npm - @zackbart/connecta - Versions diffs - 0.12.1 → 0.12.2 - Mend

@zackbart/connecta 0.12.1 → 0.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/CHANGELOG.md +36 -0
package/dist/apps-shell.d.ts +13 -11
package/dist/apps-shell.d.ts.map +1 -1
package/dist/apps-shell.js +221 -30
package/dist/apps-shell.js.map +1 -1
package/dist/execute.d.ts +12 -4
package/dist/execute.d.ts.map +1 -1
package/dist/execute.js +131 -11
package/dist/execute.js.map +1 -1
package/dist/meta-tools.d.ts.map +1 -1
package/dist/meta-tools.js +9 -0
package/dist/meta-tools.js.map +1 -1
package/dist/skills.d.ts +2 -2
package/dist/skills.d.ts.map +1 -1
package/dist/skills.js +3 -2
package/dist/skills.js.map +1 -1
package/dist/version.d.ts +1 -1
package/dist/version.js +1 -1
package/documentation/code-mode.md +26 -14
package/documentation/mcp-ui-design.md +8 -8
package/documentation/program-ui-read-calls.md +213 -0
package/ethos.md +2 -1
package/package.json +1 -1
package/src/apps-shell.ts +221 -30
package/src/execute.ts +198 -12
package/src/meta-tools.ts +9 -0
package/src/skills.ts +3 -2
package/src/version.ts +1 -1
package/templates/node/package.json +1 -1

package/src/apps-shell.ts CHANGED Viewed

@@ -3,17 +3,17 @@
  *
  * A build-time string constant, not a file read at startup: the core is
  * Web-API-only so it runs unchanged on Workers, and the same bytes have to
- * serve everywhere. The shell is display-only — it renders whatever HTML a
- * program handed `connecta.ui` inside a nested `srcdoc` frame and forwards no
- * channel back from that frame to the host, so program-authored markup is
- * inert beyond its own pixels.
+ * serve everywhere. It renders whatever HTML a program handed `connecta.ui`
+ * inside a nested `srcdoc` frame. The one-argument form forwards no channel;
+ * an explicitly bound view gets only named read calls through the trusted
+ * shell, never a raw host channel.
  *
  * The address carries a version segment because hosts are permitted to
- * prefetch and cache templates by URI: change these bytes, bump `v1`.
+ * prefetch and cache templates by URI: change these bytes, bump the version.
  */
 /** The only `ui://` URI in the system. No program input reaches it. */
-export const PROGRAM_UI_RESOURCE_URI = "ui://connecta/program-ui/v1";
+export const PROGRAM_UI_RESOURCE_URI = "ui://connecta/program-ui/v2";
 /** The mimeType the Apps spec requires of an HTML template. */
 export const PROGRAM_UI_MIME_TYPE = "text/html;profile=mcp-app";
@@ -34,10 +34,12 @@ export const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
  * Apps postMessage dialect (`ui/initialize`, `ui/notifications/initialized`,
  * `ui/notifications/tool-result`, `ui/notifications/size-changed`,
  * `ui/resource-teardown`), lifts `_meta["connecta/ui"].html` out of the
- * delivered tool result, and puts it in a frame. It declares no CSP domains,
- * so the host applies its restrictive default and the `srcdoc` frame inherits
- * `default-src 'none'` — the payload gets scripts and local interactivity,
- * and no network.
+ * delivered tool result, and puts it in a frame. An optional read manifest
+ * installs one narrow `connecta.read(name, args)` bridge in that inner frame;
+ * the outer shell maps declared names to the existing `call_tool` meta-tool.
+ * It declares no CSP domains, so the host applies its restrictive default and
+ * the `srcdoc` frame inherits `default-src 'none'` — program markup still gets
+ * no direct network.
  */
 export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
 <html lang="en">
