@jini-ai/agentic 0.4.1 → 0.4.3

package/dist/guards.js

@@ -0,0 +1,186 @@
+/**
+ * @module guards
+ *
+ * The refusals that must hold on every surface, expressed over plain descriptors rather than
+ * DOM nodes so they are testable in Node and reusable from any framework binding.
+ *
+ * Both guards here answer review findings that an allowlist alone does not cover: a generic
+ * filler will happily type into a password or card-number field even when that field carries a
+ * legitimate handle, and `data-agent-label` is page-authored text that reaches a model as if
+ * the host had written it.
+ */
+/** Input types no automated caller may ever write to. */
+const DENIED_TYPES = new Set(['password', 'hidden', 'file', 'image']);
+/** Autocomplete tokens covering credentials, payment instruments and one-time codes. */
+const DENIED_AUTOCOMPLETE = new Set([
+    'current-password', 'new-password', 'one-time-code',
+    'cc-number', 'cc-exp', 'cc-exp-month', 'cc-exp-year', 'cc-csc', 'cc-name', 'cc-type',
+]);
+/**
+ * Substrings in `name`/`id` that indicate a secret even when type/autocomplete are unset.
+ *
+ * Matched against {@link squashSeparators}'d text, so the multi-word entries catch the separator
+ * spellings people actually use. `api_key`, `api-key` and `apiKey` are all the same field; a
+ * literal-substring match sees only the last one, which is the least common of the three.
+ */
+const SUSPICIOUS_NAME = /(?:password|passwd|secret|token|csrf|xsrf|otp|cvv|cvc|ssn|creditcard|cardnumber|apikey|ccnumber|cardnum|accountnumber|routing|iban|sortcode|securitycode|passphrase|privatekey|clientsecret|accesskey|secretkey|recoverycode|backupcode|mfa)/i;
+// Deliberately NOT added as bare substrings, even though both are real PCI/banking terms
+// ("pin", "PAN" — Primary Account Number): they collide with ordinary field names once
+// separators are squashed out. `shipping` contains "pin"; `company` contains "pan". Adding
+// either here would refuse a large share of legitimate, non-sensitive fields. See
+// guards.test.ts's "does not refuse ordinary fields that happen to contain pin/pan as a
+// substring" test — it exists specifically so a future edit cannot add either back silently.
+/**
+ * Drops everything that is not a letter or digit, so separator conventions do not decide whether
+ * a guard fires. Over-matching is the safe direction here and is the point: this guard fails
+ * closed, and the cost of a false positive is a field an agent must leave to the user.
+ *
+ * Normalizes before squashing rather than after, because the naive squash used to *delete* any
+ * character outside ASCII `[a-z0-9]` instead of folding it. Deleting, not folding, is the bug:
+ * replacing one letter of a trigger word with a look-alike codepoint (fullwidth, accented, …)
+ * used to remove that letter from the squashed string entirely, so `ｐassword` (fullwidth
+ * U+FF50 `ｐ`) squashed to `assword` and matched nothing. NFKC folds that class of look-alike —
+ * fullwidth/halfwidth forms, and the Latin compatibility block — to its ordinary ASCII form
+ * before the letter can be deleted. The NFD pass afterward strips combining marks so an accented
+ * letter (`á` → `a` + combining acute) folds the same way once the mark itself is dropped.
+ *
+ * This does NOT close the general homoglyph class. NFKC has no cross-script confusables table:
+ * Cyrillic `а` (U+0430) and Greek `ο` (U+03BF) stay distinct codepoints from Latin `a`/`o` after
+ * NFKC, so `pаssword` (Cyrillic а) still squashes to something other than `password` and still
+ * bypasses `SUSPICIOUS_NAME`. Closing that would need an explicit confusables-folding table
+ * (e.g. Unicode TR39's) mapping each look-alike script's letters onto Latin before squashing —
+ * deliberately not built here; see the "known limit" test in guards.test.ts for the concrete gap.
+ */
+function squashSeparators(value) {
+    const foldedWidth = value.normalize('NFKC');
+    const withoutMarks = foldedWidth.normalize('NFD').replace(/\p{M}/gu, '');
+    return withoutMarks.replace(/[^a-z0-9]/gi, '');
+}
+/**
+ * Input types that hold no text.
+ *
+ * Writing to one succeeds mechanically and accomplishes nothing: setting `value` on a checkbox
+ * changes the string submitted *if* it is ticked, and leaves `checked` alone. The caller is told
+ * the fill worked and the box is still clear — a false success, which is worse than a refusal
+ * because it is never retried.
+ */
+const NON_TEXT_TYPES = new Set(['checkbox', 'radio', 'submit', 'reset', 'button']);
+/**
+ * Why this field's current value must not be reported back to a caller, or `null` when reading
+ * it is safe.
+ *
+ * Reading is the strictly more dangerous direction: writing into a password box gives an agent
+ * nothing, whereas reading one out hands over the secret itself. So every secrecy signal the fill
+ * guard uses applies here identically — type, autocomplete token, and a name or id that indicates
+ * a credential or anti-forgery token — and none of them may be relaxed for reads.
+ *
+ * @param field - The field's attributes.
+ * @returns The first secrecy refusal, or `null` when the value may be reported.
+ */
+export function findFieldReadRefusal(field) {
+    const type = field.type?.toLowerCase();
+    if (type !== undefined && DENIED_TYPES.has(type))
+        return 'denied-type';
+    const autocomplete = field.autocomplete?.toLowerCase();
+    if (autocomplete !== undefined) {
+        // The real grammar is space-separated tokens, but a comma-joined value
+        // (`"new-password,current-password"`) is markup an attacker-controlled page can trivially
+        // emit even though real browsers won't autofill it correctly either — splitting on
+        // whitespace alone turned the whole string into one unrecognized token, so the field still
+        // worked as a plain text input while looking unguarded.
+        for (const token of autocomplete.split(/[\s,]+/)) {
+            if (DENIED_AUTOCOMPLETE.has(token))
+                return 'denied-autocomplete';
+        }
+    }
+    if (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.
+        //
+        // Each label is squashed and matched on its own rather than as one joined string: squashing
+        // 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;
+}
+/**
+ * Why an automated fill must be refused for this field, or `null` when it is safe to write.
+ *
+ * Fails closed on anything that looks like a credential, payment instrument, one-time code, or
+ * anti-forgery token, independent of whether the field carries an agent handle. Tagging a
+ * password box does not make it fillable. Every secrecy refusal is also a fill refusal — a field
+ * whose contents an agent may not read is certainly not one it may overwrite — and two further
+ * refusals cover fields that are simply not writable.
+ *
+ * @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);
+    if (secrecy !== null)
+        return secrecy;
+    const type = field.type?.toLowerCase();
+    if (type !== undefined && NON_TEXT_TYPES.has(type))
+        return 'not-text';
+    if (field.readOnly === true)
+        return 'read-only';
+    if (field.disabled === true)
+        return 'disabled';
+    return null;
+}
+const FIELD_REFUSAL_MESSAGES = {
+    'denied-type': 'this field type can never be filled by an agent',
+    'denied-autocomplete': 'this field holds a credential or payment instrument',
+    'suspicious-name': 'this field name indicates a secret or anti-forgery token',
+    'not-text': 'this control holds no text — activate it with the click verb instead of filling it',
+    'read-only': 'this field is read-only',
+    disabled: 'this field is disabled',
+};
+const FIELD_READ_REFUSAL_MESSAGES = {
+    'denied-type': 'this field type is never readable by an agent',
+    'denied-autocomplete': 'this field holds a credential or payment instrument',
+    '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) {
+    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) {
+    return FIELD_READ_REFUSAL_MESSAGES[refusal];
+}
+/** Default cap on page-authored text handed to a model. */
+export const MAX_AGENT_LABEL_LENGTH = 200;
+/**
+ * C0/C1 control characters plus the Unicode bidirectional and invisible formatting ranges.
+ *
+ * The bidi overrides matter as much as the control codes: `U+202E` and friends let page text
+ * render one way and read another, which is a direct way to smuggle a different instruction
+ * into whatever reads the label back.
+ */
+const CONTROL_AND_BIDI = 
+// eslint-disable-next-line no-control-regex
+/[\u0000-\u001F\u007F-\u009F\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g;
+/**
+ * Normalizes page-authored text before it reaches a model.
+ *
+ * Strips control characters (including the bidirectional overrides used to make text render
+ * differently from how it reads), collapses whitespace, and caps the length. The result is still
+ * untrusted *content* — this only bounds it; it does not make it safe to follow as instruction.
+ *
+ * @param raw - Text read off the page, e.g. a `data-agent-label`.
+ * @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) {
+    const stripped = raw.replace(CONTROL_AND_BIDI, ' ');
+    const collapsed = stripped.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= maxLength)
+        return { text: collapsed, truncated: false };
+    return { text: collapsed.slice(0, maxLength), truncated: true };
+}
+//# sourceMappingURL=guards.js.map

package/dist/handle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module handle
+ *
+ * `agentHandle('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
+ * 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.
+ */
+import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, type AgentElementRole } from './element-handles.js';
+/** Optional markup to attach alongside the handle itself. */
+export interface AgentHandleOptions {
+    /** What verb applies to this element — see {@link AgentElementRole}. */
+    readonly role?: AgentElementRole;
+    /** Stable, page-authored ontology for this element (e.g. `"Full name"`). Never live text. */
+    readonly label?: string;
+    /** Which published page this element belongs to, for a multi-page host. */
+    readonly page?: string;
+}
+/** The attribute props {@link agentHandle} returns, ready to spread onto an element. */
+export type AgentHandleProps = {
+    readonly [AGENT_ELEMENT_ATTRIBUTE]: string;
+} & Partial<Record<typeof AGENT_ROLE_ATTRIBUTE | typeof AGENT_LABEL_ATTRIBUTE | typeof AGENT_PAGE_ATTRIBUTE, string>>;
+/**
+ * Builds the attribute props that publish `handle` as an agent-addressable element.
+ *
+ * @param handle - The handle to publish. Must satisfy {@link isValidElementHandle} — this
+ *   function reuses that exact rule rather than a second, possibly-diverging check, since an
+ *   adversarial probe already confirmed it rejects quotes, brackets, backslashes, unicode and
+ *   overlong handles (see `element-handles.ts`).
+ * @param options - Optional role/label/page markup.
+ * @returns Attribute props to spread onto the element that should carry this handle.
+ * @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;
+//# sourceMappingURL=handle.d.ts.map

package/dist/handle.js

@@ -0,0 +1,41 @@
+/**
+ * @module handle
+ *
+ * `agentHandle('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
+ * 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.
+ */
+import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, isValidElementHandle, } from './element-handles.js';
+/**
+ * Builds the attribute props that publish `handle` as an agent-addressable element.
+ *
+ * @param handle - The handle to publish. Must satisfy {@link isValidElementHandle} — this
+ *   function reuses that exact rule rather than a second, possibly-diverging check, since an
+ *   adversarial probe already confirmed it rejects quotes, brackets, backslashes, unicode and
+ *   overlong handles (see `element-handles.ts`).
+ * @param options - Optional role/label/page markup.
+ * @returns Attribute props to spread onto the element that should carry this handle.
+ * @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)) {
+        throw new Error(`invalid element handle "${handle.slice(0, 128)}": `
+            + 'handles are lowercase words joined by single hyphens, and are never CSS selectors');
+    }
+    const props = { [AGENT_ELEMENT_ATTRIBUTE]: handle };
+    if (options.role !== undefined)
+        props[AGENT_ROLE_ATTRIBUTE] = options.role;
+    if (options.label !== undefined)
+        props[AGENT_LABEL_ATTRIBUTE] = options.label;
+    if (options.page !== undefined)
+        props[AGENT_PAGE_ATTRIBUTE] = options.page;
+    return props;
+}
+//# sourceMappingURL=handle.js.map

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/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