@jini-ai/agentic 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @jini-ai/agentic
 
+## 0.4.2 — 2026-10-06
+
+- `@jini-ai/agentic/a2ui`: `A2UI_DISPLAY_ONLY_PROPERTY` (`"displayOnly"` on `createSurface.surfaceProperties`) plus `displayOnlySurfaceIdOf` and `a2uiSurfaceIdOf` readers.
+
+## 0.4.1 — 2026-10-04
+
+- `createAnnotatedActionsScript` registers a published page's annotated actions with WebMCP.
+- Internal `@jini-ai/*` dependencies are caret ranges (`workspace:^`) instead of exact pins, so a host on a newer patch resolves a single copy without an override.
+
 ## 0.4.0 — 2026-10-02
 
 ### BREAKING

package/dist/core/a2ui/index.d.ts

@@ -13,4 +13,5 @@ export * from './json-pointer.js';
 export * from './resolve.js';
 export * from './tree.js';
 export * from './interpreter.js';
+export * from './surface-properties.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/a2ui/index.js

@@ -13,4 +13,5 @@ export * from './json-pointer.js';
 export * from './resolve.js';
 export * from './tree.js';
 export * from './interpreter.js';
+export * from './surface-properties.js';
 //# sourceMappingURL=index.js.map

package/dist/core/a2ui/surface-properties.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module surface-properties
+ *
+ * Reading facts about a surface off the raw wire messages, without an interpreter.
+ *
+ * Why a display-only marker: a host's chat pane treats a surface that arrives while its tool call is
+ * still open as a question the person must answer ("Waiting for your answer above"). That is right
+ * for a form or a choice, and wrong for a chart a tool draws and then holds its call open only to
+ * hear whether the browser refused it (Tovu demo V3, 2026-10-05). The tool that emits the surface is
+ * the only party that knows which it is, so it says so on `createSurface.surfaceProperties`, which
+ * the v1.0 schema already accepts as an open record; renderers ignore the key.
+ */
+/** `createSurface.surfaceProperties` key: `true` means the surface shows something and asks nothing. */
+export declare const A2UI_DISPLAY_ONLY_PROPERTY = "displayOnly";
+/**
+ * The `surfaceId` a surface-scoped message (create/update components/update data/delete) names, or
+ * `undefined` for any other message or a malformed value. Never throws.
+ *
+ * @complexity O(1).
+ */
+export declare function a2uiSurfaceIdOf({ message }: {
+    message: unknown;
+}): string | undefined;
+/**
+ * The `surfaceId` of a `createSurface` that declares {@link A2UI_DISPLAY_ONLY_PROPERTY} `true`, else
+ * `undefined`. Only `createSurface` carries surface properties, so a caller folding a stream records
+ * the id here and matches later messages with {@link a2uiSurfaceIdOf}.
+ *
+ * @complexity O(1).
+ */
+export declare function displayOnlySurfaceIdOf({ message }: {
+    message: unknown;
+}): string | undefined;
+//# sourceMappingURL=surface-properties.d.ts.map

package/dist/core/a2ui/surface-properties.js