@@ -70,17 +72,21 @@ export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
     <script>
       (function () {
         "use strict";
-        // The host frame is the only peer this shell speaks to, in either
-        // direction. The payload frame below is sandboxed to scripts alone,
-        // with no same-origin escape, and is never handed a reply path:
-        // anything it posts fails the source check and is dropped. There is
-        // no bridge from program HTML to the host, by construction rather
-        // than by validation.
+        // The outer shell is the only host peer. The payload frame is
+        // sandboxed to scripts alone, with no same-origin escape. Its one
+        // optional message dialect is handled below and translated into
+        // bounded call_tool requests; raw JSON-RPC is never forwarded.
         var host = window.parent;
         var view = document.getElementById("program-view");
         var initializeId = "connecta-ui-initialize";
         var lastWidth = 0;
         var lastHeight = 0;
+        var reads = null;
+        var hostCanCallTools = false;
+        var nextHostRequestId = 0;
+        var pendingHostReads = Object.create(null);
+        var activeHostReads = 0;
+        var maxActiveHostReads = 8;
         function send(message) {
           if (!host || host === window) return;
@@ -92,8 +98,8 @@ export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
         }
         // Program views are fixed-height by construction. The shell has no
-        // bridge to the payload frame — that is the security posture, not an
-        // omission — so it can never learn the payload's content height, and
+        // content-height bridge to the payload frame, so it can never learn
+        // the payload's content height, and
         // what it reports here is its own box: the min-height above, unless
         // the host has given it more. Taller content scrolls inside the inner
         // frame rather than growing the view. Raising the min-height is the
@@ -110,30 +116,213 @@ export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
           });
         }
