@jini-ai/agentic 0.3.7 → 0.4.0

package/dist/core/guards.d.ts

@@ -57,7 +57,9 @@ export type FieldRefusal = FieldReadRefusal | 'not-text' | 'read-only' | 'disabl
  * @param field - The field's attributes.
  * @returns The first secrecy refusal, or `null` when the value may be reported.
  */
-export declare function findFieldReadRefusal(field: FieldDescriptor): FieldReadRefusal | null;
+export declare function findFieldReadRefusal({ field }: {
+    field: FieldDescriptor;
+}, _optional?: Record<string, never>): FieldReadRefusal | null;
 /**
  * Why an automated fill must be refused for this field, or `null` when it is safe to write.
  *
@@ -70,11 +72,17 @@ export declare function findFieldReadRefusal(field: FieldDescriptor): FieldReadR
  * @param field - The field's attributes.
  * @returns The first refusal reason, or `null` when the field may be filled.
  */
-export declare function findFieldFillRefusal(field: FieldDescriptor): FieldRefusal | null;
+export declare function findFieldFillRefusal({ field }: {
+    field: FieldDescriptor;
+}, _optional?: Record<string, never>): FieldRefusal | null;
 /** Model-readable reason for a refusal, so a blocked fill explains itself instead of failing opaquely. */
-export declare function describeFieldRefusal(refusal: FieldRefusal): string;
+export declare function describeFieldRefusal({ refusal }: {
+    refusal: FieldRefusal;
+}, _optional?: Record<string, never>): string;
 /** Model-readable reason a value was withheld, so a caller knows the field has contents it may not see rather than assuming it is empty. */
