@jini-ai/agentic 0.1.1 → 0.3.0

package/dist/core/list-handles.js

@@ -0,0 +1,57 @@
+/**
+ * @module list-handles
+ *
+ * How a host turns one namespace prefix (its own `agentHandle` base, e.g. `"mcp-server"`) plus a
+ * list of items' own stable ids into a distinct, stable base handle per item — the shape every
+ * repeated-row/repeated-card list needs, and that a per-host reimplementation risks getting
+ * subtly wrong (see {@link buildAgentListHandles}'s own doc for the exact failure mode).
+ *
+ * The core problem: a `data-agent-element` handle is `[a-z0-9]+(-[a-z0-9]+)*` only (see
+ * `element-handles.ts`), but the ids driving a real list (a form field's `id`, a content type's
+ * `key`, a database row's numeric id, a configured source's own id, ...) are arbitrary strings.
+ * Two different ids can also slugify to the SAME handle. Both are resolved here, once, so every
+ * list surface in every host derives its handles the same way instead of each re-deriving (and
+ * possibly getting wrong) the same two rules. Lives at this package's universal root — like
+ * `handle.ts` and `element-handles.ts` — because it is pure data with no DOM or framework
+ * involved, so any host (React, Vue, a server-rendered list) can use it identically.
+ */
+/**
+ * Builds one distinct, stable base handle per id, positionally aligned with `ids`.
+ *
+ * Handles are derived from each id's own slug, not its position in the list — an agent reading
+ * `page.find_elements` should see `<prefix>-about-us`, not `<prefix>-3`, so the same control keeps
+ * the same handle even if rows are later reordered or filtered. An id with nothing sluggable left
+ * in it (e.g. `"***"`) falls back to its 1-based position instead, so it still produces a
+ * resolvable handle rather than an empty one.
+ *
+ * Uniqueness is enforced with a suffix SEARCH, not a single `-<index>` append: appending the index
+ * alone is not collision-proof (`["x", "x-3", "x"]` would give the third entry the fallback
+ * `<prefix>-x-3`, which the second entry already holds). A duplicate handle does not fail loudly —
+ * it makes `page.click`/`page.fill` silently resolve to whichever element the DOM reaches first —
+ * so this loop is the load-bearing part of the function, not a stylistic choice.
+ *
+ * @param prefix - The list's own handle namespace (e.g. `"mcp-server"`, `"form-field"`). Must
+ *   already be a valid, non-empty handle segment — callers own that, same as every other
+ *   `agentHandle()` base.
+ * @param ids - The list items' own stable ids, in the order they are rendered.
+ * @returns One base handle per id, positionally aligned with `ids`, all distinct.
+ * @complexity Time O(n) typical, O(n²) worst case when every id slugifies identically (the suffix
+ * 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) {
+    const used = new Set();
+    return ids.map((id, index) => {
+        const slug = id.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+        const preferred = `${prefix}-${slug === '' ? index + 1 : slug}`;
+        let handle = preferred;
+        let suffix = 2;
+        while (used.has(handle)) {
+            handle = `${preferred}-${suffix}`;
+            suffix += 1;
+        }
+        used.add(handle);
+        return handle;
+    });
+}
+//# sourceMappingURL=list-handles.js.map

package/dist/core/list-handles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-handles.js","sourceRoot":"","sources":["../../src/core/list-handles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,GAAsB;IAC1E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE;QAC3B,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAClF,MAAM,SAAS,GAAG,GAAG,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChE,IAAI,MAAM,GAAG,SAAS,CAAC;QACvB,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,MAAM,GAAG,GAAG,SAAS,IAAI,MAAM,EAAE,CAAC;YAClC,MAAM,IAAI,CAAC,CAAC;QACd,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjB,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,223 @@
+/**
+ * @module mcp-ui
+ *
+ * The MCP Apps (`mcp-ui`) envelope: JSON-RPC 2.0 over `postMessage` between a host and a
+ * sandboxed iframe View.
+ *
+ * MCP Apps became the first official MCP extension (SEP-1865) on 2026-01-26. Jini borrows its
+ * **envelope and lifecycle** rather than inventing a message format, because the hard parts are
+ * already settled there: request/response correlation by `id`, and the ordering rule that a host
+ * MUST NOT send any request or notification to a View before receiving `initialized` — which is
+ * the fix for the "posted before the iframe was listening" race.
+ *
+ * Re-verified 2026-07-28 against the primary source (`github.com/modelcontextprotocol/ext-apps`,
+ * both `specification/2026-01-26/apps.mdx` [Stable] and `specification/draft/apps.mdx`) after an
+ * audit found the bucket below had the wrong direction for two lifecycle messages and mis-typed a
+ * third as fire-and-forget when the spec defines it as a request needing a response:
+ *
+ * - `ui/notifications/initialized` and `ui/notifications/size-changed` are **View→Host** (the
+ *   sequence diagram is unambiguous: `UI ->> H: ui/notifications/initialized`, and the "Host
+ *   Behavior" prose for size reads "hosts MUST **listen for** ... notifications **from the
+ *   View**"). They were previously bucketed under `MCP_UI_HOST_NOTIFICATIONS`, i.e. backwards —
+ *   now under {@link MCP_UI_VIEW_NOTIFICATIONS}.
+ * - `ui/resource-teardown` (Host→View) carries an `id` and has success/error response shapes in
+ *   the spec's own wire examples, and the prose is explicit: "Host SHOULD wait for a response
+ *   before tearing down the resource (to prevent data loss)." That is a request, not a
+ *   notification — moved to {@link MCP_UI_HOST_REQUESTS}.
+ *
+ * The draft spec (not yet Stable, but already fixing the above and adding surface this module
+ * now also models) adds: `ui/notifications/request-teardown` (View→Host, the View asking to be
+ * torn down), `ui/download-file` and `sampling/createMessage` (View→Host requests), and the
+ * Host→App direction of `tools/call`/`tools/list` for Apps that register their own tools (the
+ * "App-Provided Tools" section, declared via `appCapabilities.tools` in `ui/initialize`).
+ *
+ * Two deliberate divergences from the spec, both load-bearing:
+ *
+ * 1. **Direction.** MCP Apps is primarily View→Host: the embedded UI calls tools. Host→View is a
+ *    *fixed* lifecycle set with no generic "host asks the View to do something" (the App-tools
+ *    addition above is the one exception, and it is opt-in and capability-gated). Jini's page
+ *    verbs therefore ride as an explicitly-namespaced extension ({@link JINI_PAGE_ACTION_METHOD})
+ *    — ours, not the spec's, and named so no one mistakes it.
+ * 2. **Sandbox.** The spec mandates `sandbox="allow-scripts allow-same-origin"`, which is safe
+ *    *there* because the View is served from a separate origin behind a sandbox proxy. A host
+ *    serving preview content from its own origin must NOT copy that line: `allow-same-origin`
+ *    would hand the embedded document access to the host's origin. See
+ *    {@link MCP_UI_SANDBOX_NOTE}.
+ *
+ * No transport here — this package touches no browser globals. These are pure builders and
+ * parsers; the binding that owns the iframe does the posting.
+ */
+/** Requests the View may send the Host. From the 2026-01-26 [Stable] spec plus the draft's additions (marked below). */
+export declare const MCP_UI_VIEW_METHODS: {
+    readonly initialize: "ui/initialize";
+    /** View→Host: call a server tool via the Host's proxy (distinct from {@link MCP_UI_HOST_REQUESTS.callAppTool}, the reverse direction). */
+    readonly callTool: "tools/call";
+    readonly readResource: "resources/read";
+    readonly log: "notifications/message";
+    readonly openLink: "ui/open-link";
+    readonly sendMessage: "ui/message";
+    readonly requestDisplayMode: "ui/request-display-mode";
+    readonly updateModelContext: "ui/update-model-context";
+    /** Draft addition. Host-mediated file download from a sandboxed iframe that cannot use `allow-downloads`. */
+    readonly downloadFile: "ui/download-file";
+    /** Draft addition. Request an LLM completion from the Host; gated behind `hostCapabilities.sampling`. */
+    readonly createMessage: "sampling/createMessage";
+    readonly ping: "ping";
+};
+/**
+ * Notifications the Host may send the View — fire-and-forget, no response expected or allowed.
+ * `initialized`/`size-changed` are NOT here: both are sent BY the View (see
+ * {@link MCP_UI_VIEW_NOTIFICATIONS}), and `teardown` is NOT here either: it is a request the Host
+ * sends TO the View expecting a response (see {@link MCP_UI_HOST_REQUESTS}).
+ */
+export declare const MCP_UI_HOST_NOTIFICATIONS: {
+    readonly toolInputPartial: "ui/notifications/tool-input-partial";
+    readonly toolInput: "ui/notifications/tool-input";
+    readonly toolResult: "ui/notifications/tool-result";
+    readonly toolCancelled: "ui/notifications/tool-cancelled";
+    readonly hostContextChanged: "ui/notifications/host-context-changed";
+};
+/**
+ * Notifications the View may send the Host — fire-and-forget, no response expected or allowed.
+ * The spec's own "Notifications (Host → View)" heading in the 2026-01-26 text is misleading for
+ * two of these (see the module doc's audit note); the draft spec corrects this by giving these
+ * two, plus its own new addition, an explicit "Notifications (View → Host)" heading.
+ */
+export declare const MCP_UI_VIEW_NOTIFICATIONS: {
+    /** The View→Host handshake completion notification. Host MUST NOT send anything to the View before this arrives. */
+    readonly initialized: "ui/notifications/initialized";
+    /** The View SHOULD send this "when rendered content body size changes." */
+    readonly sizeChanged: "ui/notifications/size-changed";
+    /** Draft addition. The View asking to be torn down (e.g. a "Done" button); the Host MAY defer or ignore it, but if it accepts, it still owes the View {@link MCP_UI_HOST_REQUESTS.teardown}. */
+    readonly requestTeardown: "ui/notifications/request-teardown";
+};
+/**
+ * Requests the Host may send the View, needing a response. Distinct from
+ * {@link MCP_UI_HOST_NOTIFICATIONS} because a caller building a JSON-RPC envelope for one of
+ * these must attach an `id` and correlate the reply — using {@link createJsonRpcNotification}
+ * here would silently produce a message the View has no `id` to answer, and a Host that then
+ * "waits for a response" (the spec's own words) would wait forever.
+ */
+export declare const MCP_UI_HOST_REQUESTS: {
+    /**
+     * Host MUST send this before tearing down the UI resource, for any reason. Per spec: "Host
+     * SHOULD wait for a response before tearing down the resource (to prevent data loss)." — this
+     * is the message the bug report flagged: bucketing it as a fire-and-forget notification means a
+     * Host never learns whether the View acknowledged before disappearing.
+     */
+    readonly teardown: "ui/resource-teardown";
+    /** Draft addition ("App-Provided Tools"). Host→App: execute a tool the App registered via `appCapabilities.tools`. */
+    readonly callAppTool: "tools/call";
+    /** Draft addition. Host→App: list the App's registered tools. */
+    readonly listAppTools: "tools/list";
+};
+/**
+ * Jini's page-action extension. **Not part of MCP Apps** — the namespace is explicit so it can
+ * never be mistaken for a spec method, and so a compliant host that does not understand it
+ * rejects it as unknown rather than silently mis-handling it.
+ */
+export declare const JINI_PAGE_ACTION_METHOD = "x-jini/page-action";
+/**
+ * Why a host serving preview content from its own origin must not copy the spec's sandbox line.
+ * Kept as an exported string so the reason travels with the code that would otherwise be
+ * cargo-culted.
+ */
+export declare const MCP_UI_SANDBOX_NOTE: string;
+export interface JsonRpcRequest {
+    readonly jsonrpc: '2.0';
+    readonly id: number | string;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+export interface JsonRpcNotification {
+    readonly jsonrpc: '2.0';
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+export interface JsonRpcError {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface JsonRpcResponse {
+    readonly jsonrpc: '2.0';
+    readonly id: number | string;
+    readonly result?: unknown;
+    readonly error?: JsonRpcError;
+}
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+/** JSON-RPC 2.0 reserved codes, used so a View's failures read the same as any other client's. */
+export declare const JSON_RPC_ERROR_CODES: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+};
+/**
+ * Whether an arbitrary value is a JSON-RPC 2.0 message.
+ *
+ * Messages arriving over `postMessage` are attacker-influenced input — any page able to reach the
+ * frame can post anything. Validate before dispatch; never trust the shape.
+ *
+ * Found by live adversarial testing against a real sandboxed iframe (2026-07-28), NOT by static
+ * review: a request whose `method` is a valid string but whose `id` is present and malformed
+ * (e.g. an object, `{ jsonrpc: '2.0', id: { nested: true }, method: 'tools/call' }`) used to pass
+ * this check — the `typeof value['method'] === 'string'` branch returned `true` unconditionally,
+ * without ever looking at `id`'s type. A Host trusting that then had to build a JSON-RPC response
+ * carrying a non-spec `id` back at the View, which the View's own correlation map (keyed by
+ * string ids) could never match — not a crash, but a real protocol violation this function exists
+ * specifically to catch. Now: if `id` is present at all, its type is checked before anything else,
+ * for every message shape (request, notification, or response) — a notification legitimately has
+ * no `id`, but a message that HAS one must have a valid one.
+ *
+ * The 2026-07-29 audit found the rest of that check was still far too generous, in three ways, all
+ * of them reachable from anything able to post at the frame:
+ *
+ * - **`params` went unread.** Any string `method` returned `true` immediately, so
+ *   `{method: 'tools/call', params: 'nope'}` reached dispatch and a handler reading
+ *   `params.capabilityId` got `undefined` rather than a refusal. §4.2 fixes the type: Array or
+ *   Object.
+ * - **The four shapes were not kept apart.** JSON-RPC 2.0 defines request, notification, success
+ *   response and error response as distinct, mutually exclusive objects. A message carrying both
+ *   `method` and `result` passed as a request; one carrying both `result` and `error` passed as a
+ *   response, which §5 forbids in as many words ("Either the result member or error member MUST be
+ *   included, but both members MUST NOT be included").
+ * - **`error` was accepted as any value at all**, `error: "boom"` included, so a host formatting
+ *   `error.message` back to a user read a property off a string.
+ *
+ * A message whose `method` is present but not a string is rejected outright rather than falling
+ * through to the response branch — reinterpreting a malformed request as a response is how one
+ * bad message becomes two wrong behaviors.
+ *
+ * @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;
+/** Whether a validated message expects a response (as opposed to being a notification). */
+export declare function isJsonRpcRequest(message: JsonRpcMessage): message is JsonRpcRequest;
+/**
+ * Builds a request.
+ *
+ * @param id - Correlation id, unique per in-flight request. Doubles as the idempotency key: a
+ * transport that redelivers (an SSE reconnect, a repeated post) must not execute twice.
+ * @param method - Method name.
+ * @param params - Optional parameters.
+ */
+export declare function createJsonRpcRequest(id: number | string, method: string, params?: Record<string, unknown>): JsonRpcRequest;
+/** Builds a notification — no `id`, so no response is expected or allowed. */
+export declare function createJsonRpcNotification(method: string, params?: Record<string, unknown>): JsonRpcNotification;
+/** Builds a success response for `id`. */
+export declare function createJsonRpcResult(id: number | string, result: unknown): JsonRpcResponse;
+/** Builds an error response for `id`. */
+export declare function createJsonRpcError(id: number | string, code: number, message: string, data?: unknown): JsonRpcResponse;
+/**
+ * Builds a Jini page-action request.
+ *
+ * @param id - Correlation/idempotency id.
+ * @param capabilityId - A `page.*` capability id.
+ * @param input - Capability arguments.
+ * @returns The namespaced extension request.
+ */
+export declare function createPageActionRequest(id: number | string, capabilityId: string, input: Record<string, unknown>): JsonRpcRequest;
+//# sourceMappingURL=mcp-ui-apps.d.ts.map

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

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

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

@@ -0,0 +1,252 @@
+/**
+ * @module mcp-ui
+ *
+ * The MCP Apps (`mcp-ui`) envelope: JSON-RPC 2.0 over `postMessage` between a host and a
+ * sandboxed iframe View.
+ *
+ * MCP Apps became the first official MCP extension (SEP-1865) on 2026-01-26. Jini borrows its
+ * **envelope and lifecycle** rather than inventing a message format, because the hard parts are
+ * already settled there: request/response correlation by `id`, and the ordering rule that a host
+ * MUST NOT send any request or notification to a View before receiving `initialized` — which is
+ * the fix for the "posted before the iframe was listening" race.
+ *
+ * Re-verified 2026-07-28 against the primary source (`github.com/modelcontextprotocol/ext-apps`,
+ * both `specification/2026-01-26/apps.mdx` [Stable] and `specification/draft/apps.mdx`) after an
+ * audit found the bucket below had the wrong direction for two lifecycle messages and mis-typed a
+ * third as fire-and-forget when the spec defines it as a request needing a response:
+ *
+ * - `ui/notifications/initialized` and `ui/notifications/size-changed` are **View→Host** (the
+ *   sequence diagram is unambiguous: `UI ->> H: ui/notifications/initialized`, and the "Host
+ *   Behavior" prose for size reads "hosts MUST **listen for** ... notifications **from the
+ *   View**"). They were previously bucketed under `MCP_UI_HOST_NOTIFICATIONS`, i.e. backwards —
+ *   now under {@link MCP_UI_VIEW_NOTIFICATIONS}.
+ * - `ui/resource-teardown` (Host→View) carries an `id` and has success/error response shapes in
+ *   the spec's own wire examples, and the prose is explicit: "Host SHOULD wait for a response
+ *   before tearing down the resource (to prevent data loss)." That is a request, not a
+ *   notification — moved to {@link MCP_UI_HOST_REQUESTS}.
+ *
+ * The draft spec (not yet Stable, but already fixing the above and adding surface this module
+ * now also models) adds: `ui/notifications/request-teardown` (View→Host, the View asking to be
+ * torn down), `ui/download-file` and `sampling/createMessage` (View→Host requests), and the
+ * Host→App direction of `tools/call`/`tools/list` for Apps that register their own tools (the
+ * "App-Provided Tools" section, declared via `appCapabilities.tools` in `ui/initialize`).
+ *
+ * Two deliberate divergences from the spec, both load-bearing:
+ *
+ * 1. **Direction.** MCP Apps is primarily View→Host: the embedded UI calls tools. Host→View is a
+ *    *fixed* lifecycle set with no generic "host asks the View to do something" (the App-tools
+ *    addition above is the one exception, and it is opt-in and capability-gated). Jini's page
+ *    verbs therefore ride as an explicitly-namespaced extension ({@link JINI_PAGE_ACTION_METHOD})
+ *    — ours, not the spec's, and named so no one mistakes it.
+ * 2. **Sandbox.** The spec mandates `sandbox="allow-scripts allow-same-origin"`, which is safe
+ *    *there* because the View is served from a separate origin behind a sandbox proxy. A host
+ *    serving preview content from its own origin must NOT copy that line: `allow-same-origin`
+ *    would hand the embedded document access to the host's origin. See
+ *    {@link MCP_UI_SANDBOX_NOTE}.
+ *
+ * No transport here — this package touches no browser globals. These are pure builders and
+ * parsers; the binding that owns the iframe does the posting.
+ */
+/** Requests the View may send the Host. From the 2026-01-26 [Stable] spec plus the draft's additions (marked below). */
+export const MCP_UI_VIEW_METHODS = {
+    initialize: 'ui/initialize',
+    /** View→Host: call a server tool via the Host's proxy (distinct from {@link MCP_UI_HOST_REQUESTS.callAppTool}, the reverse direction). */
+    callTool: 'tools/call',
+    readResource: 'resources/read',
+    log: 'notifications/message',
+    openLink: 'ui/open-link',
+    sendMessage: 'ui/message',
+    requestDisplayMode: 'ui/request-display-mode',
+    updateModelContext: 'ui/update-model-context',
+    /** Draft addition. Host-mediated file download from a sandboxed iframe that cannot use `allow-downloads`. */
+    downloadFile: 'ui/download-file',
+    /** Draft addition. Request an LLM completion from the Host; gated behind `hostCapabilities.sampling`. */
+    createMessage: 'sampling/createMessage',
+    ping: 'ping',
+};
+/**
+ * Notifications the Host may send the View — fire-and-forget, no response expected or allowed.
+ * `initialized`/`size-changed` are NOT here: both are sent BY the View (see
+ * {@link MCP_UI_VIEW_NOTIFICATIONS}), and `teardown` is NOT here either: it is a request the Host
+ * sends TO the View expecting a response (see {@link MCP_UI_HOST_REQUESTS}).
+ */
+export const MCP_UI_HOST_NOTIFICATIONS = {
+    toolInputPartial: 'ui/notifications/tool-input-partial',
+    toolInput: 'ui/notifications/tool-input',
+    toolResult: 'ui/notifications/tool-result',
+    toolCancelled: 'ui/notifications/tool-cancelled',
+    hostContextChanged: 'ui/notifications/host-context-changed',
+};
+/**
+ * Notifications the View may send the Host — fire-and-forget, no response expected or allowed.
+ * The spec's own "Notifications (Host → View)" heading in the 2026-01-26 text is misleading for
+ * two of these (see the module doc's audit note); the draft spec corrects this by giving these
+ * two, plus its own new addition, an explicit "Notifications (View → Host)" heading.
+ */
+export const MCP_UI_VIEW_NOTIFICATIONS = {
+    /** The View→Host handshake completion notification. Host MUST NOT send anything to the View before this arrives. */
+    initialized: 'ui/notifications/initialized',
+    /** The View SHOULD send this "when rendered content body size changes." */
+    sizeChanged: 'ui/notifications/size-changed',
+    /** Draft addition. The View asking to be torn down (e.g. a "Done" button); the Host MAY defer or ignore it, but if it accepts, it still owes the View {@link MCP_UI_HOST_REQUESTS.teardown}. */
+    requestTeardown: 'ui/notifications/request-teardown',
+};
+/**
+ * Requests the Host may send the View, needing a response. Distinct from
+ * {@link MCP_UI_HOST_NOTIFICATIONS} because a caller building a JSON-RPC envelope for one of
+ * these must attach an `id` and correlate the reply — using {@link createJsonRpcNotification}
+ * here would silently produce a message the View has no `id` to answer, and a Host that then
+ * "waits for a response" (the spec's own words) would wait forever.
+ */
+export const MCP_UI_HOST_REQUESTS = {
+    /**
+     * Host MUST send this before tearing down the UI resource, for any reason. Per spec: "Host
+     * SHOULD wait for a response before tearing down the resource (to prevent data loss)." — this
+     * is the message the bug report flagged: bucketing it as a fire-and-forget notification means a
+     * Host never learns whether the View acknowledged before disappearing.
+     */
+    teardown: 'ui/resource-teardown',
+    /** Draft addition ("App-Provided Tools"). Host→App: execute a tool the App registered via `appCapabilities.tools`. */
+    callAppTool: 'tools/call',
+    /** Draft addition. Host→App: list the App's registered tools. */
+    listAppTools: 'tools/list',
+};
+/**
+ * Jini's page-action extension. **Not part of MCP Apps** — the namespace is explicit so it can
+ * never be mistaken for a spec method, and so a compliant host that does not understand it
+ * rejects it as unknown rather than silently mis-handling it.
+ */
+export const JINI_PAGE_ACTION_METHOD = 'x-jini/page-action';
+/**
+ * Why a host serving preview content from its own origin must not copy the spec's sandbox line.
+ * Kept as an exported string so the reason travels with the code that would otherwise be
+ * cargo-culted.
+ */
+export const MCP_UI_SANDBOX_NOTE = 'MCP Apps requires sandbox="allow-scripts allow-same-origin" because its Views are served from '
+    + 'a separate origin behind a sandbox proxy. When the embedded document is served from the '
+    + "host's own origin, allow-same-origin grants it access to the host — use allow-scripts alone.";
+/** JSON-RPC 2.0 reserved codes, used so a View's failures read the same as any other client's. */
+export const JSON_RPC_ERROR_CODES = {
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+};
+function isRecord(value) {
+    // Arrays excluded deliberately: `typeof [] === 'object'`, and an array carrying the right
+    // properties would otherwise pass as a message. An array IS meaningful JSON-RPC — it is a
+    // *batch* — but this transport does not send or accept batches, so one arriving is either a
+    // mistake or a probe, and either way is not the single message every caller here expects.
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `params`, per §4.2, is "Array or Object" — a primitive there is not an under-specified call, it is a malformed one. */
+function hasValidParams(value) {
+    if (!('params' in value))
+        return true;
+    const params = value['params'];
+    return typeof params === 'object' && params !== null;
+}
+/** The §5.1 error object: a Number `code` and a String `message` (plus optional `data`). */
+function isJsonRpcErrorObject(value) {
+    return isRecord(value) && typeof value['code'] === 'number' && typeof value['message'] === 'string';
+}
+/**
+ * Whether an arbitrary value is a JSON-RPC 2.0 message.
+ *
+ * Messages arriving over `postMessage` are attacker-influenced input — any page able to reach the
+ * frame can post anything. Validate before dispatch; never trust the shape.
+ *
+ * Found by live adversarial testing against a real sandboxed iframe (2026-07-28), NOT by static
+ * review: a request whose `method` is a valid string but whose `id` is present and malformed
+ * (e.g. an object, `{ jsonrpc: '2.0', id: { nested: true }, method: 'tools/call' }`) used to pass
+ * this check — the `typeof value['method'] === 'string'` branch returned `true` unconditionally,
+ * without ever looking at `id`'s type. A Host trusting that then had to build a JSON-RPC response
+ * carrying a non-spec `id` back at the View, which the View's own correlation map (keyed by
+ * string ids) could never match — not a crash, but a real protocol violation this function exists
+ * specifically to catch. Now: if `id` is present at all, its type is checked before anything else,
+ * for every message shape (request, notification, or response) — a notification legitimately has
+ * no `id`, but a message that HAS one must have a valid one.
+ *
+ * The 2026-07-29 audit found the rest of that check was still far too generous, in three ways, all
+ * of them reachable from anything able to post at the frame:
+ *
+ * - **`params` went unread.** Any string `method` returned `true` immediately, so
+ *   `{method: 'tools/call', params: 'nope'}` reached dispatch and a handler reading
+ *   `params.capabilityId` got `undefined` rather than a refusal. §4.2 fixes the type: Array or
+ *   Object.
+ * - **The four shapes were not kept apart.** JSON-RPC 2.0 defines request, notification, success
+ *   response and error response as distinct, mutually exclusive objects. A message carrying both
+ *   `method` and `result` passed as a request; one carrying both `result` and `error` passed as a
+ *   response, which §5 forbids in as many words ("Either the result member or error member MUST be
+ *   included, but both members MUST NOT be included").
+ * - **`error` was accepted as any value at all**, `error: "boom"` included, so a host formatting
+ *   `error.message` back to a user read a property off a string.
+ *
+ * A message whose `method` is present but not a string is rejected outright rather than falling
+ * through to the response branch — reinterpreting a malformed request as a response is how one
+ * bad message becomes two wrong behaviors.
+ *
+ * @param value - The raw `event.data`.
+ * @returns True when the value is a well-formed JSON-RPC message.
+ */
+export function isJsonRpcMessage(value) {
+    if (!isRecord(value) || value['jsonrpc'] !== '2.0')
+        return false;
+    if ('id' in value && typeof value['id'] !== 'number' && typeof value['id'] !== 'string')
+        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);
+    }
+    // Response: correlated by `id`, carrying exactly one of `result` / `error`.
+    if (!('id' in value))
+        return false;
+    const hasResult = 'result' in value;
+    const hasError = 'error' in value;
+    if (hasResult === hasError)
+        return false;
+    return hasResult || isJsonRpcErrorObject(value['error']);
+}
+/** Whether a validated message expects a response (as opposed to being a notification). */
+export function isJsonRpcRequest(message) {
+    return 'id' in message && typeof message.method === 'string';
+}
+/**
+ * Builds a request.
+ *
+ * @param id - Correlation id, unique per in-flight request. Doubles as the idempotency key: a
+ * transport that redelivers (an SSE reconnect, a repeated post) must not execute twice.
+ * @param method - Method name.
+ * @param params - Optional parameters.
+ */
+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) {
+    return { jsonrpc: '2.0', method, ...(params === undefined ? {} : { params }) };
+}
+/** Builds a success response for `id`. */
+export function createJsonRpcResult(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+/** Builds an error response for `id`. */
+export function createJsonRpcError(id, code, message, data) {
+    return { jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } };
+}
+/**
+ * Builds a Jini page-action request.
+ *
+ * @param id - Correlation/idempotency id.
+ * @param capabilityId - A `page.*` capability id.
+ * @param input - Capability arguments.
+ * @returns The namespaced extension request.
+ */
+export function createPageActionRequest(id, capabilityId, input) {
+    return createJsonRpcRequest(id, JINI_PAGE_ACTION_METHOD, { capabilityId, input });
+}
+//# sourceMappingURL=mcp-ui-apps.js.map

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * @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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-capabilities.d.ts","sourceRoot":"","sources":["../../src/core/page-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAWrD,eAAO,MAAM,iBAAiB,EAAE,SAAS,aAAa,EAiIrD,CAAC"}