-        function payloadHtml(result) {
+        function payload(result) {
           if (!result || typeof result !== "object") return null;
           var meta = result._meta;
           if (!meta || typeof meta !== "object") return null;
-          var payload = meta["connecta/ui"];
-          if (!payload || typeof payload !== "object") return null;
-          var html = payload.html;
-          return typeof html === "string" && html.length > 0 ? html : null;
+          var value = meta["connecta/ui"];
+          if (!value || typeof value !== "object") return null;
+          return typeof value.html === "string" && value.html.length > 0
+            ? value
+            : null;
+        }
+        // This function is serialized into the opaque-origin payload frame.
+        // It knows no addresses and has no host channel of its own: one named
+        // read request goes to the trusted outer shell and one correlated
+        // result comes back.
+        function payloadReadBridge() {
+          "use strict";
+          var pending = Object.create(null);
+          var nextId = 0;
+          function read(name, args) {
+            return new Promise(function (resolve, reject) {
+              var id = String(++nextId);
+              pending[id] = { resolve: resolve, reject: reject };
+              try {
+                window.parent.postMessage({
+                  type: "connecta/read",
+                  id: id,
+                  name: name,
+                  args: args === undefined ? {} : args
+                }, "*");
+              } catch (error) {
+                delete pending[id];
+                reject(error);
+              }
+            });
+          }
+          Object.defineProperty(globalThis, "connecta", {
+            value: Object.freeze({ read: read }),
+            configurable: false,
+            enumerable: true,
+            writable: false
+          });
+          window.addEventListener("message", function (event) {
+            if (event.source !== window.parent) return;
+            var message = event.data;
+            if (!message || message.type !== "connecta/read-result") return;
+            var waiter = pending[message.id];
+            if (!waiter) return;
+            delete pending[message.id];
+            if (message.ok) waiter.resolve(message.value);
+            else waiter.reject(new Error(message.error || "Read failed"));
+          });
+        }
+        function htmlWithReadBridge(html) {
+          var script =
+            "<scr" + "ipt>(" + payloadReadBridge.toString() + ")();</scr" + "ipt>";
+          var head = /<head(?:\\s[^>]*)?>/i.exec(html);
+          if (head) {
+            var at = (head.index || 0) + head[0].length;
+            return html.slice(0, at) + script + html.slice(at);
+          }
+          var document = /<html(?:\\s[^>]*)?>/i.exec(html);
+          if (document) {
+            var afterHtml = (document.index || 0) + document[0].length;
+            return html.slice(0, afterHtml) + "<head>" + script + "</head>" + html.slice(afterHtml);
+          }
+          return script + html;
         }
         function render(params) {
-          var html =
-            payloadHtml(params) ||
-            payloadHtml(params && params.result) ||
-            payloadHtml(params && params.toolResult);
-          if (html === null) return;
-          view.srcdoc = html;
+          var value =
+            payload(params) ||
+            payload(params && params.result) ||
+            payload(params && params.toolResult);
+          if (value === null) return;
+          reads = value.reads && typeof value.reads === "object"
+            ? value.reads
+            : null;
+          view.srcdoc = reads
+            ? htmlWithReadBridge(value.html)
+            : value.html;
           reportSize();
         }
+        function readError(message, fallback) {
+          if (message && typeof message.message === "string") return message.message;
+          if (message && message.data && typeof message.data.message === "string") {
+            return message.data.message;
+          }
+          return fallback;
+        }
+        function finishInnerRead(innerId, ok, value) {
+          if (!view.contentWindow) return;
+          view.contentWindow.postMessage(ok
+            ? { type: "connecta/read-result", id: innerId, ok: true, value: value }
+            : { type: "connecta/read-result", id: innerId, ok: false, error: value }, "*");
+        }
+        function beginInnerRead(message) {
+          if (!hostCanCallTools) {
+            finishInnerRead(message && message.id, false, "This host does not support app-initiated server tool calls");
+            return;
+          }
+          if (!message || typeof message.id !== "string" || typeof message.name !== "string") return;
+          if (!reads || !Object.prototype.hasOwnProperty.call(reads, message.name)) {
+            finishInnerRead(message.id, false, "Unknown read binding");
+            return;
+          }
+          if (activeHostReads >= maxActiveHostReads) {
+            finishInnerRead(message.id, false, "Too many concurrent reads");
+            return;
+          }
+          var binding = reads[message.name];
+          if (!binding || typeof binding !== "object" || typeof binding.address !== "string") {
+            finishInnerRead(message.id, false, "Invalid read binding");
+            return;
+          }
+          var supplied = message.args;
+          if (!supplied || typeof supplied !== "object" || Array.isArray(supplied)) {
+            finishInnerRead(message.id, false, "Read arguments must be an object");
+            return;
+          }
+          var allowed = Array.isArray(binding.viewArgs) ? binding.viewArgs : [];
+          var suppliedKeys = Object.keys(supplied);
+          for (var i = 0; i < suppliedKeys.length; i++) {
+            var key = suppliedKeys[i];
+            if (allowed.indexOf(key) === -1) {
+              finishInnerRead(message.id, false, "Undeclared read argument " + JSON.stringify(key));
+              return;
+            }
+          }
+          var args = Object.create(null);
+          var fixed = binding.fixedArgs && typeof binding.fixedArgs === "object"
+            ? binding.fixedArgs
+            : {};
+          Object.keys(fixed).forEach(function (key) { args[key] = fixed[key]; });
+          suppliedKeys.forEach(function (key) { args[key] = supplied[key]; });
+          var hostId = "connecta-ui-read-" + String(++nextHostRequestId);
+          pendingHostReads[hostId] = { innerId: message.id };
+          activeHostReads++;
+          send({
+            jsonrpc: "2.0",
+            id: hostId,
+            method: "tools/call",
+            params: {
+              name: "call_tool",
+              arguments: {
+                address: binding.address,
+                args: args,
+                resultMode: "value"
+              }
+            }
+          });
+        }
+        function finishHostRead(message) {
+          var pending = pendingHostReads[message.id];
+          if (!pending) return false;
+          delete pendingHostReads[message.id];
+          activeHostReads--;
+          if (message.error) {
+            finishInnerRead(pending.innerId, false, readError(message.error, "Host rejected read"));
+            return true;
+          }
+          var toolResult = message.result;
+          if (!toolResult || typeof toolResult !== "object") {
+            finishInnerRead(pending.innerId, false, "Host returned an invalid tool result");
+            return true;
+          }
+          var structured = toolResult.structuredContent;
+          if (toolResult.isError || (structured && structured.ok === false)) {
+            var detail = structured && structured.error;
+            var content = Array.isArray(toolResult.content)
+              ? toolResult.content.find(function (block) { return block && block.type === "text"; })
+              : null;
+            finishInnerRead(
+              pending.innerId,
+              false,
+              readError(detail, content && content.text ? content.text : "Read failed")
+            );
+            return true;
+          }
+          var value = structured && structured.ok === true &&
+              Object.prototype.hasOwnProperty.call(structured, "data")
+            ? structured.data
+            : structured !== undefined
+              ? structured
+              : toolResult;
+          finishInnerRead(pending.innerId, true, value);
+          return true;
+        }
         window.addEventListener("message", function (event) {
-          if (event.source !== host) return;
           var message = event.data;
+          if (event.source === view.contentWindow) {
+            if (message && message.type === "connecta/read") beginInnerRead(message);
+            return;
+          }
+          if (event.source !== host) return;
           if (!message || message.jsonrpc !== "2.0") return;
+          if (message.id !== undefined && finishHostRead(message)) return;
           if (message.method === "ui/notifications/tool-result") {
             render(message.params);
             return;
@@ -151,6 +340,8 @@ export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
           // response carries the same id, and announcing initialization on one
           // would assert a handshake that never happened.
           if (message.id === initializeId && message.result !== undefined) {
+            var capabilities = message.result.hostCapabilities;
+            hostCanCallTools = Boolean(capabilities && capabilities.serverTools);
             notify("ui/notifications/initialized", {});
           }
         });

package/src/execute.ts CHANGED Viewed

@@ -28,6 +28,7 @@ import {
   InvocationService,
 } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
+import { isExplicitlyReadOnly } from "./tool-safety.js";
 import type {
   Executor,
   ExecutorProvider,
@@ -249,7 +250,23 @@ function requireEmittedBlock(raw: unknown): EmittedBlock {
 }
 const UI_SHAPE_HINT =
-  "connecta.ui accepts exactly one argument: a non-empty string of HTML";
+  "connecta.ui accepts exactly one HTML argument and, optionally, one read-binding options object";
+const MAX_UI_READ_BINDINGS = 32;
+const MAX_UI_VIEW_ARGS = 32;
+const UI_READ_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const FORBIDDEN_UI_KEY = new Set(["__proto__", "constructor", "prototype"]);
+interface UiReadBinding {
+  address: string;
+  fixedArgs: Record<string, unknown>;
+  viewArgs: string[];
+}
+interface UiPayload {
+  html: string;
+  reads?: Record<string, UiReadBinding>;
+}
 /** What the argument was, named the way the emit validator names a bad field. */
 function describeUiArgument(raw: unknown): string {
@@ -262,9 +279,9 @@ function describeUiArgument(raw: unknown): string {
 }
 /**
- * Strict U1 validation. There is no options parameter and no sugar form, for
- * M1's reason: sugar is how a one-shape contract grows hair. An options bag or
- * an MCP block object is just a non-string, and fails as one.
+ * Strict U1/V1 validation. The first argument remains HTML; the only second
+ * argument is one read-binding manifest. There are no alternate object or MCP
+ * block forms.
  */
 function requireUiHtml(raw: unknown): string {
   if (typeof raw !== "string" || raw.length === 0) {
@@ -273,6 +290,125 @@ function requireUiHtml(raw: unknown): string {
   return raw;
 }
+function requireRecord(raw: unknown, label: string): Record<string, unknown> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return raw as Record<string, unknown>;
+}
+function requireExactKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string,
+): void {
+  const extras = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (extras.length > 0) {
+    throw new Error(
+      `${label} carries unsupported field(s) ${extras.map((key) => JSON.stringify(key)).join(", ")}`,
+    );
+  }
+}
+function requireUiReadKey(raw: unknown, label: string): string {
+  if (
+    typeof raw !== "string" ||
+    raw.length === 0 ||
+    raw.length > 128 ||
+    FORBIDDEN_UI_KEY.has(raw)
+  ) {
+    throw new Error(
+      `${label} must be a non-empty string of at most 128 characters and cannot be __proto__, constructor, or prototype`,
+    );
+  }
+  return raw;
+}
+function requireUiReads(raw: unknown): Record<string, UiReadBinding> {
+  const record = requireRecord(raw, "connecta.ui options.reads");
+  const names = Object.keys(record);
+  if (names.length === 0 || names.length > MAX_UI_READ_BINDINGS) {
+    throw new Error(
+      `connecta.ui options.reads must contain from 1 through ${MAX_UI_READ_BINDINGS} named bindings`,
+    );
+  }
+  const reads = Object.create(null) as Record<string, UiReadBinding>;
+  for (const name of names) {
+    if (!UI_READ_NAME.test(name) || FORBIDDEN_UI_KEY.has(name)) {
+      throw new Error(
+        `connecta.ui read binding name ${JSON.stringify(name)} must match ${UI_READ_NAME}`,
+      );
+    }
+    const value = requireRecord(
+      record[name],
+      `connecta.ui read binding ${JSON.stringify(name)}`,
+    );
+    requireExactKeys(
+      value,
+      ["address", "fixedArgs", "viewArgs"],
+      `connecta.ui read binding ${JSON.stringify(name)}`,
+    );
+    if (typeof value.address !== "string" || value.address.length === 0) {
+      throw new Error(
+        `connecta.ui read binding ${JSON.stringify(name)} address must be a non-empty string`,
+      );
+    }
+    const fixedArgs =
+      value.fixedArgs === undefined
+        ? {}
+        : requireRecord(
+            value.fixedArgs,
+            `connecta.ui read binding ${JSON.stringify(name)} fixedArgs`,
+          );
+    const rawViewArgs = value.viewArgs ?? [];
+    if (!Array.isArray(rawViewArgs) || rawViewArgs.length > MAX_UI_VIEW_ARGS) {
+      throw new Error(
+        `connecta.ui read binding ${JSON.stringify(name)} viewArgs must be an array of at most ${MAX_UI_VIEW_ARGS} strings`,
+      );
+    }
+    const viewArgs = rawViewArgs.map((key) =>
+      requireUiReadKey(
+        key,
+        `connecta.ui read binding ${JSON.stringify(name)} viewArgs entry`,
+      )
+    );
+    if (new Set(viewArgs).size !== viewArgs.length) {
+      throw new Error(
+        `connecta.ui read binding ${JSON.stringify(name)} viewArgs must not repeat a key`,
+      );
+    }
+    for (const key of viewArgs) {
+      if (Object.prototype.hasOwnProperty.call(fixedArgs, key)) {
+        throw new Error(
+          `connecta.ui read binding ${JSON.stringify(name)} view argument ${JSON.stringify(key)} cannot override a fixed argument`,
+        );
+      }
+    }
+    reads[name] = {
+      address: value.address,
+      fixedArgs,
+      viewArgs,
+    };
+  }
+  return reads;
+}
+function requireUiPayload(values: unknown[]): UiPayload {
+  if (values.length !== 1 && values.length !== 2) {
+    throw new Error(
+      `${UI_SHAPE_HINT}; got ${values.length} arguments`,
+    );
+  }
+  const html = requireUiHtml(values[0]);
+  if (values.length === 1) return { html };
+  const options = requireRecord(values[1], "connecta.ui options");
+  requireExactKeys(options, ["reads"], "connecta.ui options");
+  if (!Object.prototype.hasOwnProperty.call(options, "reads")) {
+    throw new Error("connecta.ui options must contain reads");
+  }
+  return { html, reads: requireUiReads(options.reads) };
+}
 /**
  * Request-local collection for `connecta.emit` and `connecta.ui`. Budgets fail
  * loudly at the crossing call — nothing is partially accepted and prior blocks
@@ -288,7 +424,7 @@ export class EmitCollector {
   /** The shared transport aggregate: emitted blocks plus the UI payload. */
   bytes = 0;
   /** The one accepted UI payload (U2), delivered in result `_meta` on success. */
-  ui?: { html: string };
+  ui?: UiPayload;
   /** What the blocks alone cost, so the `emitted` aggregate stays a true pair. */
   private blockBytes = 0;
   constructor(
@@ -328,14 +464,28 @@ export class EmitCollector {
    * problem worth naming — that there is a second payload at all — and a
    * complaint about its type would send the author to fix the wrong thing.
    */
-  acceptUi(raw: unknown): void {
+  acceptUi(...values: unknown[]): void {
     if (this.ui) {
       throw new Error(
         "connecta.ui accepts at most one payload per run: a view was already accepted and stands",
       );
     }
-    const payload = { html: requireUiHtml(raw) };
-    const size = diagnosticsEncoder.encode(JSON.stringify(payload)).byteLength;
+    this.acceptUiPayload(requireUiPayload(values));
+  }
+  acceptUiPayload(payload: UiPayload): void {
+    if (this.ui) {
+      throw new Error(
+        "connecta.ui accepts at most one payload per run: a view was already accepted and stands",
+      );
+    }
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(payload);
+    } catch {
+      throw new Error("connecta.ui payload must be JSON-serializable");
+    }
+    const size = diagnosticsEncoder.encode(serialized).byteLength;
     if (this.bytes + size > this.maxBytes) {
       throw new Error(
         `connecta.ui byte budget exceeded: payload is ${size} serialized bytes with ${this.maxBytes - this.bytes} of ${this.maxBytes} remaining`,
@@ -619,6 +769,41 @@ export async function buildSandboxProviders(
     return outcome.value;
   };
+  /**
+   * A read binding is admitted while the program still owns the request. The
+   * shell later calls the ordinary `call_tool`, which repeats this same
+   * fail-closed check against the then-current catalog; validating here keeps
+   * a typo or destructive address from producing a view whose controls can
+   * never work, while validation at use keeps a stale view from retaining old
+   * authority.
+   */
+  const validateUiReads = async (payload: UiPayload): Promise<UiPayload> => {
+    if (!payload.reads) return payload;
+    const reads = Object.create(null) as Record<string, UiReadBinding>;
+    for (const [name, binding] of Object.entries(payload.reads)) {
+      const resolution = await catalog.resolveTool(
+        binding.address,
+        limits.signal !== undefined ? { signal: limits.signal } : {},
+      );
+      if (!resolution.ok) {
+        throw new Error(
+          `connecta.ui read binding ${JSON.stringify(name)} could not resolve ${JSON.stringify(binding.address)}: ${resolution.error.message}`,
+        );
+      }
+      if (!isExplicitlyReadOnly(resolution.resolved.definition)) {
+        throw new Error(
+          `connecta.ui read binding ${JSON.stringify(name)} refuses ${JSON.stringify(binding.address)}: the tool is not explicitly read-only`,
+        );
+      }
+      reads[name] = {
+        ...binding,
+        address:
+          `${resolution.resolved.connector.id}.${resolution.resolved.toolName}`,
+      };
+    }
+    return { html: payload.html, reads };
+  };
   return [
     {
       name: "connecta",
@@ -643,13 +828,14 @@ export async function buildSandboxProviders(
         // reason (U7): one more provider fn, no change to ExecuteResult or
         // the Executor contract. Delivery is the handler's job, not the
         // guest's — nothing here becomes addressable.
-        ui: async (html: unknown) => {
+        ui: async (...values: unknown[]) => {
           if (!limits.emitCollector) {
             throw new Error(
               "connecta.ui is unavailable: no emission collector was configured for this execution",
             );
           }
-          limits.emitCollector.acceptUi(html);
+          const payload = await validateUiReads(requireUiPayload(values));
+          limits.emitCollector.acceptUiPayload(payload);
         },
         batch: async (calls: unknown) => {
           const started = Date.now();
@@ -1043,7 +1229,7 @@ export function createExecuteTool(
       // _meta is where the Apps spec's best practices put data "not intended
       // for model context", and how shipped hosts behave. The shell reads
       // exactly this key out of the tool result the host delivers to it.
-      response._meta = { [PROGRAM_UI_META_KEY]: { html: emitted.ui.html } };
+      response._meta = { [PROGRAM_UI_META_KEY]: emitted.ui };
     }
     if (emitted.blocks.length > 0) {
       // Emitted image/audio blocks are valid MCP content that ToolResult's
@@ -1093,7 +1279,7 @@ Write an async arrow function. It runs with NO network, filesystem, timers, or i
 - connecta.call(address, args) and connecta.batch(calls) — call raw addresses. Every batch entry is { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }; destructure that, not a bare result.
 - connecta.search(args) and connecta.describe, taking { address: "<connectorId>.<toolName>" } or { addresses: [...] } — load and inspect request-local catalogs on demand. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; it changes results, not authority. Matches carrying schemas also list inputKeys, requiredInputKeys, and outputKeys — the schema's own names, checkable before building args. A missing list means the schema is not a plain object shape, not that the tool has no fields — read the schema.
 - connecta.emit(block) — deliver MCP content beside the JSON return: exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }, nothing else. Blocks are appended on success only, spend no host calls, and are budgeted per run (${emitBudgets.maxBlocks} blocks, ${emitBudgets.maxBytes} serialized bytes); an over-budget or invalid emit throws catchably and accepts nothing.
-- connecta.ui(html) — hand the client one rendered view: exactly one argument, a non-empty HTML string, no options, no block object. Delivered on success only, spends no host calls, and draws on the same ${emitBudgets.maxBytes}-byte budget connecta.emit does — one budget, not two; a second, over-budget, or invalid call throws catchably and accepts nothing. The view is display-only (no network, no tool calls, no links) and out of model context — the envelope reports only ui: true, so the model reads the return value, not the view: return the summary it should reason over, built from the same variables the view renders.
+- connecta.ui(html, options?) — deliver one view. One argument is display-only; for live reads pass { reads: { name: { address, fixedArgs?, viewArgs? } } }, then markup calls connecta.read(name, args). Read-only is validated; fixed keys cannot be overridden, undeclared keys fail, and discovery, writes, and network stay unavailable. Success-only, no binding call cost, and one budget, not two (${emitBudgets.maxBytes} shared emit bytes); a second, over-budget, or invalid call throws catchably. The bytes stay out of context, so the model reads the return value, not the view: return the initial summary from its variables; later reads update only the view.
 - console.log(...) — captured and returned with the result.
 Tool calls return plain values (MCP text is JSON-parsed when possible) and throw on downstream errors — use try/catch. A thrown error carries only a message, so use connecta.batch when a program must tell a policy refusal from a transient failure. Never retry a failure whose retryable is false, and never retry a rate_limited one immediately — the sandbox has no timers. Return a JSON-serializable value; large results are truncated, so reduce data in code rather than return raw payloads.

package/src/meta-tools.ts CHANGED Viewed

@@ -1484,6 +1484,7 @@ export function registerMetaTools(
       description: describedFor(registry, SKILLS_DESC, "skills"),
       inputSchema: z.object({ name: z.string().optional() }),
       annotations: READ_ONLY_LOCAL,
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.skills(args as SkillArgs),
   );
@@ -1508,6 +1509,7 @@ export function registerMetaTools(
         includeSchemas: z.enum(["compact", "json"]).optional(),
       }),
       annotations: READ_ONLY_REMOTE,
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.searchTools(args as SearchArgs),
   );
@@ -1520,6 +1522,10 @@ export function registerMetaTools(
       // call_tool admits only tools that are themselves explicitly read-only;
       // anything else is refused and routed to call_destructive_tool.
       annotations: READ_ONLY_REMOTE,
+      // The trusted program-view shell delegates bounded named reads here.
+      // It is already one of the seven model tools; app visibility adds no
+      // tool and this handler repeats ordinary fail-closed read admission.
+      _meta: { ui: { visibility: ["model", "app"] } },
     },
     async (args) => mt.callTool(args as CallArgs),
   );
@@ -1541,6 +1547,7 @@ export function registerMetaTools(
         readOnlyHint: false,
         openWorldHint: true,
       },
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => {
       // `reason` is the host's to display and connecta's to keep out of the
@@ -1568,6 +1575,7 @@ export function registerMetaTools(
         destructiveHint: false,
         openWorldHint: true,
       },
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.authorizeConnector(args as AuthorizeArgs),
   );
@@ -1586,6 +1594,7 @@ export function registerMetaTools(
         maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
       }),
       annotations: READ_ONLY_LOCAL,
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.getResult(args as GetResultArgs),
   );