-export declare function describeFieldReadRefusal(refusal: FieldReadRefusal): string;
+export declare function describeFieldReadRefusal({ refusal }: {
+    refusal: FieldReadRefusal;
+}, _optional?: Record<string, never>): string;
 /** Default cap on page-authored text handed to a model. */
 export declare const MAX_AGENT_LABEL_LENGTH = 200;
 export interface NormalizedLabel {
@@ -92,5 +100,9 @@ export interface NormalizedLabel {
  * @param maxLength - Cap, defaulting to {@link MAX_AGENT_LABEL_LENGTH}.
  * @returns The bounded text and whether anything was cut.
  */
-export declare function normalizeAgentLabel(raw: string, maxLength?: number): NormalizedLabel;
+export declare function normalizeAgentLabel({ raw }: {
+    raw: string;
+}, { maxLength }?: {
+    maxLength?: number | undefined;
+}): NormalizedLabel;
 //# sourceMappingURL=guards.d.ts.map

package/dist/core/guards.js

@@ -77,7 +77,7 @@ const NON_TEXT_TYPES = new Set(['checkbox', 'radio', 'submit', 'reset', 'button'
  * @param field - The field's attributes.
  * @returns The first secrecy refusal, or `null` when the value may be reported.
  */
-export function findFieldReadRefusal(field) {
+export function findFieldReadRefusal({ field }, _optional = {}) {
     const type = field.type?.toLowerCase();
     if (type !== undefined && DENIED_TYPES.has(type))
         return 'denied-type';
@@ -119,8 +119,8 @@ export function findFieldReadRefusal(field) {
  * @param field - The field's attributes.
  * @returns The first refusal reason, or `null` when the field may be filled.
  */
-export function findFieldFillRefusal(field) {
-    const secrecy = findFieldReadRefusal(field);
+export function findFieldFillRefusal({ field }, _optional = {}) {
+    const secrecy = findFieldReadRefusal({ field });
     if (secrecy !== null)
         return secrecy;
     const type = field.type?.toLowerCase();
@@ -146,11 +146,11 @@ const FIELD_READ_REFUSAL_MESSAGES = {
     'suspicious-name': 'this field name indicates a secret or anti-forgery token',
 };
 /** Model-readable reason for a refusal, so a blocked fill explains itself instead of failing opaquely. */
-export function describeFieldRefusal(refusal) {
+export function describeFieldRefusal({ refusal }, _optional = {}) {
     return FIELD_REFUSAL_MESSAGES[refusal];
 }
 /** Model-readable reason a value was withheld, so a caller knows the field has contents it may not see rather than assuming it is empty. */
-export function describeFieldReadRefusal(refusal) {
+export function describeFieldReadRefusal({ refusal }, _optional = {}) {
     return FIELD_READ_REFUSAL_MESSAGES[refusal];
 }
 /** Default cap on page-authored text handed to a model. */
@@ -176,7 +176,7 @@ const CONTROL_AND_BIDI =
  * @param maxLength - Cap, defaulting to {@link MAX_AGENT_LABEL_LENGTH}.
  * @returns The bounded text and whether anything was cut.
  */
-export function normalizeAgentLabel(raw, maxLength = MAX_AGENT_LABEL_LENGTH) {
+export function normalizeAgentLabel({ raw }, { maxLength = MAX_AGENT_LABEL_LENGTH } = {}) {
     const stripped = raw.replace(CONTROL_AND_BIDI, ' ');
     const collapsed = stripped.replace(/\s+/g, ' ').trim();
     if (collapsed.length <= maxLength)

package/dist/core/handle.d.ts

@@ -1,13 +1,13 @@
 /**
  * @module handle
  *
- * `agentHandle('save')` — the attribute props a component spreads onto its root element to
+ * `agentHandle({ handle: 'save' })` — the attribute props a component spreads onto its root element to
  * publish itself under this package's `data-agent-*` markup convention (see
  * `element-handles.ts`), without the caller having to know the attribute names or re-derive the
  * handle-validity rule itself.
  *
  * Deliberately pure data, no DOM: this returns a plain object of string attributes, spreadable by
- * React (`<button {...agentHandle('save')}>`), Vue, Svelte, or any renderer that accepts arbitrary
+ * React (`<button {...agentHandle({ handle: 'save' })}>`), Vue, Svelte, or any renderer that accepts arbitrary
  * attribute props on an element. That is what lets it live in this package's universal root
  * rather than `./dom` — nothing here touches `document` or any browser global.
  */
@@ -37,7 +37,9 @@ export type AgentHandleProps = {
  * @throws If `handle` is not a valid element handle — never publishes a handle a caller (`page.*`
  *   capabilities, `resolveHandleSelector`) could not later resolve.
  */
-export declare function agentHandle(handle: string, options?: AgentHandleOptions): AgentHandleProps;
+export declare function agentHandle({ handle }: {
+    handle: string;
+}, options?: AgentHandleOptions): AgentHandleProps;
 /**
  * The handle for one sub-element published under `base` — `<base>-<action>`.
  *
@@ -54,9 +56,14 @@ export declare function agentHandle(handle: string, options?: AgentHandleOptions
  * @returns `<base>-<action>`.
  * @complexity O(1).
  */
-export declare function agentSubHandle(base: string, action: string): string;
+export declare function agentSubHandle({ base, action }: {
+    base: string;
+    action: string;
+}, _optional?: Record<string, never>): string;
 /** What to publish about one sub-element — see {@link agentHandleProps}. */
 export interface AgentHandlePropsOptions extends AgentHandleOptions {
+    /** Host-published base handle. Omit to leave the element unpublished. */
+    readonly base?: string | undefined;
     /**
      * The sub-element's name, appended to `base` via {@link agentSubHandle}. Omit when the element
      * IS `base` — the component's own root.
@@ -85,5 +92,5 @@ export interface AgentHandlePropsOptions extends AgentHandleOptions {
  *   answering to a handle the host never wrote.
  * @complexity O(1).
  */
-export declare function agentHandleProps(base: string | undefined, options?: AgentHandlePropsOptions): AgentHandleProps | Record<string, never>;
+export declare function agentHandleProps(_required: Record<string, never>, options?: AgentHandlePropsOptions): AgentHandleProps | Record<string, never>;
 //# sourceMappingURL=handle.d.ts.map

package/dist/core/handle.js

@@ -1,13 +1,13 @@
 /**
  * @module handle
  *
- * `agentHandle('save')` — the attribute props a component spreads onto its root element to
+ * `agentHandle({ handle: 'save' })` — the attribute props a component spreads onto its root element to
  * publish itself under this package's `data-agent-*` markup convention (see
  * `element-handles.ts`), without the caller having to know the attribute names or re-derive the
  * handle-validity rule itself.
  *
  * Deliberately pure data, no DOM: this returns a plain object of string attributes, spreadable by
- * React (`<button {...agentHandle('save')}>`), Vue, Svelte, or any renderer that accepts arbitrary
+ * React (`<button {...agentHandle({ handle: 'save' })}>`), Vue, Svelte, or any renderer that accepts arbitrary
  * attribute props on an element. That is what lets it live in this package's universal root
  * rather than `./dom` — nothing here touches `document` or any browser global.
  */
@@ -24,8 +24,8 @@ import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, A
  * @throws If `handle` is not a valid element handle — never publishes a handle a caller (`page.*`
  *   capabilities, `resolveHandleSelector`) could not later resolve.
  */
-export function agentHandle(handle, options = {}) {
-    if (!isValidElementHandle(handle)) {
+export function agentHandle({ handle }, options = {}) {
+    if (!isValidElementHandle({ handle })) {
         throw new Error(`invalid element handle "${handle.slice(0, 128)}": `
             + 'handles are lowercase words joined by single hyphens, and are never CSS selectors');
     }
@@ -54,7 +54,7 @@ export function agentHandle(handle, options = {}) {
  * @returns `<base>-<action>`.
  * @complexity O(1).
  */
-export function agentSubHandle(base, action) {
+export function agentSubHandle({ base, action }, _optional = {}) {
     return `${base}-${action}`;
 }
 /**
@@ -79,10 +79,11 @@ export function agentSubHandle(base, action) {
  *   answering to a handle the host never wrote.
  * @complexity O(1).
  */
-export function agentHandleProps(base, options = {}) {
+export function agentHandleProps(_required, options = {}) {
+    const { base } = options;
     if (base === undefined)
         return {};
-    const { action, ...rest } = options;
-    return agentHandle(action === undefined ? base : agentSubHandle(base, action), rest);
+    const { action, base: _base, ...rest } = options;
+    return agentHandle({ handle: action === undefined ? base : agentSubHandle({ base, action }) }, rest);
 }
 //# sourceMappingURL=handle.js.map

package/dist/core/index.d.ts

@@ -15,7 +15,7 @@
  * preview in a sandboxed frame. The verbs are identical either way. Also not here: any product's
  * OWN capabilities (`@jini-ai/chat-core`'s `chat.*` verbs stay in chat-core, which depends on this
  * package for the vocabulary rather than the other way around) — see this package's
- * source-map.md for why the split is real rather than a wholesale relocation.
+ * archived provenance ledger for why the split is real rather than a wholesale relocation.
  */
 export { findCapability, findCapabilityInputError, availableCapabilities, type CapabilityDef, type CapabilityInputSchema, type CapabilityRisk, type CapabilitySurface, } from './capability.js';
 export type { PageDriver, FindElementsFilter, PageSummary } from './page-driver.js';
@@ -72,4 +72,5 @@ export { toAgUiTool, toAgUiTools, createAgUiToolResult, AG_UI_TOOL_CALL_EVENTS,
  */
 export { createGenUiEncoder, type GenUiEncodeContext, type GenUiEncoder, type GenUiAgentMessageEvent, type GenUiEvent, type GenUiEventBase, type GenUiEventKind, type GenUiRunLifecycleEvent, type GenUiStateUpdateEvent, type GenUiSurfaceRequestedEvent, type GenUiSurfaceRespondedEvent, type GenUiToolCallEvent, } from './gen-ui/index.js';
 export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_VIEW_NOTIFICATIONS, MCP_UI_HOST_REQUESTS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcNotification, type JsonRpcResponse, type JsonRpcError, } from './mcp-ui-apps.js';
+export { defaultAgenticMessages } from "./messages.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -15,7 +15,7 @@
  * preview in a sandboxed frame. The verbs are identical either way. Also not here: any product's
  * OWN capabilities (`@jini-ai/chat-core`'s `chat.*` verbs stay in chat-core, which depends on this
  * package for the vocabulary rather than the other way around) — see this package's
- * source-map.md for why the split is real rather than a wholesale relocation.
+ * archived provenance ledger for why the split is real rather than a wholesale relocation.
  */
 export { findCapability, findCapabilityInputError, availableCapabilities, } from './capability.js';
 export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, } from './page-executor.js';
@@ -71,4 +71,5 @@ export { toAgUiTool, toAgUiTools, createAgUiToolResult, AG_UI_TOOL_CALL_EVENTS,
  */
 export { createGenUiEncoder, } from './gen-ui/index.js';
 export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_VIEW_NOTIFICATIONS, MCP_UI_HOST_REQUESTS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, } from './mcp-ui-apps.js';
+export { defaultAgenticMessages } from "./messages.js";
 //# sourceMappingURL=index.js.map

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

@@ -39,5 +39,8 @@
  * search then walks the full used-set for each collision); n is a list's row/card count, which is
  * operator- or user-authored content and stays small in practice. Space O(n).
  */
-export declare function buildAgentListHandles(prefix: string, ids: readonly string[]): string[];
+export declare function buildAgentListHandles({ prefix, ids }: {
+    prefix: string;
+    ids: readonly string[];
+}, _optional?: Record<string, never>): string[];
 //# sourceMappingURL=list-handles.d.ts.map

package/dist/core/list-handles.js

@@ -39,7 +39,7 @@
  * search then walks the full used-set for each collision); n is a list's row/card count, which is
  * operator- or user-authored content and stays small in practice. Space O(n).
  */
-export function buildAgentListHandles(prefix, ids) {
+export function buildAgentListHandles({ prefix, ids }, _optional = {}) {
     const used = new Set();
     return ids.map((id, index) => {
         const slug = id.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');

package/dist/core/mcp-ui-apps.d.ts

@@ -127,12 +127,12 @@ export interface JsonRpcRequest {
     readonly jsonrpc: '2.0';
     readonly id: number | string;
     readonly method: string;
-    readonly params?: Record<string, unknown>;
+    readonly params?: Record<string, unknown> | undefined;
 }
 export interface JsonRpcNotification {
     readonly jsonrpc: '2.0';
     readonly method: string;
-    readonly params?: Record<string, unknown>;
+    readonly params?: Record<string, unknown> | undefined;
 }
 export interface JsonRpcError {
     readonly code: number;
@@ -193,9 +193,17 @@ export declare const JSON_RPC_ERROR_CODES: {
  * @param value - The raw `event.data`.
  * @returns True when the value is a well-formed JSON-RPC message.
  */
-export declare function isJsonRpcMessage(value: unknown): value is JsonRpcMessage;
+export declare function isJsonRpcMessage(required: {
+    value: unknown;
+}, _optional?: Record<string, never>): required is {
+    value: JsonRpcMessage;
+};
 /** Whether a validated message expects a response (as opposed to being a notification). */
-export declare function isJsonRpcRequest(message: JsonRpcMessage): message is JsonRpcRequest;
+export declare function isJsonRpcRequest(required: {
+    message: JsonRpcMessage;
+}, _optional?: Record<string, never>): required is {
+    message: JsonRpcRequest;
+};
 /**
  * Builds a request.
  *
@@ -204,13 +212,31 @@ export declare function isJsonRpcRequest(message: JsonRpcMessage): message is Js
  * @param method - Method name.
  * @param params - Optional parameters.
  */
-export declare function createJsonRpcRequest(id: number | string, method: string, params?: Record<string, unknown>): JsonRpcRequest;
+export declare function createJsonRpcRequest({ id, method }: {
+    id: number | string;
+    method: string;
+}, { params }?: {
+    params?: Record<string, unknown> | undefined;
+}): JsonRpcRequest;
 /** Builds a notification — no `id`, so no response is expected or allowed. */
-export declare function createJsonRpcNotification(method: string, params?: Record<string, unknown>): JsonRpcNotification;
+export declare function createJsonRpcNotification({ method }: {
+    method: string;
+}, { params }?: {
+    params?: Record<string, unknown> | undefined;
+}): JsonRpcNotification;
 /** Builds a success response for `id`. */
-export declare function createJsonRpcResult(id: number | string, result: unknown): JsonRpcResponse;
+export declare function createJsonRpcResult({ id, result }: {
+    id: number | string;
+    result: unknown;
+}, _optional?: Record<string, never>): JsonRpcResponse;
 /** Builds an error response for `id`. */
-export declare function createJsonRpcError(id: number | string, code: number, message: string, data?: unknown): JsonRpcResponse;
+export declare function createJsonRpcError({ id, code, message }: {
+    id: number | string;
+    code: number;
+    message: string;
+}, { data }?: {
+    data?: unknown;
+}): JsonRpcResponse;
 /**
  * Builds a Jini page-action request.
  *
@@ -219,5 +245,9 @@ export declare function createJsonRpcError(id: number | string, code: number, me
  * @param input - Capability arguments.
  * @returns The namespaced extension request.
  */
-export declare function createPageActionRequest(id: number | string, capabilityId: string, input: Record<string, unknown>): JsonRpcRequest;
+export declare function createPageActionRequest({ id, capabilityId, input }: {
+    id: number | string;
+    capabilityId: string;
+    input: Record<string, unknown>;
+}, _optional?: Record<string, never>): JsonRpcRequest;
 //# sourceMappingURL=mcp-ui-apps.d.ts.map

package/dist/core/mcp-ui-apps.js

@@ -190,7 +190,8 @@ function isJsonRpcErrorObject(value) {
  * @param value - The raw `event.data`.
  * @returns True when the value is a well-formed JSON-RPC message.
  */
-export function isJsonRpcMessage(value) {
+export function isJsonRpcMessage(required, _optional = {}) {
+    const { value } = required;
     if (!isRecord(value) || value['jsonrpc'] !== '2.0')
         return false;
     if ('id' in value && typeof value['id'] !== 'number' && typeof value['id'] !== 'string')
@@ -212,7 +213,8 @@ export function isJsonRpcMessage(value) {
     return hasResult || isJsonRpcErrorObject(value['error']);
 }
 /** Whether a validated message expects a response (as opposed to being a notification). */
-export function isJsonRpcRequest(message) {
+export function isJsonRpcRequest(required, _optional = {}) {
+    const { message } = required;
     return 'id' in message && typeof message.method === 'string';
 }
 /**
@@ -223,19 +225,19 @@ export function isJsonRpcRequest(message) {
  * @param method - Method name.
  * @param params - Optional parameters.
  */
-export function createJsonRpcRequest(id, method, params) {
+export function createJsonRpcRequest({ id, method }, { params } = {}) {
     return { jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) };
 }
 /** Builds a notification — no `id`, so no response is expected or allowed. */
-export function createJsonRpcNotification(method, params) {
+export function createJsonRpcNotification({ method }, { params } = {}) {
     return { jsonrpc: '2.0', method, ...(params === undefined ? {} : { params }) };
 }
 /** Builds a success response for `id`. */
-export function createJsonRpcResult(id, result) {
+export function createJsonRpcResult({ id, result }, _optional = {}) {
     return { jsonrpc: '2.0', id, result };
 }
 /** Builds an error response for `id`. */
-export function createJsonRpcError(id, code, message, data) {
+export function createJsonRpcError({ id, code, message }, { data } = {}) {
     return { jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } };
 }
 /**
@@ -246,7 +248,7 @@ export function createJsonRpcError(id, code, message, data) {
  * @param input - Capability arguments.
  * @returns The namespaced extension request.
  */
-export function createPageActionRequest(id, capabilityId, input) {
-    return createJsonRpcRequest(id, JINI_PAGE_ACTION_METHOD, { capabilityId, input });
+export function createPageActionRequest({ id, capabilityId, input }, _optional = {}) {
+    return createJsonRpcRequest({ id, method: JINI_PAGE_ACTION_METHOD }, { params: { capabilityId, input } });
 }
 //# sourceMappingURL=mcp-ui-apps.js.map

package/dist/core/messages.d.ts

@@ -0,0 +1,6 @@
+/** Model-facing defaults. Hosts can replace descriptions in the existing CapabilityDef
+ * descriptors before projecting tools; canonical descriptor IDs and policy remain unchanged. */
+export declare const defaultAgenticMessages: {
+    pageNavigateDescription: () => string;
+};
+//# sourceMappingURL=messages.d.ts.map

package/dist/core/messages.js

@@ -0,0 +1,6 @@
+/** Model-facing defaults. Hosts can replace descriptions in the existing CapabilityDef
+ * descriptors before projecting tools; canonical descriptor IDs and policy remain unchanged. */
+export const defaultAgenticMessages = {
+    pageNavigateDescription: () => 'Move to another page, named by its data-agent-page id. Only pages the host has published are reachable; arbitrary URLs are refused. Returns which page was showing before and after, and how many controls each publishes — call page.find_elements again afterwards, since every handle you hold may belong to the page you just left.',
+};
+//# sourceMappingURL=messages.js.map

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

@@ -1,14 +1,3 @@
-/**
- * @module page-capabilities
- *
- * What an outside caller may ask a *page* to do: find the tagged controls, point at one, and
- * operate it. Every verb addresses an element by its published `data-agent-element` handle —
- * never by a caller-supplied selector, and never by evaluating caller-supplied script.
- *
- * Deliberately small. `click` is unbounded by construction (it carries whatever effect that
- * button has), so the surface stays narrow and the page decides what is reachable by choosing
- * what to tag. Nothing here scans a whole document: a host names the container to search.
- */
 import type { CapabilityDef } from './capability.js';
 export declare const PAGE_CAPABILITIES: readonly CapabilityDef[];
 //# sourceMappingURL=page-capabilities.d.ts.map

package/dist/core/page-capabilities.js

@@ -1,3 +1,15 @@
+/**
+ * @module page-capabilities
+ *
+ * What an outside caller may ask a *page* to do: find the tagged controls, point at one, and
+ * operate it. Every verb addresses an element by its published `data-agent-element` handle —
+ * never by a caller-supplied selector, and never by evaluating caller-supplied script.
+ *
+ * Deliberately small. `click` is unbounded by construction (it carries whatever effect that
+ * button has), so the surface stays narrow and the page decides what is reachable by choosing
+ * what to tag. Nothing here scans a whole document: a host names the container to search.
+ */
+import { defaultAgenticMessages } from './messages.js';
 /** Handle argument shared by every element-addressed verb. */
 const HANDLE_PROPERTY = {
     handle: {
@@ -113,7 +125,7 @@ export const PAGE_CAPABILITIES = [
     },
     {
         id: 'page.navigate',
-        description: 'Move to another page of this site, named by its data-agent-page id. Only pages the host has published are reachable; arbitrary URLs are refused. Returns which page was showing before and after, and how many controls each publishes — call page.find_elements again afterwards, since every handle you hold may belong to the page you just left.',
+        description: defaultAgenticMessages.pageNavigateDescription(),
         inputSchema: {
             type: 'object',
             properties: {

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