@jini-ai/agentic 0.3.7 → 0.4.1

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

@@ -51,27 +51,39 @@ export interface PageDriver {
      * @param filter - Optional role/substring narrowing.
      * @returns Descriptors. `label` may be raw page text; the executor normalizes it.
      */
-    findElements(filter: FindElementsFilter): Promise<readonly AgentElementDescriptor[]>;
+    findElements(_required: Record<string, never>, filter?: FindElementsFilter): Promise<readonly AgentElementDescriptor[]>;
     /**
      * The pages this host can navigate to.
      *
      * An allowlist, so `page.navigate` refuses anything the host has not published rather than
      * accepting a caller-supplied URL.
      */
-    listPages(): Promise<readonly PageSummary[]>;
+    listPages(_required: Record<string, never>, _optional?: Record<string, never>): Promise<readonly PageSummary[]>;
     /**
      * The attributes of a field, for the fill guard.
      *
      * @param handle - A validated element handle.
      * @returns The field's attributes, or `null` when the handle does not resolve to an input.
      */
-    describeField(handle: string): Promise<FieldDescriptor | null>;
+    describeField(required: {
+        handle: string;
+    }, _optional?: Record<string, never>): Promise<FieldDescriptor | null>;
     /** Draws a transient marker. The executor has already clamped `durationMs`. */
-    highlight(handle: string, durationMs: number): Promise<void>;
-    scrollTo(handle: string): Promise<void>;
-    click(handle: string): Promise<void>;
+    highlight(required: {
+        handle: string;
+        durationMs: number;
+    }, _optional?: Record<string, never>): Promise<void>;
+    scrollTo(required: {
+        handle: string;
+    }, _optional?: Record<string, never>): Promise<void>;
+    click(required: {
+        handle: string;
+    }, _optional?: Record<string, never>): Promise<void>;
     /** Called only after the fill guard has passed. */
-    fill(handle: string, text: string): Promise<void>;
+    fill(required: {
+        handle: string;
+        text: string;
+    }, _optional?: Record<string, never>): Promise<void>;
     /**
      * Chooses — or, in a multi-select, removes — an option in a dropdown, matching visible text
      * before value.
@@ -89,9 +101,16 @@ export interface PageDriver {
      * @throws When the handle is not a dropdown, when no option matches, or when `selected: false`
      * is requested on a single-select.
      */
-    selectOption(handle: string, option: string, selected?: boolean): Promise<void>;
+    selectOption(required: {
+        handle: string;
+        option: string;
+    }, optional?: {
+        selected?: boolean | undefined;
+    }): Promise<void>;
     /** Called only after `page` has been checked against {@link PageDriver.listPages}. */
-    navigate(page: string): Promise<void>;
+    navigate(required: {
+        page: string;
+    }, _optional?: Record<string, never>): Promise<void>;
     /**
      * What the element currently is: its live text, a field's contents, checked/disabled/visible.
      *
@@ -103,7 +122,9 @@ export interface PageDriver {
      * @returns The raw state, or `null` when the handle no longer resolves — which is itself an
      * observation (a click that removed its own target), not an error.
      */
-    describeState?(handle: string): Promise<AgentElementRawState | null>;
+    describeState?(required: {
+        handle: string;
+    }, _optional?: Record<string, never>): Promise<AgentElementRawState | null>;
     /**
      * Resolves once the surface has finished reacting to the write that just happened.
      *
@@ -115,6 +136,6 @@ export interface PageDriver {
      * Implementations must be bounded: a hidden tab suspends animation frames indefinitely, so a
      * naive "wait for the next frame" never resolves for exactly the background agent this is for.
      */
-    settle?(): Promise<void>;
+    settle?(_required: Record<string, never>, _optional?: Record<string, never>): Promise<void>;
 }
 //# sourceMappingURL=page-driver.d.ts.map

package/dist/core/page-executor.d.ts

