@jini-ai/agentic 0.4.3 → 0.4.5

package/dist/core/gen-ui/encoder.js

@@ -1,3 +1,13 @@
+/** `stage_start` / `stage_end` share one shape; `iteration` is omitted entirely (not set to `undefined`) when absent. */
+function encodeStage(payload, base) {
+    return {
+        ...base,
+        kind: 'run.lifecycle',
+        status: payload.type === 'stage_start' ? 'pipeline_stage_started' : 'pipeline_stage_completed',
+        stageId: payload.stageId,
+        ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
+    };
+}
 /**
  * Creates a fresh `GenUiEncoder` with its own, empty tool-call correlation map.
  * @complexity `encode` is O(1) per call (one `Map` get/set/delete); memory is O(k) in the number
@@ -10,6 +20,24 @@ export function createGenUiEncoder({ clock }, _optional = {}) {
         const ts = ctx.now ? ctx.now({}) : clock.nowMs();
         return ctx.seq !== undefined ? { runId: ctx.runId, ts, seq: ctx.seq } : { runId: ctx.runId, ts };
     }
+    /** Resolves a `tool_result` against (and removes) its correlated `tool_use`. */
+    function encodeToolResult(payload, base) {
+        const pending = pendingToolCalls.get(payload.toolUseId);
+        pendingToolCalls.delete(payload.toolUseId);
+        return {
+            ...base,
+            kind: 'tool_call',
+            // A tool_result with no matching prior tool_use (never observed, or already resolved/
+            // cleared — e.g. after a run-ending 'end' event, see below) falls back to an 'unknown'
+            // name and null args rather than throwing: the result itself is still real and worth
+            // relaying even when its originating call wasn't captured.
+            toolName: pending?.toolName ?? 'unknown',
+            args: pending?.args ?? null,
+            callId: payload.toolUseId,
+            status: payload.isError ? 'failed' : 'completed',
+            result: payload.content,
+        };
+    }
     function encodeAgentPayload(payload, ctx) {
         const base = baseFields(ctx);
         switch (payload.type) {
@@ -21,42 +49,14 @@ export function createGenUiEncoder({ clock }, _optional = {}) {
                 // and there is no protocol-level guarantee ids are never reused within one run.
                 pendingToolCalls.set(payload.id, { toolName: payload.name, args: payload.input });
                 return { ...base, kind: 'tool_call', toolName: payload.name, args: payload.input, callId: payload.id, status: 'started' };
-            case 'tool_result': {
-                const pending = pendingToolCalls.get(payload.toolUseId);
-                pendingToolCalls.delete(payload.toolUseId);
-                return {
-                    ...base,
-                    kind: 'tool_call',
-                    // A tool_result with no matching prior tool_use (never observed, or already resolved/
-                    // cleared — e.g. after a run-ending 'end' event, see below) falls back to an 'unknown'
-                    // name and null args rather than throwing: the result itself is still real and worth
-                    // relaying even when its originating call wasn't captured.
-                    toolName: pending?.toolName ?? 'unknown',
-                    args: pending?.args ?? null,
-                    callId: payload.toolUseId,
-                    status: payload.isError ? 'failed' : 'completed',
-                    result: payload.content,
-                };
-            }
+            case 'tool_result':
+                return encodeToolResult(payload, base);
             // Generalization (see archived provenance ledger): pipeline_stage_started/completed generalized into a
             // named-stage boundary any multi-step driver can emit, flowing through the same 'agent'
             // channel as tool_use/tool_result.
             case 'stage_start':
-                return {
-                    ...base,
-                    kind: 'run.lifecycle',
-                    status: 'pipeline_stage_started',
-                    stageId: payload.stageId,
-                    ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
-                };
             case 'stage_end':
-                return {
-                    ...base,
-                    kind: 'run.lifecycle',
-                    status: 'pipeline_stage_completed',
-                    stageId: payload.stageId,
-                    ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
-                };
+                return encodeStage(payload, base);
             // Generalization (see archived provenance ledger): genui_surface_request/response generalized into a
             // generic human-in-the-loop ask/answer pair.
             case 'surface_request':

package/dist/core/guards.js

@@ -81,6 +81,13 @@ export function findFieldReadRefusal({ field }, _optional = {}) {
     const type = field.type?.toLowerCase();
     if (type !== undefined && DENIED_TYPES.has(type))
         return 'denied-type';
+    if (hasDeniedAutocomplete({ field }))
+        return 'denied-autocomplete';
+    if (hasSuspiciousFieldName({ field }))
+        return 'suspicious-name';
+    return null;
+}
+function hasDeniedAutocomplete({ field }, _optional = {}) {
     const autocomplete = field.autocomplete?.toLowerCase();
     if (autocomplete !== undefined) {
         // The real grammar is space-separated tokens, but a comma-joined value
@@ -90,10 +97,13 @@ export function findFieldReadRefusal({ field }, _optional = {}) {
         // worked as a plain text input while looking unguarded.
         for (const token of autocomplete.split(/[\s,]+/)) {
             if (DENIED_AUTOCOMPLETE.has(token))
-                return 'denied-autocomplete';
+                return true;
         }
     }
-    if (SUSPICIOUS_NAME.test(squashSeparators(field.name ?? ''))
+    return false;
+}
+function hasSuspiciousFieldName({ field }, _optional = {}) {
+    return (SUSPICIOUS_NAME.test(squashSeparators(field.name ?? ''))
         || SUSPICIOUS_NAME.test(squashSeparators(field.id ?? ''))
         // `name`/`id` are the *machine* names; a form builder or CMS that emits `name="field_47"`
         // next to a visible "Card number" label left the guard nothing to judge until this existed.
@@ -102,10 +112,7 @@ export function findFieldReadRefusal({ field }, _optional = {}) {
         // deletes the separators, so a join would let two innocuous labels form a trigger word across
         // their boundary ("Address" + "Snapshot" -> "addresssnapshot", which contains "ssn"). This
         // guard is deliberately over-inclusive, but not at the cost of matching text no page wrote.
-        || (field.accessibleLabels ?? []).some((label) => SUSPICIOUS_NAME.test(squashSeparators(label)))) {
-        return 'suspicious-name';
-    }
-    return null;
+        || (field.accessibleLabels ?? []).some((label) => SUSPICIOUS_NAME.test(squashSeparators(label))));
 }
 /**
  * Why an automated fill must be refused for this field, or `null` when it is safe to write.

package/dist/core/handle.d.ts

@@ -40,6 +40,19 @@ export type AgentHandleProps = {
 export declare function agentHandle({ handle }: {
     handle: string;
 }, options?: AgentHandleOptions): AgentHandleProps;
+/**
+ * Derives a bounded handle segment from an opaque id without rewriting that id.
+ * Short valid ids keep their spelling; other ids use a stable 64-bit FNV-1a fingerprint
+ * of their UTF-16 code units. The `h-<16 hex digits>` namespace is reserved for fingerprints.
+ * Unlike list collision suffixes, this segment does not depend on filtering or row order.
+ * This is display identity, not a cryptographic or authorization primitive.
+ * @param required - The original id; arbitrary characters, empty and long strings are accepted.
+ * @returns A valid segment of at most 40 characters; callers reserve space for their fixed prefix.
+ * @complexity O(n) time in id characters, O(1) auxiliary space. No effects or errors.
+ */
+export declare function agentHandleSegment({ value }: {
+    value: string;
+}, _optional?: Record<string, never>): string;
 /**
  * The handle for one sub-element published under `base` — `<base>-<action>`.
  *

package/dist/core/handle.js

@@ -38,6 +38,25 @@ export function agentHandle({ handle }, options = {}) {
         props[AGENT_PAGE_ATTRIBUTE] = options.page;
     return props;
 }
+/**
+ * Derives a bounded handle segment from an opaque id without rewriting that id.
+ * Short valid ids keep their spelling; other ids use a stable 64-bit FNV-1a fingerprint
+ * of their UTF-16 code units. The `h-<16 hex digits>` namespace is reserved for fingerprints.
+ * Unlike list collision suffixes, this segment does not depend on filtering or row order.
+ * This is display identity, not a cryptographic or authorization primitive.
+ * @param required - The original id; arbitrary characters, empty and long strings are accepted.
+ * @returns A valid segment of at most 40 characters; callers reserve space for their fixed prefix.
+ * @complexity O(n) time in id characters, O(1) auxiliary space. No effects or errors.
+ */
+export function agentHandleSegment({ value }, _optional = {}) {
+    if (value.length <= 40 && isValidElementHandle({ handle: value }) && !/^h-[0-9a-f]{16}$/.test(value))
+        return value;
+    let hash = 0xcbf29ce484222325n;
+    for (let index = 0; index < value.length; index += 1) {
+        hash = BigInt.asUintN(64, (hash ^ BigInt(value.charCodeAt(index))) * 0x100000001b3n);
+    }
+    return `h-${hash.toString(16).padStart(16, '0')}`;
+}
 /**
  * The handle for one sub-element published under `base` — `<base>-<action>`.
  *

package/dist/core/index.d.ts

@@ -21,7 +21,7 @@ export type { PageDriver, FindElementsFilter, PageSummary } from './page-driver.
 export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, type FindElementsResult, type PageElementResult, type PageActivitySnapshot, type PageWriteObservation, } from './page-executor.js';
 export { PAGE_CAPABILITIES } from './page-capabilities.js';
 export { AGENT_ELEMENT_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_PRIVATE_ATTRIBUTE, AGENT_ELEMENT_ROLES, isValidElementHandle, resolveHandleSelector, type AgentElementRole, type AgentElementDescriptor, type AgentElementRawState, type AgentElementState, } from './element-handles.js';
-export { agentHandle, agentSubHandle, agentHandleProps, type AgentHandleOptions, type AgentHandleProps, type AgentHandlePropsOptions, } from './handle.js';
+export { agentHandle, agentHandleSegment, agentSubHandle, agentHandleProps, type AgentHandleOptions, type AgentHandleProps, type AgentHandlePropsOptions, } from './handle.js';
 export { buildAgentListHandles } from './list-handles.js';
 export { findFieldFillRefusal, findFieldReadRefusal, describeFieldRefusal, describeFieldReadRefusal, normalizeAgentLabel, MAX_AGENT_LABEL_LENGTH, type FieldDescriptor, type FieldRefusal, type FieldReadRefusal, type NormalizedLabel, } from './guards.js';
 /**
@@ -48,4 +48,5 @@ export { createGenUiEncoder, type GenUiEncodeContext, type GenUiEncoder, type Ge
 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";
 export { createAnnotatedActionsScript } from './annotated-actions-script.js';
+export * from './site-guide/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -20,7 +20,7 @@ export { findCapability, findCapabilityInputError, availableCapabilities, } from
 export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, } from './page-executor.js';
 export { PAGE_CAPABILITIES } from './page-capabilities.js';
 export { AGENT_ELEMENT_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_PRIVATE_ATTRIBUTE, AGENT_ELEMENT_ROLES, isValidElementHandle, resolveHandleSelector, } from './element-handles.js';
-export { agentHandle, agentSubHandle, agentHandleProps, } from './handle.js';
+export { agentHandle, agentHandleSegment, agentSubHandle, agentHandleProps, } from './handle.js';
 export { buildAgentListHandles } from './list-handles.js';
 export { findFieldFillRefusal, findFieldReadRefusal, describeFieldRefusal, describeFieldReadRefusal, normalizeAgentLabel, MAX_AGENT_LABEL_LENGTH, } from './guards.js';
 /**
@@ -47,4 +47,5 @@ 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";
 export { createAnnotatedActionsScript } from './annotated-actions-script.js';
+export * from './site-guide/index.js';
 //# sourceMappingURL=index.js.map

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

@@ -194,14 +194,10 @@ 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')
+    if (!hasValidJsonRpcId({ value }))
         return false;
     if ('method' in value) {
-        // Request or notification: `id` present or not, but never a response's members alongside.
-        return typeof value['method'] === 'string'
-            && hasValidParams(value)
-            && !('result' in value)
-            && !('error' in value);
+        return isJsonRpcCallShape({ value });
     }
     // Response: correlated by `id`, carrying exactly one of `result` / `error`.
     if (!('id' in value))
@@ -212,6 +208,16 @@ export function isJsonRpcMessage(required, _optional = {}) {
         return false;
     return hasResult || isJsonRpcErrorObject(value['error']);
 }
+function hasValidJsonRpcId({ value }, _optional = {}) {
+    return !('id' in value) || typeof value['id'] === 'number' || typeof value['id'] === 'string';
+}
+function isJsonRpcCallShape({ value }, _optional = {}) {
+    // Request or notification: `id` present or not, but never a response's members alongside.
+    return typeof value['method'] === 'string'
+        && hasValidParams(value)
+        && !('result' in value)
+        && !('error' in value);
+}
 /** Whether a validated message expects a response (as opposed to being a notification). */
 export function isJsonRpcRequest(required, _optional = {}) {
     const { message } = required;

package/dist/core/page-executor.js

@@ -11,7 +11,7 @@
  * Nothing here touches the DOM. That is what makes the interesting half testable without a
  * browser: "does it refuse to type into a password box" is a unit test, not an integration test.
  */
-import { findCapabilityInputError, } from './capability.js';
+import { findCapability, findCapabilityInputError, } from './capability.js';
 import { AGENT_ELEMENT_ROLES, isValidElementHandle, } from './element-handles.js';
 import { describeFieldReadRefusal, describeFieldRefusal, findFieldFillRefusal, findFieldReadRefusal, normalizeAgentLabel, } from './guards.js';
 import { PAGE_CAPABILITIES } from './page-capabilities.js';
@@ -69,19 +69,28 @@ export function projectElementState({ raw }, _optional = {}) {
     // 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({ field: raw.field }) : null;
+    const withheldText = findWithheldText({ raw, refusal });
+    const base = {
+        text: withheldText === undefined ? text.text : '',
+        textTruncated: withheldText === undefined ? text.truncated : false,
+        ...(withheldText !== undefined ? { textWithheld: withheldText } : {}),
+        ...projectOptionalState({ raw, refusal }),
+    };
+    return projectFieldValue({ raw, refusal, base });
+}
+function findWithheldText({ raw, refusal }, _optional = {}) {
     // The one element whose `text` is NOT page-authored chrome: an editable region, whose contents
     // are the user's data and whose driver has no `value` to report them as. It is gated by exactly
     // the rules `value` is gated by below, including the "arrived with nothing to check it against"
     // one — an unverifiable secret is withheld, not trusted.
-    const withheldText = raw.textIsValue !== true
+    return raw.textIsValue !== true
         ? undefined
         : raw.field === undefined
             ? 'this element reported contents without the attributes needed to check them for secrets'
             : refusal !== null ? describeFieldReadRefusal({ refusal }) : undefined;
-    const base = {
-        text: withheldText === undefined ? text.text : '',
-        textTruncated: withheldText === undefined ? text.truncated : false,
-        ...(withheldText !== undefined ? { textWithheld: withheldText } : {}),
+}
+function projectOptionalState({ raw, refusal }, _optional = {}) {
+    return {
         ...(raw.checked !== undefined && refusal === null ? { checked: raw.checked } : {}),
         ...(raw.disabled !== undefined ? { disabled: raw.disabled } : {}),
         ...(raw.visible !== undefined ? { visible: raw.visible } : {}),
@@ -91,6 +100,8 @@ export function projectElementState({ raw }, _optional = {}) {
             ? { options: raw.options.map((option) => normalizeAgentLabel({ raw: option }).text) }
             : {}),
     };
+}
+function projectFieldValue({ raw, refusal, base }, _optional = {}) {
     if (raw.value === undefined)
         return base;
     if (raw.field === undefined) {
@@ -176,66 +187,10 @@ async function summarizePage(driver) {
  * purpose: a caller must be told why, not handed a silent no-op it will retry forever.
  */
 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 });
-    if (inputError !== null) {
-        // The schema rides along with the refusal rather than making a caller spend a second
-        // round trip on describe_tool to learn what it already tried to guess — ai-control-plane.md
-        // §29.4's "schema-on-error" requirement, empirically forced by a real run: page.fill was
-        // called with `handle` instead of the argument's old name, `element`, twice before the caller
-        // gave up and looked the schema up separately. One JSON-Schema object, embedded once, turned
-        // that into a same-turn self-correction for every page.* verb this gate guards, not just the
-        // one that got measured — self-correction is why that mismatch was survivable at all, given
-        // every verb here needs a handle from `page.find_elements`, whose own response has always
-        // called this same value `handle` (`AgentElementDescriptor.handle`). The argument itself was
-        // later renamed from `element` to `handle` to match, closing the gap this comment describes
-        // rather than merely papering over it turn by turn.
-        throw new Error(`${capabilityId}: ${inputError}. Expected input: ${JSON.stringify(capability.inputSchema)}`);
-    }
+    validatePageCapability({ capabilityId, input });
     switch (capabilityId) {
-        case 'page.find_elements': {
-            const role = input['role'];
-            // The schema's enum check has already run; this narrows the type for the driver.
-            const filter = {
-                ...(isAgentElementRole(role) ? { role } : {}),
-                ...(typeof input['query'] === 'string' ? { query: input['query'] } : {}),
-            };
-            const [found, rawPages] = await Promise.all([driver.findElements({}, filter), driver.listPages({})]);
-            const withState = input['withState'] === true;
-            const observing = withState && driver.describeState !== undefined;
-            const elements = await Promise.all(found.map(async (element, index) => {
-                const label = normalizeAgentLabel({ raw: element.label });
-                const base = {
-                    handle: element.handle,
-                    role: element.role,
-                    label: label.text,
-                    labelTruncated: label.truncated,
-                    page: element.page,
-                };
-                if (!observing || index >= MAX_STATEFUL_ELEMENTS)
-                    return base;
-                const state = await observeElement(driver, element.handle);
-                return state === undefined ? base : { ...base, state };
-            }));
-            // `label` is page-authored the same way an element's is — bounded here for the same reason
-            // `page.navigate`'s refusal message bounds it below, rather than trusting a host to have kept
-            // every `data-agent-page` label short and clean.
-            const pages = rawPages.map((page) => ({
-                id: page.id,
-                label: normalizeAgentLabel({ raw: page.label }).text,
-            }));
-            return {
-                elements,
-                pages,
-                untrustedFields: observing
-                    ? ['elements[].label', 'elements[].state.text', 'elements[].state.value', 'pages[].label']
-                    : ['elements[].label', 'pages[].label'],
-                ...(withState && !observing ? { stateUnavailable: true } : {}),
-                ...(observing && found.length > MAX_STATEFUL_ELEMENTS ? { stateTruncated: true } : {}),
-            };
-        }
+        case 'page.find_elements':
+            return findPageElements({ driver, input });
         case 'page.highlight': {
             const handle = requireHandle(input, 'handle');
             const durationMs = clampHighlightDuration(input['durationMs']);
@@ -252,30 +207,15 @@ export async function executePageCapability({ driver, capabilityId, input }, _op
             const observation = await observeWrite(driver, handle, () => driver.click({ handle }));
             return { clicked: handle, ...observation };
         }
-        case 'page.fill': {
-            const handle = requireHandle(input, 'handle');
-            // Declared required and typed `string` in the manifest, and `findCapabilityInputError`
-            // enforced both above — re-checking here would be an unreachable branch, not a safeguard.
-            const text = input['text'];
-            // Ask the page what this field actually is before writing to it. A handle proves the page
-            // published the element; it says nothing about whether it holds a password.
-            const field = await driver.describeField({ handle });
-            if (field === null)
-                throw new Error(`"${handle}" is not a fillable field`);
-            const refusal = findFieldFillRefusal({ field });
-            if (refusal !== null) {
-                throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal({ refusal })}`);
-            }
-            const observation = await observeWrite(driver, handle, () => driver.fill({ handle, text }));
-            return { filled: handle, ...observation };
-        }
+        case 'page.fill':
+            return fillPageField({ driver, input });
         case 'page.select_option': {
             const handle = requireHandle(input, 'handle');
             // Required and string-typed by the manifest, already enforced above. See page.fill.
             const option = input['option'];
             // Optional and boolean-typed by the manifest; absent means "select it", same as before this
             // argument existed.
-            const selected = input['selected'] === false ? false : true;
+            const selected = input['selected'] !== false;
             // 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>`.
@@ -284,37 +224,117 @@ export async function executePageCapability({ driver, capabilityId, input }, _op
             // "the handle this call acted on" for every verb in this switch (`clicked`, `filled`, …).
             return { selected: handle, option, optionSelected: selected, ...observation };
         }
-        case 'page.navigate': {
-            // Required and string-typed by the manifest, already enforced above. See page.fill.
-            const page = input['page'];
-            const pages = await driver.listPages({});
-            if (!pages.some((candidate) => candidate.id === page)) {
-                // Every other piece of page-authored (or, here, caller-authored-but-page-shaped) text
-                // this system hands to a model goes through normalizeAgentLabel first — bounded, control-
-                // and bidi-stripped. This refusal was the one path that skipped it: the raw `page`
-                // argument, and the `pages` this host actually publishes (itself read verbatim off
-                // `data-agent-page` attributes with no length bound), were interpolated straight into the
-                // thrown message. A 5000+-char bidi payload survived verbatim as a result. The lookup
-                // above still runs on the raw values — only the text that reaches the message is bounded.
-                //
-                // `id (label)`, not just the id: a refusal is the one moment a caller that guessed wrong
-                // is looking straight at the real menu, so it is worth spending the label here even though
-                // `page.find_elements` already carries the same information — a caller that jumped
-                // straight to `page.navigate` without calling that first still lands on the right id.
-                const safePage = normalizeAgentLabel({ 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 });
-            if (driver.settle !== undefined)
-                await driver.settle({});
-            const after = await summarizePage(driver);
-            return { navigatedTo: page, before, after };
-        }
+        case 'page.navigate':
+            return navigatePage({ driver, input });
         /* c8 ignore next 2 -- unreachable: the id was matched against PAGE_CAPABILITIES above. */
         default:
             throw new Error(`unhandled page capability: ${capabilityId}`);
     }
 }
+function validatePageCapability({ capabilityId, input }, _optional = {}) {
+    const capability = findCapability({ capabilities: PAGE_CAPABILITIES, id: capabilityId });
+    if (capability === undefined)
+        throw new Error(`unknown page capability: ${capabilityId}`);
+    const inputError = findCapabilityInputError({ capability, input });
+    if (inputError !== null) {
+        // The schema rides along with the refusal rather than making a caller spend a second
+        // round trip on describe_tool to learn what it already tried to guess — ai-control-plane.md
+        // §29.4's "schema-on-error" requirement, empirically forced by a real run: page.fill was
+        // called with `handle` instead of the argument's old name, `element`, twice before the caller
+        // gave up and looked the schema up separately. One JSON-Schema object, embedded once, turned
+        // that into a same-turn self-correction for every page.* verb this gate guards, not just the
+        // one that got measured — self-correction is why that mismatch was survivable at all, given
+        // every verb here needs a handle from `page.find_elements`, whose own response has always
+        // called this same value `handle` (`AgentElementDescriptor.handle`). The argument itself was
+        // later renamed from `element` to `handle` to match, closing the gap this comment describes
+        // rather than merely papering over it turn by turn.
+        throw new Error(`${capabilityId}: ${inputError}. Expected input: ${JSON.stringify(capability.inputSchema)}`);
+    }
+}
+async function findPageElements({ driver, input }, _optional = {}) {
+    const role = input['role'];
+    // The schema's enum check has already run; this narrows the type for the driver.
+    const filter = {
+        ...(isAgentElementRole(role) ? { role } : {}),
+        ...(typeof input['query'] === 'string' ? { query: input['query'] } : {}),
+    };
+    const [found, rawPages] = await Promise.all([driver.findElements({}, filter), driver.listPages({})]);
+    const withState = input['withState'] === true;
+    const observing = withState && driver.describeState !== undefined;
+    const elements = await Promise.all(found.map(async (element, index) => {
+        const label = normalizeAgentLabel({ raw: element.label });
+        const base = {
+            handle: element.handle,
+            role: element.role,
+            label: label.text,
+            labelTruncated: label.truncated,
+            page: element.page,
+        };
+        if (!observing || index >= MAX_STATEFUL_ELEMENTS)
+            return base;
+        const state = await observeElement(driver, element.handle);
+        return state === undefined ? base : { ...base, state };
+    }));
+    // `label` is page-authored the same way an element's is — bounded here for the same reason
+    // `page.navigate`'s refusal message bounds it below, rather than trusting a host to have kept
+    // every `data-agent-page` label short and clean.
+    const pages = rawPages.map((page) => ({
+        id: page.id,
+        label: normalizeAgentLabel({ raw: page.label }).text,
+    }));
+    return {
+        elements,
+        pages,
+        untrustedFields: observing
+            ? ['elements[].label', 'elements[].state.text', 'elements[].state.value', 'pages[].label']
+            : ['elements[].label', 'pages[].label'],
+        ...(withState && !observing ? { stateUnavailable: true } : {}),
+        ...(observing && found.length > MAX_STATEFUL_ELEMENTS ? { stateTruncated: true } : {}),
+    };
+}
+async function fillPageField({ driver, input }, _optional = {}) {
+    const handle = requireHandle(input, 'handle');
+    // Declared required and typed `string` in the manifest, and `findCapabilityInputError`
+    // enforced both above — re-checking here would be an unreachable branch, not a safeguard.
+    const text = input['text'];
+    // Ask the page what this field actually is before writing to it. A handle proves the page
+    // published the element; it says nothing about whether it holds a password.
+    const field = await driver.describeField({ handle });
+    if (field === null)
+        throw new Error(`"${handle}" is not a fillable field`);
+    const refusal = findFieldFillRefusal({ field });
+    if (refusal !== null) {
+        throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal({ refusal })}`);
+    }
+    const observation = await observeWrite(driver, handle, () => driver.fill({ handle, text }));
+    return { filled: handle, ...observation };
+}
+async function navigatePage({ driver, input }, _optional = {}) {
+    // Required and string-typed by the manifest, already enforced above. See page.fill.
+    const page = input['page'];
+    const pages = await driver.listPages({});
+    if (!pages.some((candidate) => candidate.id === page)) {
+        // Every other piece of page-authored (or, here, caller-authored-but-page-shaped) text
+        // this system hands to a model goes through normalizeAgentLabel first — bounded, control-
+        // and bidi-stripped. This refusal was the one path that skipped it: the raw `page`
+        // argument, and the `pages` this host actually publishes (itself read verbatim off
+        // `data-agent-page` attributes with no length bound), were interpolated straight into the
+        // thrown message. A 5000+-char bidi payload survived verbatim as a result. The lookup
+        // above still runs on the raw values — only the text that reaches the message is bounded.
+        //
+        // `id (label)`, not just the id: a refusal is the one moment a caller that guessed wrong
+        // is looking straight at the real menu, so it is worth spending the label here even though
+        // `page.find_elements` already carries the same information — a caller that jumped
+        // straight to `page.navigate` without calling that first still lands on the right id.
+        const safePage = normalizeAgentLabel({ 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 });
+    if (driver.settle !== undefined)
+        await driver.settle({});
+    const after = await summarizePage(driver);
+    return { navigatedTo: page, before, after };
+}
 //# sourceMappingURL=page-executor.js.map

package/dist/core/site-guide/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './topic-schema.js';
+export * from './site-guide.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/site-guide/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './topic-schema.js';
+export * from './site-guide.js';
+//# sourceMappingURL=index.js.map

package/dist/core/site-guide/site-guide.d.ts

@@ -0,0 +1,18 @@
+import type { SiteGuide, SiteGuidePorts } from './types.js';
+export declare class SiteGuideInputError extends Error {
+    constructor({ message }: {
+        readonly message: string;
+    }, _options?: Record<string, never>);
+}
+/** Build a neutral read-only guide over host ports. No product state or plugin loader is ambient.
+ * Authorization and contributions are read fresh for each request. Errors from enrichment/facts
+ * yield explicit unavailable status without copying arbitrary error messages into model context.
+ * @param ports - Facts, authorization, optional enrichment, and host minimal capability cards.
+ * @returns One overview/explain service. Invalid input and hidden topics throw SiteGuideInputError.
+ * @complexity O(t + p) per request, topics plus distinct permissions; one bulk facts read.
+ * @example createSiteGuide({ facts, authorize, builtInTopics: cards }).run({ caller, operation: 'overview' });
+ */
+export declare function createSiteGuide(ports: SiteGuidePorts, options?: {
+    readonly readTimeoutMs?: number;
+}): SiteGuide;
+//# sourceMappingURL=site-guide.d.ts.map