@@ -0,0 +1,49 @@
+/**
+ * @module surface-properties
+ *
+ * Reading facts about a surface off the raw wire messages, without an interpreter.
+ *
+ * Why a display-only marker: a host's chat pane treats a surface that arrives while its tool call is
+ * still open as a question the person must answer ("Waiting for your answer above"). That is right
+ * for a form or a choice, and wrong for a chart a tool draws and then holds its call open only to
+ * hear whether the browser refused it (Tovu demo V3, 2026-10-05). The tool that emits the surface is
+ * the only party that knows which it is, so it says so on `createSurface.surfaceProperties`, which
+ * the v1.0 schema already accepts as an open record; renderers ignore the key.
+ */
+/** `createSurface.surfaceProperties` key: `true` means the surface shows something and asks nothing. */
+export const A2UI_DISPLAY_ONLY_PROPERTY = 'displayOnly';
+const SURFACE_SCOPED_KEYS = ['createSurface', 'updateComponents', 'updateDataModel', 'deleteSurface'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * The `surfaceId` a surface-scoped message (create/update components/update data/delete) names, or
+ * `undefined` for any other message or a malformed value. Never throws.
+ *
+ * @complexity O(1).
+ */
+export function a2uiSurfaceIdOf({ message }) {
+    if (!isRecord(message))
+        return undefined;
+    for (const key of SURFACE_SCOPED_KEYS) {
+        const body = message[key];
+        if (isRecord(body) && typeof body.surfaceId === 'string')
+            return body.surfaceId;
+    }
+    return undefined;
+}
+/**
+ * The `surfaceId` of a `createSurface` that declares {@link A2UI_DISPLAY_ONLY_PROPERTY} `true`, else
+ * `undefined`. Only `createSurface` carries surface properties, so a caller folding a stream records
+ * the id here and matches later messages with {@link a2uiSurfaceIdOf}.
+ *
+ * @complexity O(1).
+ */
+export function displayOnlySurfaceIdOf({ message }) {
+    const body = isRecord(message) ? message.createSurface : undefined;
+    if (!isRecord(body) || typeof body.surfaceId !== 'string')
+        return undefined;
+    const properties = body.surfaceProperties;
+    return isRecord(properties) && properties[A2UI_DISPLAY_ONLY_PROPERTY] === true ? body.surfaceId : undefined;
+}
+//# sourceMappingURL=surface-properties.js.map

package/dist/core/annotated-actions-script.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Framework-free script asset for data-toolname/data-tooldescription actions.
+ * Native tool* forms remain the browser's responsibility. No polyfill, transport,
+ * field-value reader, arbitrary selector input or cross-origin exposure is added.
+ * The host owns consent copy and its browser preference key. This string asset
+ * can be inlined into static exports without importing a DOM runtime on Node.
+ */
+export declare function createAnnotatedActionsScript({ preferenceKey, confirmationMessage, confirmationMessages }: {
+    preferenceKey?: string;
+    confirmationMessage?: string;
+    confirmationMessages?: Readonly<Record<string, string>>;
+}, _optional?: Record<string, never>): string;
+//# sourceMappingURL=annotated-actions-script.d.ts.map

package/dist/core/annotated-actions-script.js

@@ -0,0 +1,137 @@
+/**
+ * Framework-free script asset for data-toolname/data-tooldescription actions.
+ * Native tool* forms remain the browser's responsibility. No polyfill, transport,
+ * field-value reader, arbitrary selector input or cross-origin exposure is added.
+ * The host owns consent copy and its browser preference key. This string asset
+ * can be inlined into static exports without importing a DOM runtime on Node.
+ */
+export function createAnnotatedActionsScript({ preferenceKey, confirmationMessage = 'Allow this browser-agent action?', confirmationMessages = {} }, _optional = {}) {
+    const config = JSON.stringify({ preferenceKey, confirmationMessage, confirmationMessages }).replace(/</g, '\\u003c');
+    return String.raw `(function install(config) {
+    'use strict';
+    var doc = document;
+    var locale = (doc.documentElement.lang || 'en').toLowerCase();
+    var messages = config.confirmationMessages;
+    var confirmation = Object.keys(messages).find(function (key) { return key.toLowerCase() === locale; });
+    var confirmationMessage = messages[confirmation] || messages[locale.split('-')[0]] || config.confirmationMessage;
+    var stopped = false;
+    var registrations = [];
+    var observer;
+    function enabled() {
+      try { return !config.preferenceKey || localStorage.getItem(config.preferenceKey) !== 'false'; }
+      catch (_) { return true; }
+    }
+    function stripNativeForms() {
+      doc.querySelectorAll('form[toolname]').forEach(function (form) {
+        ['toolname', 'tooldescription', 'toolautosubmit'].forEach(function (name) { form.removeAttribute(name); });
+      });
+    }
+    function stop(event) {
+      stopped = true;
+      registrations.forEach(function (controller) { controller.abort(); });
+      registrations = [];
+      if (observer) observer.disconnect();
+      window.removeEventListener('storage', onStorage);
+      window.removeEventListener('pagehide', stop);
+      // A cached Document executes no scripts when the browser restores it.
+      // Reinstall on pageshow, while old callbacks remain permanently stopped.
+      if (event && event.persisted) window.addEventListener('pageshow', function () { install(config); }, { once: true });
+    }
+    function onStorage(event) {
+      if (event.key !== null && event.key !== config.preferenceKey) return;
+      if (!enabled()) { stripNativeForms(); stop(); }
+    }
+    if (!enabled()) { stripNativeForms(); return; }
+    var context = [doc.modelContext, typeof navigator !== 'undefined' && navigator.modelContext].find(function (value) {
+      return value && typeof value.registerTool === 'function';
+    });
+    if (!context || typeof context.registerTool !== 'function') return;
+    function visible(element) {
+      if (!element.isConnected || element.closest('[hidden], [inert], [aria-hidden="true"], dialog:not([open])')) return false;
+      for (var current = element; current; current = current.parentElement) {
+        var style = window.getComputedStyle(current);
+        if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') return false;
+      }
+      return true;
+    }
+    function descriptor(element) {
+      var name = element.getAttribute('data-toolname') || '';
+      var description = element.getAttribute('data-tooldescription') || '';
+      if (!/^[A-Za-z0-9_.-]{1,128}$/.test(name) || !description.trim() || !visible(element)) return null;
+      if (element.matches(':disabled, [aria-disabled="true"]')) return null;
+      if (element.tagName === 'A') {
+        if (!element.hasAttribute('href') || element.hasAttribute('download')) return null;
+        var url;
+        try { url = new URL(element.getAttribute('href'), doc.baseURI); } catch (_) { return null; }
+        if (!/^https?:$/.test(url.protocol) || url.origin !== window.location.origin || url.username || url.password) return null;
+        return { name: name, description: description, href: url.href };
+      }
+      // Inputs and form submission are intentionally absent: declarative forms
+      // preserve native validation and human submission, with no secret fields.
+      if (element.tagName !== 'BUTTON' || element.type !== 'button') return null;
+      return { name: name, description: description, href: null };
+    }
+    function refresh() {
+      registrations.forEach(function (controller) { controller.abort(); });
+      registrations = [];
+      if (stopped || !enabled()) { stripNativeForms(); stop(); return; }
+      var counts = new Map();
+      doc.querySelectorAll('[data-toolname], form[toolname]').forEach(function (element) {
+        if (!visible(element)) return;
+        var name = element.getAttribute('data-toolname') || element.getAttribute('toolname');
+        counts.set(name, (counts.get(name) || 0) + 1);
+      });
+      doc.querySelectorAll('[data-toolname]').forEach(function (element) {
+        var action = descriptor(element);
+        if (!action || counts.get(action.name) !== 1) return;
+        var controller = new AbortController();
+        registrations.push(controller);
+        function current() {
+          var latest = descriptor(element);
+          var matches = Array.from(doc.querySelectorAll('[data-toolname], form[toolname]')).filter(function (candidate) {
+            return visible(candidate) && (candidate.getAttribute('data-toolname') || candidate.getAttribute('toolname')) === action.name;
+          });
+          if (stopped || controller.signal.aborted || !enabled() || !latest ||
+              matches.length !== 1 || latest.name !== action.name || latest.description !== action.description || latest.href !== action.href) {
+            throw new Error('Browser-agent action is unavailable');
+          }
+        }
+        var tool = {
+          name: action.name,
+          description: action.description,
+          inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+          annotations: { readOnlyHint: action.href !== null },
+          execute: async function (args) {
+            current();
+            if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).length !== 0) {
+              throw new Error('This action takes no arguments');
+            }
+            if (action.href !== null) {
+              // Navigation has no click-handler side effects and cannot forward
+              // arbitrary agent-supplied URLs or use a theme's cross-origin base.
+              window.location.assign(action.href);
+              return { navigationRequested: true };
+            }
+            if (!window.confirm(confirmationMessage + '\n\n' + action.description)) {
+              throw new Error('Browser-agent action declined');
+            }
+            current();
+            element.click();
+            // Activation acknowledges the UI event, never business success.
+            return { activated: true };
+          }
+        };
+        try {
+          Promise.resolve(context.registerTool(tool, { signal: controller.signal })).catch(function () { controller.abort(); });
+        } catch (_) { controller.abort(); }
+      });
+    }
+    window.addEventListener('pagehide', stop);
+    window.addEventListener('storage', onStorage);
+    refresh();
+    observer = new MutationObserver(refresh);
+    observer.observe(doc.documentElement, { subtree: true, childList: true, attributes: true,
+      attributeFilter: ['data-toolname', 'data-tooldescription', 'toolname', 'href', 'download', 'type', 'disabled', 'aria-disabled', 'hidden', 'inert', 'aria-hidden', 'style', 'class', 'open'] });
+  })(` + config + ');';
+}
+//# sourceMappingURL=annotated-actions-script.js.map

package/dist/core/index.d.ts

@@ -73,4 +73,5 @@ export { toAgUiTool, toAgUiTools, createAgUiToolResult, AG_UI_TOOL_CALL_EVENTS,
 export { createGenUiEncoder, type GenUiEncodeContext, type GenUiEncoder, type GenUiAgentMessageEvent, type GenUiEvent, type GenUiEventBase, type GenUiEventKind, type GenUiRunLifecycleEvent, type GenUiStateUpdateEvent, type GenUiSurfaceRequestedEvent, type GenUiSurfaceRespondedEvent, type GenUiToolCallEvent, } from './gen-ui/index.js';
 export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_VIEW_NOTIFICATIONS, MCP_UI_HOST_REQUESTS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcNotification, type JsonRpcResponse, type JsonRpcError, } from './mcp-ui-apps.js';
 export { defaultAgenticMessages } from "./messages.js";
+export { createAnnotatedActionsScript } from './annotated-actions-script.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -72,4 +72,5 @@ export { toAgUiTool, toAgUiTools, createAgUiToolResult, AG_UI_TOOL_CALL_EVENTS,
 export { createGenUiEncoder, } from './gen-ui/index.js';
 export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_VIEW_NOTIFICATIONS, MCP_UI_HOST_REQUESTS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, } from './mcp-ui-apps.js';
 export { defaultAgenticMessages } from "./messages.js";
+export { createAnnotatedActionsScript } from './annotated-actions-script.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agentic",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Framework-free agent-control layer: page-capability vocabulary and manifests, the data-agent-* markup convention, AG-UI projection, generative-UI streams, and A2UI.",
   "license": "Apache-2.0",
   "repository": {
@@ -75,7 +75,7 @@
   "dependencies": {
     "zod": "^3.25.76",
     "@jini-ai/core": "^0.4.0",
-    "@jini-ai/protocol": "0.4.0"
+    "@jini-ai/protocol": "^0.4.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^2.1.9",