@@ -68,7 +68,9 @@ export interface PageWriteObservation {
  * 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 declare function projectElementState(raw: AgentElementRawState): AgentElementState;
+export declare function projectElementState({ raw }: {
+    raw: AgentElementRawState;
+}, _optional?: Record<string, never>): AgentElementState;
 /**
  * What page is showing and how much it publishes, at one moment — the before/after pair
  * `page.navigate` reports. Not {@link PageSummary} (`page-driver.js`): that names one entry in the
@@ -90,5 +92,9 @@ export interface PageActivitySnapshot {
  * 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 declare function executePageCapability(driver: PageDriver, capabilityId: string, input: Record<string, unknown>): Promise<unknown>;
+export declare function executePageCapability({ driver, capabilityId, input }: {
+    driver: PageDriver;
+    capabilityId: string;
+    input: Record<string, unknown>;
+}, _optional?: Record<string, never>): Promise<unknown>;
 //# sourceMappingURL=page-executor.d.ts.map

package/dist/core/page-executor.js

@@ -34,7 +34,7 @@ export const MAX_HIGHLIGHT_MS = 15_000;
 export const MAX_STATEFUL_ELEMENTS = 50;
 function requireHandle(input, key) {
     const value = input[key];
-    if (typeof value !== 'string' || !isValidElementHandle(value)) {
+    if (typeof value !== 'string' || !isValidElementHandle({ handle: 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');
     }
@@ -56,8 +56,8 @@ function isAgentElementRole(value) {
  * 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);
+export function projectElementState({ raw }, _optional = {}) {
+    const text = normalizeAgentLabel({ raw: 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`,
@@ -68,7 +68,7 @@ export function projectElementState(raw) {
     // 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;
+    const refusal = raw.field !== undefined ? findFieldReadRefusal({ field: 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"
@@ -77,7 +77,7 @@ export function projectElementState(raw) {
         ? undefined
         : raw.field === undefined
             ? 'this element reported contents without the attributes needed to check them for secrets'
-            : refusal !== null ? describeFieldReadRefusal(refusal) : undefined;
+            : refusal !== null ? describeFieldReadRefusal({ refusal }) : undefined;
     const base = {
         text: withheldText === undefined ? text.text : '',
         textTruncated: withheldText === undefined ? text.truncated : false,
@@ -88,7 +88,7 @@ export function projectElementState(raw) {
         // 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) }
+            ? { options: raw.options.map((option) => normalizeAgentLabel({ raw: option }).text) }
             : {}),
     };
     if (raw.value === undefined)
@@ -100,8 +100,8 @@ export function projectElementState(raw) {
         };
     }
     if (refusal !== null)
-        return { ...base, valueWithheld: describeFieldReadRefusal(refusal) };
-    const value = normalizeAgentLabel(raw.value);
+        return { ...base, valueWithheld: describeFieldReadRefusal({ refusal }) };
+    const value = normalizeAgentLabel({ raw: raw.value });
     return { ...base, value: value.text, valueTruncated: value.truncated };
 }
 /**
@@ -133,17 +133,17 @@ function sameElementState(a, b) {
  * not report state.
  */
 async function observeElement(driver, handle) {
-    if (driver.describeState === undefined || !isValidElementHandle(handle))
+    if (driver.describeState === undefined || !isValidElementHandle({ handle }))
         return undefined;
-    const raw = await driver.describeState(handle);
-    return raw === null ? undefined : projectElementState(raw);
+    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();
+        await driver.settle({});
     const after = await observeElement(driver, handle);
     return {
         ...(before !== undefined ? { before } : {}),
@@ -158,7 +158,7 @@ async function observeWrite(driver, handle, write) {
  * 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({});
+    const elements = await driver.findElements({}, {});
     return {
         page: elements.find((element) => element.page !== undefined)?.page,
         elementCount: elements.length,
@@ -175,11 +175,11 @@ async function summarizePage(driver) {
  * 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) {
+export async function executePageCapability({ driver, capabilityId, input }, _optional = {}) {
     const capability = PAGE_CAPABILITIES.find((entry) => entry.id === capabilityId);
     if (capability === undefined)
         throw new Error(`unknown page capability: ${capabilityId}`);
-    const inputError = findCapabilityInputError(capability, input);
+    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
@@ -202,11 +202,11 @@ export async function executePageCapability(driver, capabilityId, input) {
                 ...(isAgentElementRole(role) ? { role } : {}),
                 ...(typeof input['query'] === 'string' ? { query: input['query'] } : {}),
             };
-            const [found, rawPages] = await Promise.all([driver.findElements(filter), driver.listPages()]);
+            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 label = normalizeAgentLabel({ raw: element.label });
                 const base = {
                     handle: element.handle,
                     role: element.role,
@@ -224,7 +224,7 @@ export async function executePageCapability(driver, capabilityId, input) {
             // every `data-agent-page` label short and clean.
             const pages = rawPages.map((page) => ({
                 id: page.id,
-                label: normalizeAgentLabel(page.label).text,
+                label: normalizeAgentLabel({ raw: page.label }).text,
             }));
             return {
                 elements,
@@ -239,17 +239,17 @@ export async function executePageCapability(driver, capabilityId, input) {
         case 'page.highlight': {
             const handle = requireHandle(input, 'handle');
             const durationMs = clampHighlightDuration(input['durationMs']);
-            await driver.highlight(handle, durationMs);
+            await driver.highlight({ handle, durationMs });
             return { highlighted: handle, durationMs };
         }
         case 'page.scroll_to': {
             const handle = requireHandle(input, 'handle');
-            await driver.scrollTo(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));
+            const observation = await observeWrite(driver, handle, () => driver.click({ handle }));
             return { clicked: handle, ...observation };
         }
         case 'page.fill': {
@@ -259,14 +259,14 @@ export async function executePageCapability(driver, capabilityId, input) {
             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);
+            const field = await driver.describeField({ handle });
             if (field === null)
                 throw new Error(`"${handle}" is not a fillable field`);
-            const refusal = findFieldFillRefusal(field);
+            const refusal = findFieldFillRefusal({ field });
             if (refusal !== null) {
-                throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal(refusal)}`);
+                throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal({ refusal })}`);
             }
-            const observation = await observeWrite(driver, handle, () => driver.fill(handle, text));
+            const observation = await observeWrite(driver, handle, () => driver.fill({ handle, text }));
             return { filled: handle, ...observation };
         }
         case 'page.select_option': {
@@ -279,7 +279,7 @@ export async function executePageCapability(driver, capabilityId, input) {
             // 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));
+            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 };
@@ -287,7 +287,7 @@ export async function executePageCapability(driver, capabilityId, input) {
         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();
+            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-
@@ -301,14 +301,14 @@ export async function executePageCapability(driver, capabilityId, input) {
                 // 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})`);
+                const safePage = normalizeAgentLabel({ raw: page }).text;
+                const safePages = pages.map((candidate) => `${normalizeAgentLabel({ raw: candidate.id }).text} (${normalizeAgentLabel({ raw: 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);
+            await driver.navigate({ page });
             if (driver.settle !== undefined)
-                await driver.settle();
+                await driver.settle({});
             const after = await summarizePage(driver);
             return { navigatedTo: page, before, after };
         }

package/dist/core/webmcp.d.ts

@@ -27,7 +27,7 @@
  *    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)`.
+ *    `modelContext.registerTool({ tool: 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
@@ -68,7 +68,7 @@ export interface WebMcpToolRegistration {
      * `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)`.
+     * object a caller can pass straight through: `modelContext.registerTool({ tool: reg }, reg.registerOptions)`.
      */
     readonly registerOptions?: WebMcpRegisterToolOptions;
 }
@@ -146,10 +146,15 @@ export interface ToWebMcpToolOptions {
 export declare class WebMcpConfirmationRequiredError extends Error {
     readonly capabilityId: string;
     readonly reason: 'declined' | 'no-handler';
-    constructor(capabilityId: string, reason: 'declined' | 'no-handler');
+    constructor({ capabilityId, reason }: {
+        capabilityId: string;
+        reason: 'declined' | 'no-handler';
+    }, _optional?: Record<string, never>);
 }
 /** 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;
+export declare function isValidWebMcpToolName({ name }: {
+    name: string;
+}, _optional?: Record<string, never>): 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
@@ -157,7 +162,9 @@ export declare function isValidWebMcpToolName(name: string): boolean;
  */
 export declare class InvalidWebMcpToolNameError extends Error {
     readonly capabilityId: string;
-    constructor(capabilityId: string);
+    constructor({ capabilityId }: {
+        capabilityId: string;
+    }, _optional?: Record<string, never>);
 }
 /**
  * Projects one capability into a WebMCP registration.
@@ -173,7 +180,7 @@ export declare class InvalidWebMcpToolNameError extends Error {
  * 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
+ * @param execute - Runs the capability. Receives `{ id, args }`, with args 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`.
@@ -183,7 +190,13 @@ export declare class InvalidWebMcpToolNameError extends Error {
  * @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;
+export declare function toWebMcpTool({ capability, execute }: {
+    capability: CapabilityDef;
+    execute: (required: {
+        id: string;
+        args: Record<string, unknown>;
+    }) => Promise<unknown>;
+}, options?: ToWebMcpToolOptions): WebMcpToolRegistration;
 /**
  * Projects a whole manifest.
  *
@@ -198,5 +211,11 @@ export declare function toWebMcpTool(capability: CapabilityDef, execute: (id: st
  * @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[];
+export declare function toWebMcpTools({ capabilities, execute }: {
+    capabilities: readonly CapabilityDef[];
+    execute: (required: {
+        id: string;
+        args: Record<string, unknown>;
+    }) => Promise<unknown>;
+}, options?: ToWebMcpToolOptions): readonly WebMcpToolRegistration[];
 //# sourceMappingURL=webmcp.d.ts.map

package/dist/core/webmcp.js

@@ -27,7 +27,7 @@
  *    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)`.
+ *    `modelContext.registerTool({ tool: 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
@@ -52,7 +52,7 @@ import { findCapabilityInputError } from './capability.js';
 export class WebMcpConfirmationRequiredError extends Error {
     capabilityId;
     reason;
-    constructor(capabilityId, reason) {
+    constructor({ capabilityId, reason }, _optional = {}) {
         super(reason === 'declined'
             ? `WebMCP: "${capabilityId}" was declined by the user`
             : `WebMCP: "${capabilityId}" requires confirmation, but no requestUserInteraction handler was supplied`);
@@ -69,7 +69,7 @@ export class WebMcpConfirmationRequiredError extends Error {
  */
 const WEBMCP_TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
 /** Whether `name` satisfies the spec's tool-name rule. Exported so a caller can pre-check a manifest without registering anything. */
-export function isValidWebMcpToolName(name) {
+export function isValidWebMcpToolName({ name }, _optional = {}) {
     return WEBMCP_TOOL_NAME_PATTERN.test(name);
 }
 /**
@@ -79,7 +79,7 @@ export function isValidWebMcpToolName(name) {
  */
 export class InvalidWebMcpToolNameError extends Error {
     capabilityId;
-    constructor(capabilityId) {
+    constructor({ capabilityId }, _optional = {}) {
         super(`WebMCP: capability id "${capabilityId}" is not a valid tool name — the spec requires 1-128 `
             + 'ASCII alphanumeric characters plus "_", "-", "." '
             + '(https://webmachinelearning.github.io/webmcp/#dom-modelcontext-registertool)');
@@ -101,7 +101,7 @@ export class InvalidWebMcpToolNameError extends Error {
  * 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
+ * @param execute - Runs the capability. Receives `{ id, args }`, with args 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`.
@@ -111,9 +111,9 @@ export class InvalidWebMcpToolNameError extends Error {
  * @throws {@link WebMcpConfirmationRequiredError} from `execute`, when confirmation is required
  * and is either declined or unobtainable.
  */
-export function toWebMcpTool(capability, execute, options = {}) {
-    if (!isValidWebMcpToolName(capability.id)) {
-        throw new InvalidWebMcpToolNameError(capability.id);
+export function toWebMcpTool({ capability, execute }, options = {}) {
+    if (!isValidWebMcpToolName({ name: capability.id })) {
+        throw new InvalidWebMcpToolNameError({ capabilityId: capability.id });
     }
     const { title, annotations, signal, exposedTo } = options;
     const resolvedAnnotations = {
@@ -133,21 +133,21 @@ export function toWebMcpTool(capability, execute, options = {}) {
             // Schema-on-error, matching page-executor.ts's discipline for page.* — WebMCP defines no
             // input validation of its own, so a wrong-schema call would otherwise reach `execute` (or a
             // confirmation prompt for one) with bad arguments instead of a same-turn correctable error.
-            const inputError = findCapabilityInputError(capability, input);
+            const inputError = findCapabilityInputError({ capability, input });
             if (inputError !== null) {
                 throw new Error(`${capability.id}: ${inputError}. Expected input: ${JSON.stringify(capability.inputSchema)}`);
             }
             if (capability.requiresConfirmation === true) {
                 const { requestUserInteraction } = options;
                 if (!requestUserInteraction) {
-                    throw new WebMcpConfirmationRequiredError(capability.id, 'no-handler');
+                    throw new WebMcpConfirmationRequiredError({ capabilityId: capability.id, reason: 'no-handler' });
                 }
                 const approved = await requestUserInteraction({ capability, args: input });
                 if (approved !== true) {
-                    throw new WebMcpConfirmationRequiredError(capability.id, 'declined');
+                    throw new WebMcpConfirmationRequiredError({ capabilityId: capability.id, reason: 'declined' });
                 }
             }
-            return execute(capability.id, input);
+            return execute({ id: capability.id, args: input });
         },
         annotations: resolvedAnnotations,
         ...(registerOptions !== undefined ? { registerOptions } : {}),
@@ -167,7 +167,7 @@ export function toWebMcpTool(capability, execute, options = {}) {
  * @throws {@link InvalidWebMcpToolNameError} synchronously, for the first capability whose `id`
  * cannot be a WebMCP tool name.
  */
-export function toWebMcpTools(capabilities, execute, options = {}) {
-    return capabilities.map((capability) => toWebMcpTool(capability, execute, options));
+export function toWebMcpTools({ capabilities, execute }, options = {}) {
+    return capabilities.map((capability) => toWebMcpTool({ capability, execute }, options));
 }
 //# sourceMappingURL=webmcp.js.map

package/dist/index.d.ts

@@ -2,6 +2,36 @@
  * Compatibility root — re-exports `./core` unchanged so existing `from '@jini-ai/agentic'`
  * imports keep resolving. New code should prefer the explicit `@jini-ai/agentic/core` import;
  * see `core/README.md` for why this package is split the way it is.
+
+ * Archived provenance rationale:
+ * ## The DOM split (why this package has two entry points)
+ *
+ * Everything under `src/` except `src/dom/` compiles under `tsconfig.json`, which extends the repo's
+ * `tsconfig.base.json` unmodified (`lib: ["ES2023"]`, no `DOM`) and **excludes `src/dom` entirely**.
+ * `src/dom/` compiles separately under `tsconfig.dom.json`, the only config in this package with
+ * `DOM`/`DOM.Iterable` in `lib`.
+ *
+ * This is a compile-time guarantee, not a convention: a `document`/`window` reference anywhere
+ * outside `src/dom/**` fails `tsc -p tsconfig.json` with "Cannot find name 'document'" (verified
+ * during the 2026-07-26 extraction — see the extraction's report for the exact command and error
+ * text). That is what proves the policy layer (`page-executor.ts`'s guards, refusals, and
+ * allowlist-enforcement) cannot quietly reach into a live page; only `src/dom/dom-page-driver.ts`,
+ * the one `PageDriver` implementation that legitimately needs a DOM, may.
+ *
+ * Two `package.json` exports follow the same split:
+ *
+ * - `.` (`dist/index.d.ts`/`dist/index.js`, built by `tsconfig.json`) — the DOM-free vocabulary,
+ *   policy gate, and protocol projections. What `@jini/chat-core`, `@jini/daemon` (structurally, see
+ *   below), and (once §5 of the plan lands) `@jini/ui` depend on.
+ * - `./dom` (`dist/dom/index.d.ts`/`dist/dom/index.js`, built by `tsconfig.dom.json`) — the browser
+ *   `PageDriver`. What `@jini/chat-react` depends on.
+ *
+ * `scripts/check-engine-boundaries.ts` R2 normally allows only bare `@jini/<name>` imports (one
+ * entry point per package), with a single named exception for `@jini/core/internal`. This extraction
+ * added a second, identically-gated exception for the exact literal `@jini/agentic/dom` — not a
+ * pattern — because `@jini/chat-react` genuinely needs the DOM half and there is no third package for
+ * it to live in without recreating the sprawl this plan exists to reduce (23 packages vs. a locked
+ * 14). See that script's own module doc for the up-to-date rule list.
  */
 export * from './core/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,6 +2,36 @@
  * Compatibility root — re-exports `./core` unchanged so existing `from '@jini-ai/agentic'`
  * imports keep resolving. New code should prefer the explicit `@jini-ai/agentic/core` import;
  * see `core/README.md` for why this package is split the way it is.
+
+ * Archived provenance rationale:
+ * ## The DOM split (why this package has two entry points)
+ *
+ * Everything under `src/` except `src/dom/` compiles under `tsconfig.json`, which extends the repo's
+ * `tsconfig.base.json` unmodified (`lib: ["ES2023"]`, no `DOM`) and **excludes `src/dom` entirely**.
+ * `src/dom/` compiles separately under `tsconfig.dom.json`, the only config in this package with
+ * `DOM`/`DOM.Iterable` in `lib`.
+ *
+ * This is a compile-time guarantee, not a convention: a `document`/`window` reference anywhere
+ * outside `src/dom/**` fails `tsc -p tsconfig.json` with "Cannot find name 'document'" (verified
+ * during the 2026-07-26 extraction — see the extraction's report for the exact command and error
+ * text). That is what proves the policy layer (`page-executor.ts`'s guards, refusals, and
+ * allowlist-enforcement) cannot quietly reach into a live page; only `src/dom/dom-page-driver.ts`,
+ * the one `PageDriver` implementation that legitimately needs a DOM, may.
+ *
+ * Two `package.json` exports follow the same split:
+ *
+ * - `.` (`dist/index.d.ts`/`dist/index.js`, built by `tsconfig.json`) — the DOM-free vocabulary,
+ *   policy gate, and protocol projections. What `@jini/chat-core`, `@jini/daemon` (structurally, see
+ *   below), and (once §5 of the plan lands) `@jini/ui` depend on.
+ * - `./dom` (`dist/dom/index.d.ts`/`dist/dom/index.js`, built by `tsconfig.dom.json`) — the browser
+ *   `PageDriver`. What `@jini/chat-react` depends on.
+ *
+ * `scripts/check-engine-boundaries.ts` R2 normally allows only bare `@jini/<name>` imports (one
+ * entry point per package), with a single named exception for `@jini/core/internal`. This extraction
+ * added a second, identically-gated exception for the exact literal `@jini/agentic/dom` — not a
+ * pattern — because `@jini/chat-react` genuinely needs the DOM half and there is no third package for
+ * it to live in without recreating the sprawl this plan exists to reduce (23 packages vs. a locked
+ * 14). See that script's own module doc for the up-to-date rule list.
  */
 export * from './core/index.js';
 //# sourceMappingURL=index.js.map

package/dist/skills/install/archive.d.ts

@@ -0,0 +1,8 @@
+import type { ArchiveReaderPort } from "./ports.js";
+import { type SkillUploadFile } from "./validation.js";
+/** Read bounded archive content only; paths are validated before opening any entry stream. */
+export declare function readSkillArchive({ base64, archiveReader }: {
+    base64: string;
+    archiveReader: ArchiveReaderPort;
+}, _optional?: Record<string, never>): Promise<SkillUploadFile[]>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/skills/install/archive.js

@@ -0,0 +1,47 @@
+import { decodeSkillBase64, MAX_SKILL_BYTES, MAX_SKILL_FILES, MAX_SKILL_FILE_BYTES, SkillInputError, validateSkillPath } from "./validation.js";
+/** Read bounded archive content only; paths are validated before opening any entry stream. */
+export async function readSkillArchive({ base64, archiveReader }, _optional = {}) {
+    try {
+        const reader = await archiveReader.open({ bytes: decodeSkillBase64({ value: base64 }) });
+        const files = [];
+        let total = 0;
+        let count = 0;
+        try {
+            for await (const entry of reader.entries) {
+                if (++count > MAX_SKILL_FILES)
+                    throw new SkillInputError({ message: "A skill archive may contain at most 256 entries." });
+                validateSkillPath({ filePath: entry.path.replace(/\/$/, "") });
+                if (entry.kind !== "file" && entry.kind !== "directory")
+                    throw new SkillInputError({ message: "Skill archives may contain only regular files and directories." });
+                if (entry.kind === "directory")
+                    continue;
+                if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX_SKILL_FILE_BYTES)
+                    throw new SkillInputError({ message: "Skill archive file exceeds 1 MiB." });
+                const chunks = [];
+                let size = 0;
+                {
+                    for await (const chunk of entry.read({})) {
+                        size += chunk.length;
+                        total += chunk.length;
+                        if (size > MAX_SKILL_FILE_BYTES || total > MAX_SKILL_BYTES)
+                            throw new SkillInputError({ message: "Skill archive exceeds its decompressed size limit." });
+                        chunks.push(Buffer.from(chunk));
+                    }
+                }
+                if (size !== entry.size)
+                    throw new SkillInputError({ message: "Skill archive file size does not match its metadata." });
+                files.push({ path: entry.path, contentBase64: Buffer.concat(chunks).toString("base64") });
+            }
+            return files;
+        }
+        finally {
+            reader.close({});
+        }
+    }
+    catch (error) {
+        if (error instanceof SkillInputError)
+            throw error;
+        throw new SkillInputError({ message: "Could not read skill ZIP. Use a valid ZIP with regular files only." });
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/skills/install/fetch-adapter.d.ts

@@ -0,0 +1,6 @@
+import type { SkillFetchPort } from './ports.js';
+/** Wrap an explicitly supplied native fetch without adding transport defaults or changing responses. */
+export declare function createSkillFetchAdapter(required: {
+    fetch: typeof fetch;
+}, _optional?: Record<string, never>): SkillFetchPort;
+//# sourceMappingURL=fetch-adapter.d.ts.map

package/dist/skills/install/fetch-adapter.js

@@ -0,0 +1,6 @@
+/** Wrap an explicitly supplied native fetch without adding transport defaults or changing responses. */
+export function createSkillFetchAdapter(required, _optional = {}) {
+    const fetchImpl = required.fetch;
+    return ({ url }, optional = {}) => fetchImpl(url, optional);
+}
+//# sourceMappingURL=fetch-adapter.js.map