@zackbart/connecta 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,179 @@
 
 All notable changes to this package are documented here.
 
+## 0.13.0 — 2026-08-03
+
+Everything an agent reads before it calls anything got more selective. Connecta
+ships its first maintained prebuilt connection — `mixpanel()` behind
+`./providers/mixpanel`, one import returning one ordinary `Connector` with the
+provider's endpoint, region, auth, and rate-limit defaults already right — and
+the ethos now names a maintained prebuilt connection the preferred authoring
+path, with `remoteMcp()` and `api()` staying equal first-class primitives for
+everything nobody maintains. Connector guides became structured: a guide can
+declare a bounded `summary` and mark itself `required`, and discovery carries
+`guideSummary` with `guideRequired`/`guideRequiredReasons`, so an agent fetches
+a guide when it changes the call and skips it when a complete read-only schema
+already says everything. A connector-scoped search whose catalog is down now
+returns a typed `catalogError` instead of advice to retry later. And the tool
+descriptions stopped inviting the two failures the new cold-agent benchmark
+kept catching: a top-level search that duplicates the one the program was about
+to run, and a program guessing at a result shape it never read.
+
+No API breaks. `usageGuide` still accepts a plain markdown string and means
+exactly what it did; every new discovery field is additive and absent unless
+earned. What changed under existing deployments is text, and it is worth
+knowing about: the served tool descriptions and the MCP `instructions` string
+are rewritten, and `skills({})` now summarizes a connector guide from its first
+body line rather than its heading — a guide opening `# Acme` that used to list
+as "Acme" now lists as the sentence beneath it. The built-in usage skill also
+grew, because the per-connector guides section is now appended unconditionally
+rather than only where a guide exists; that keeps the shared guide
+byte-identical across every deployment, so an agent that read it once in a task
+never needs a second local copy, at the cost of one paragraph in deployments
+with no guides. Upgrading is a version bump and nothing else — there is no new
+configuration, no new dependency, and no behavior a deployment must opt into
+(#294, #295, #296, #297, PRs #298–#302).
+
+### Added
+
+- **A maintained Mixpanel connection at `./providers/mixpanel`.**
+  `mixpanel(id, { purpose, region?, auth?, instructions?, title?,
+  maxResultBytes? })` proxies Mixpanel's hosted MCP server with the endpoint
+  chosen by data residency (`us`, `eu`, `in`, default `us`), OAuth by default
+  and static headers for service accounts, HTTPS required, and a rolling
+  600-calls-per-hour admission budget matching the provider's published limit.
+  It carries a maintained usage guide — start at `Get-Projects`, then
+  `Get-Business-Context`; discover names instead of guessing spellings; fetch
+  `Get-Query-Schema` before `Run-Query` — to which a deployment may append its
+  own account instructions. The subpath is an optional import, not a
+  dependency: nothing new installs with core.
+- **Fill-in-only vetted safety annotations.** The connection classifies 63
+  Mixpanel tools — 35 read-only, 28 writes split into additive creates and
+  destructive edits — but only where the downstream is silent. An explicit
+  `destructiveHint: true` or `readOnlyHint: false` from Mixpanel on an
+  allowlisted read name wins, because that is the downstream saying this
+  release's allowlist is wrong. Tools this release has never seen fail closed
+  to approval-visible rather than being assumed safe.
+- **`ConnectorUsageGuide`.** A connector may now declare
+  `usageGuide: { content, summary?, required? }` instead of a bare string.
+  `summary` is the bounded line discovery shows; `required: true` says correct
+  use always depends on conventions no tool schema can carry. Mutations and
+  truncated schemas already require review and do not need the flag.
+- **`guideSummary`, `guideRequired`, and `guideRequiredReasons` on discovery.**
+  `search_tools`, `connecta.search`, and `connecta.describe` now say what a
+  guide covers and whether it must be read first, with the reason named:
+  `connector_required` and `approval_required` stand however far a schema is
+  expanded, while `schema_truncated` clears once describe returns the exact
+  shape. A connector-scoped search that matches nothing still surfaces the
+  connector's guide, so an agent that searched the wrong terms learns the
+  vocabulary instead of concluding the connector is empty.
+- **A scoped `catalogError`.** A search explicitly scoped to one connector
+  whose catalog is unavailable now returns the classified failure — `code`,
+  bounded `message`, `retryable`, and `retryAfterMs` when known — so an agent
+  can tell a transient outage from one an operator has to clear. Exactly four
+  fields, pinned by a test: an unscoped search still gets only
+  `unavailableConnectorCount`, because one connector's failure is not another
+  search's context.
+
+### Changed
+
+- **Routing guidance no longer invites redundant discovery.** Top-level
+  `search_tools` is now reserved for a single unreduced read or for
+  write-capable work; anything involving reduction, dependent steps, loops, or
+  joins is one `execute_code` program that searches and calls inside the run.
+  Search guidance also tells an agent to scope to an obvious connector id and
+  to require purpose, input, truncation, safety, and output fit rather than
+  taking the first lexical match. Measured against the shipped text over five
+  repetitions, route compliance went from 9/30 to 25/30.
+- **`call_destructive_tool` carries the guide note.** Destructive multi-step
+  work keeps its route through top-level discovery — `execute_code` admits only
+  read-only tools — and its description now says to inspect the address and
+  fetch any guide it names before a consequential call.
+- **The ethos prefers prebuilt connections, and refuses a registry.** The
+  decisions table accepts prebuilt connections as the preferred authoring path
+  *when connecta maintains one*, fenced: exactly one ordinary `Connector` with
+  no extra privileges, never a bundle or preset, tools hand-written or proxied
+  rather than generated from a schema document, and vetted annotations that
+  only fill in downstream silence. A provider registry or integration
+  marketplace is refused outright — prebuilt connections are imports, not
+  listings, and discovery happens in documentation, never at runtime.
+- **The usage skill is byte-identical everywhere.** The per-connector guides
+  section is appended unconditionally and rewritten to route on
+  `guideRequired`/`guideSummary` rather than telling agents to read every
+  guide before first use. Guide-free deployments still pay no fixed
+  tool-description cost — the conditional notes in the meta-tool descriptions
+  remain absent.
+- **Guide summaries prefer substance over headings.** `skills({})` reads a
+  guide's first meaningful body line, falling back to the heading and then to
+  the connector description, so a listing describes what a guide says rather
+  than what it is titled.
+
+### Fixed
+
+- **The Mixpanel connection could not have booted.** Its call-admission rule
+  paired a budget with `retryAfterMs` — a queue setting without a queue, which
+  the admission controller refuses at construction. No suite caught it because
+  every suite stubbed remote-MCP before the registry saw the connector; a new
+  suite now boots two accounts through the real `createConnecta` with `fetch`
+  rigged to throw, proving the boot and the per-account address, catalog,
+  storage, credential, and budget namespaces.
+- **Tool descriptions claimed a waiver describe already performs.** Three
+  descriptions said schema expansion never clears a guide requirement while
+  `describe` cleared `schema_truncated` on every call. The text moved to the
+  behavior rather than the reverse.
+- **Package-surface guards derive from `src/providers/`** instead of naming
+  `mixpanel.ts`, so the next provider fails them only for a real reason.
+
+### Internal
+
+- **A cold-agent benchmark lane in `eval/`.** Fourteen cases across two lanes —
+  eight measuring whether an agent meeting a connector cold discovers, routes,
+  and recovers, six measuring route compliance for the description rewrite —
+  with a comparator that refuses to compare runs whose harness, scoring, or
+  sandbox fingerprints differ, and reports a `productSha256` over `src/**`. A
+  baseline and a candidate cut from one working tree record the same commit and
+  the same dirty flag, and only the fingerprint says whether the candidate
+  measured changed code. It also reports host-routing probes separately from
+  foreign calls, so a contaminated run announces itself instead of reading as a
+  product regression. `eval/` is not in the published `files` list; deployments
+  never see it.
+
+## 0.12.2 — 2026-08-02
+
+Rendered programs can now bind a small, explicit set of read-only connector
+calls into their view. `connecta.ui(html, { reads })` validates every binding
+against the request-local catalog before accepting the UI, and the trusted
+Apps shell exposes only those names and declared view arguments through
+`connecta.read`. The program markup never receives connector addresses or a
+general tool channel, and mutation-capable tools remain unavailable. Existing
+`connecta.ui(html)` calls are byte-for-byte unchanged and remain display-only;
+deployments whose views do not need refresh, pagination, or drill-down reads
+can ignore this release. No deployment configuration changes are required
+(#287, #289, PR #290).
+
+### Added
+
+- **Bounded read bindings for rendered views.** Programs may bind 1–32 names
+  to catalog addresses proven read-only, with optional fixed arguments and an
+  allowlist of view-supplied arguments. The manifest shares the existing
+  emitted-byte budget and binding does not dispatch a call or spend the
+  program's host-call budget.
+- **A narrow `connecta.read(name, args)` view API.** The trusted outer shell
+  translates bound names into ordinary `call_tool` requests, reusing its
+  current authorization, catalog, and safety checks. It rejects unknown names,
+  undeclared arguments, fixed-argument overrides, and more than eight
+  concurrent reads.
+
+### Changed
+
+- **The program UI resource advances to `/v2`.** The new shell requires the
+  host's MCP Apps server-tools capability and makes only `call_tool` visible to
+  the app; the other six meta-tools remain model-only. Display-only views do
+  not receive the read bridge.
+- **The UI security contract is explicit.** The new design record defines the
+  data flow, threat model, validation rules, executor parity, and the boundary
+  between accepted reads and still-gated mutations.
+
 ## 0.12.1 — 2026-08-01
 
 Instructions, not behavior. Calling-side feedback and a first-hand run of the

package/README.md

@@ -72,7 +72,10 @@ For an agent setting this up, the contract is:
 2. Keep the required `executor: quickJsExecutor()` configuration; without an
    executor the deployment refuses to boot.
 3. Keep secrets in environment variables or a secret store, never source.
-4. Add code only for deliberate `api()` connectors.
+4. Add connectors explicitly: import a maintained prebuilt provider
+   constructor when one exists, otherwise write a deliberate `remoteMcp()` or
+   `api()` connector. There is no registry to browse and nothing registers
+   itself.
 5. Run `npm run typecheck`, start the server, and run
    `CONNECTA_TOKEN=... npm run doctor`. Doctor checks health, the executor, and
    the exact seven-tool model-facing surface, then executes a harmless sandbox

package/dist/apps-shell.d.ts

@@ -3,16 +3,16 @@
  *
  * 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 declare const PROGRAM_UI_RESOURCE_URI = "ui://connecta/program-ui/v1";
+export declare const PROGRAM_UI_RESOURCE_URI = "ui://connecta/program-ui/v2";
 /** The mimeType the Apps spec requires of an HTML template. */
 export declare const PROGRAM_UI_MIME_TYPE = "text/html;profile=mcp-app";
 /**
@@ -29,10 +29,12 @@ export declare 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 declare const PROGRAM_UI_SHELL_HTML = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <title>connecta program view</title>\n    <style>\n      html,\n      body {\n        margin: 0;\n        padding: 0;\n        background: transparent;\n      }\n      #program-view {\n        display: block;\n        width: 100%;\n        min-height: 480px;\n        border: 0;\n      }\n    </style>\n  </head>\n  <body>\n    <iframe\n      id=\"program-view\"\n      title=\"Program-rendered view\"\n      sandbox=\"allow-scripts\"\n      srcdoc=\"\"\n    ></iframe>\n    <script>\n      (function () {\n        \"use strict\";\n        // The host frame is the only peer this shell speaks to, in either\n        // direction. The payload frame below is sandboxed to scripts alone,\n        // with no same-origin escape, and is never handed a reply path:\n        // anything it posts fails the source check and is dropped. There is\n        // no bridge from program HTML to the host, by construction rather\n        // than by validation.\n        var host = window.parent;\n        var view = document.getElementById(\"program-view\");\n        var initializeId = \"connecta-ui-initialize\";\n        var lastWidth = 0;\n        var lastHeight = 0;\n\n        function send(message) {\n          if (!host || host === window) return;\n          host.postMessage(message, \"*\");\n        }\n\n        function notify(method, params) {\n          send({ jsonrpc: \"2.0\", method: method, params: params });\n        }\n\n        // Program views are fixed-height by construction. The shell has no\n        // bridge to the payload frame \u2014 that is the security posture, not an\n        // omission \u2014 so it can never learn the payload's content height, and\n        // what it reports here is its own box: the min-height above, unless\n        // the host has given it more. Taller content scrolls inside the inner\n        // frame rather than growing the view. Raising the min-height is the\n        // only lever; a content-height signal would cost the isolation.\n        function reportSize() {\n          var width = Math.ceil(document.documentElement.clientWidth);\n          var height = Math.ceil(document.documentElement.scrollHeight);\n          if (width === lastWidth && height === lastHeight) return;\n          lastWidth = width;\n          lastHeight = height;\n          notify(\"ui/notifications/size-changed\", {\n            width: width,\n            height: height\n          });\n        }\n\n        function payloadHtml(result) {\n          if (!result || typeof result !== \"object\") return null;\n          var meta = result._meta;\n          if (!meta || typeof meta !== \"object\") return null;\n          var payload = meta[\"connecta/ui\"];\n          if (!payload || typeof payload !== \"object\") return null;\n          var html = payload.html;\n          return typeof html === \"string\" && html.length > 0 ? html : null;\n        }\n\n        function render(params) {\n          var html =\n            payloadHtml(params) ||\n            payloadHtml(params && params.result) ||\n            payloadHtml(params && params.toolResult);\n          if (html === null) return;\n          view.srcdoc = html;\n          reportSize();\n        }\n\n        window.addEventListener(\"message\", function (event) {\n          if (event.source !== host) return;\n          var message = event.data;\n          if (!message || message.jsonrpc !== \"2.0\") return;\n          if (message.method === \"ui/notifications/tool-result\") {\n            render(message.params);\n            return;\n          }\n          if (message.method === \"ui/resource-teardown\") {\n            // A host->view request, not a notification: the host waits for\n            // this reply before it tears the view down. There is nothing to\n            // release, so answer immediately rather than make it time out.\n            if (message.id !== undefined && message.id !== null) {\n              send({ jsonrpc: \"2.0\", id: message.id, result: {} });\n            }\n            return;\n          }\n          // Only a completed handshake earns \"initialized\". A JSON-RPC error\n          // response carries the same id, and announcing initialization on one\n          // would assert a handshake that never happened.\n          if (message.id === initializeId && message.result !== undefined) {\n            notify(\"ui/notifications/initialized\", {});\n          }\n        });\n\n        window.addEventListener(\"resize\", reportSize);\n        view.addEventListener(\"load\", reportSize);\n\n        // Every field here is required by the Apps initialize schema, and a\n        // conforming host rejects the request outright when one is missing \u2014\n        // which would strand the shell before any tool result arrives.\n        send({\n          jsonrpc: \"2.0\",\n          id: initializeId,\n          method: \"ui/initialize\",\n          params: {\n            appInfo: { name: \"connecta program view\", version: \"1\" },\n            appCapabilities: {},\n            protocolVersion: \"2026-01-26\"\n          }\n        });\n        reportSize();\n      })();\n    </script>\n  </body>\n</html>\n";
+export declare const PROGRAM_UI_SHELL_HTML = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <title>connecta program view</title>\n    <style>\n      html,\n      body {\n        margin: 0;\n        padding: 0;\n        background: transparent;\n      }\n      #program-view {\n        display: block;\n        width: 100%;\n        min-height: 480px;\n        border: 0;\n      }\n    </style>\n  </head>\n  <body>\n    <iframe\n      id=\"program-view\"\n      title=\"Program-rendered view\"\n      sandbox=\"allow-scripts\"\n      srcdoc=\"\"\n    ></iframe>\n    <script>\n      (function () {\n        \"use strict\";\n        // The outer shell is the only host peer. The payload frame is\n        // sandboxed to scripts alone, with no same-origin escape. Its one\n        // optional message dialect is handled below and translated into\n        // bounded call_tool requests; raw JSON-RPC is never forwarded.\n        var host = window.parent;\n        var view = document.getElementById(\"program-view\");\n        var initializeId = \"connecta-ui-initialize\";\n        var lastWidth = 0;\n        var lastHeight = 0;\n        var reads = null;\n        var hostCanCallTools = false;\n        var nextHostRequestId = 0;\n        var pendingHostReads = Object.create(null);\n        var activeHostReads = 0;\n        var maxActiveHostReads = 8;\n\n        function send(message) {\n          if (!host || host === window) return;\n          host.postMessage(message, \"*\");\n        }\n\n        function notify(method, params) {\n          send({ jsonrpc: \"2.0\", method: method, params: params });\n        }\n\n        // Program views are fixed-height by construction. The shell has no\n        // content-height bridge to the payload frame, so it can never learn\n        // the payload's content height, and\n        // what it reports here is its own box: the min-height above, unless\n        // the host has given it more. Taller content scrolls inside the inner\n        // frame rather than growing the view. Raising the min-height is the\n        // only lever; a content-height signal would cost the isolation.\n        function reportSize() {\n          var width = Math.ceil(document.documentElement.clientWidth);\n          var height = Math.ceil(document.documentElement.scrollHeight);\n          if (width === lastWidth && height === lastHeight) return;\n          lastWidth = width;\n          lastHeight = height;\n          notify(\"ui/notifications/size-changed\", {\n            width: width,\n            height: height\n          });\n        }\n\n        function payload(result) {\n          if (!result || typeof result !== \"object\") return null;\n          var meta = result._meta;\n          if (!meta || typeof meta !== \"object\") return null;\n          var value = meta[\"connecta/ui\"];\n          if (!value || typeof value !== \"object\") return null;\n          return typeof value.html === \"string\" && value.html.length > 0\n            ? value\n            : null;\n        }\n\n        // This function is serialized into the opaque-origin payload frame.\n        // It knows no addresses and has no host channel of its own: one named\n        // read request goes to the trusted outer shell and one correlated\n        // result comes back.\n        function payloadReadBridge() {\n          \"use strict\";\n          var pending = Object.create(null);\n          var nextId = 0;\n\n          function read(name, args) {\n            return new Promise(function (resolve, reject) {\n              var id = String(++nextId);\n              pending[id] = { resolve: resolve, reject: reject };\n              try {\n                window.parent.postMessage({\n                  type: \"connecta/read\",\n                  id: id,\n                  name: name,\n                  args: args === undefined ? {} : args\n                }, \"*\");\n              } catch (error) {\n                delete pending[id];\n                reject(error);\n              }\n            });\n          }\n\n          Object.defineProperty(globalThis, \"connecta\", {\n            value: Object.freeze({ read: read }),\n            configurable: false,\n            enumerable: true,\n            writable: false\n          });\n\n          window.addEventListener(\"message\", function (event) {\n            if (event.source !== window.parent) return;\n            var message = event.data;\n            if (!message || message.type !== \"connecta/read-result\") return;\n            var waiter = pending[message.id];\n            if (!waiter) return;\n            delete pending[message.id];\n            if (message.ok) waiter.resolve(message.value);\n            else waiter.reject(new Error(message.error || \"Read failed\"));\n          });\n        }\n\n        function htmlWithReadBridge(html) {\n          var script =\n            \"<scr\" + \"ipt>(\" + payloadReadBridge.toString() + \")();</scr\" + \"ipt>\";\n          var head = /<head(?:\\s[^>]*)?>/i.exec(html);\n          if (head) {\n            var at = (head.index || 0) + head[0].length;\n            return html.slice(0, at) + script + html.slice(at);\n          }\n          var document = /<html(?:\\s[^>]*)?>/i.exec(html);\n          if (document) {\n            var afterHtml = (document.index || 0) + document[0].length;\n            return html.slice(0, afterHtml) + \"<head>\" + script + \"</head>\" + html.slice(afterHtml);\n          }\n          return script + html;\n        }\n\n        function render(params) {\n          var value =\n            payload(params) ||\n            payload(params && params.result) ||\n            payload(params && params.toolResult);\n          if (value === null) return;\n          reads = value.reads && typeof value.reads === \"object\"\n            ? value.reads\n            : null;\n          view.srcdoc = reads\n            ? htmlWithReadBridge(value.html)\n            : value.html;\n          reportSize();\n        }\n\n        function readError(message, fallback) {\n          if (message && typeof message.message === \"string\") return message.message;\n          if (message && message.data && typeof message.data.message === \"string\") {\n            return message.data.message;\n          }\n          return fallback;\n        }\n\n        function finishInnerRead(innerId, ok, value) {\n          if (!view.contentWindow) return;\n          view.contentWindow.postMessage(ok\n            ? { type: \"connecta/read-result\", id: innerId, ok: true, value: value }\n            : { type: \"connecta/read-result\", id: innerId, ok: false, error: value }, \"*\");\n        }\n\n        function beginInnerRead(message) {\n          if (!hostCanCallTools) {\n            finishInnerRead(message && message.id, false, \"This host does not support app-initiated server tool calls\");\n            return;\n          }\n          if (!message || typeof message.id !== \"string\" || typeof message.name !== \"string\") return;\n          if (!reads || !Object.prototype.hasOwnProperty.call(reads, message.name)) {\n            finishInnerRead(message.id, false, \"Unknown read binding\");\n            return;\n          }\n          if (activeHostReads >= maxActiveHostReads) {\n            finishInnerRead(message.id, false, \"Too many concurrent reads\");\n            return;\n          }\n          var binding = reads[message.name];\n          if (!binding || typeof binding !== \"object\" || typeof binding.address !== \"string\") {\n            finishInnerRead(message.id, false, \"Invalid read binding\");\n            return;\n          }\n          var supplied = message.args;\n          if (!supplied || typeof supplied !== \"object\" || Array.isArray(supplied)) {\n            finishInnerRead(message.id, false, \"Read arguments must be an object\");\n            return;\n          }\n          var allowed = Array.isArray(binding.viewArgs) ? binding.viewArgs : [];\n          var suppliedKeys = Object.keys(supplied);\n          for (var i = 0; i < suppliedKeys.length; i++) {\n            var key = suppliedKeys[i];\n            if (allowed.indexOf(key) === -1) {\n              finishInnerRead(message.id, false, \"Undeclared read argument \" + JSON.stringify(key));\n              return;\n            }\n          }\n          var args = Object.create(null);\n          var fixed = binding.fixedArgs && typeof binding.fixedArgs === \"object\"\n            ? binding.fixedArgs\n            : {};\n          Object.keys(fixed).forEach(function (key) { args[key] = fixed[key]; });\n          suppliedKeys.forEach(function (key) { args[key] = supplied[key]; });\n\n          var hostId = \"connecta-ui-read-\" + String(++nextHostRequestId);\n          pendingHostReads[hostId] = { innerId: message.id };\n          activeHostReads++;\n          send({\n            jsonrpc: \"2.0\",\n            id: hostId,\n            method: \"tools/call\",\n            params: {\n              name: \"call_tool\",\n              arguments: {\n                address: binding.address,\n                args: args,\n                resultMode: \"value\"\n              }\n            }\n          });\n        }\n\n        function finishHostRead(message) {\n          var pending = pendingHostReads[message.id];\n          if (!pending) return false;\n          delete pendingHostReads[message.id];\n          activeHostReads--;\n          if (message.error) {\n            finishInnerRead(pending.innerId, false, readError(message.error, \"Host rejected read\"));\n            return true;\n          }\n          var toolResult = message.result;\n          if (!toolResult || typeof toolResult !== \"object\") {\n            finishInnerRead(pending.innerId, false, \"Host returned an invalid tool result\");\n            return true;\n          }\n          var structured = toolResult.structuredContent;\n          if (toolResult.isError || (structured && structured.ok === false)) {\n            var detail = structured && structured.error;\n            var content = Array.isArray(toolResult.content)\n              ? toolResult.content.find(function (block) { return block && block.type === \"text\"; })\n              : null;\n            finishInnerRead(\n              pending.innerId,\n              false,\n              readError(detail, content && content.text ? content.text : \"Read failed\")\n            );\n            return true;\n          }\n          var value = structured && structured.ok === true &&\n              Object.prototype.hasOwnProperty.call(structured, \"data\")\n            ? structured.data\n            : structured !== undefined\n              ? structured\n              : toolResult;\n          finishInnerRead(pending.innerId, true, value);\n          return true;\n        }\n\n        window.addEventListener(\"message\", function (event) {\n          var message = event.data;\n          if (event.source === view.contentWindow) {\n            if (message && message.type === \"connecta/read\") beginInnerRead(message);\n            return;\n          }\n          if (event.source !== host) return;\n          if (!message || message.jsonrpc !== \"2.0\") return;\n          if (message.id !== undefined && finishHostRead(message)) return;\n          if (message.method === \"ui/notifications/tool-result\") {\n            render(message.params);\n            return;\n          }\n          if (message.method === \"ui/resource-teardown\") {\n            // A host->view request, not a notification: the host waits for\n            // this reply before it tears the view down. There is nothing to\n            // release, so answer immediately rather than make it time out.\n            if (message.id !== undefined && message.id !== null) {\n              send({ jsonrpc: \"2.0\", id: message.id, result: {} });\n            }\n            return;\n          }\n          // Only a completed handshake earns \"initialized\". A JSON-RPC error\n          // response carries the same id, and announcing initialization on one\n          // would assert a handshake that never happened.\n          if (message.id === initializeId && message.result !== undefined) {\n            var capabilities = message.result.hostCapabilities;\n            hostCanCallTools = Boolean(capabilities && capabilities.serverTools);\n            notify(\"ui/notifications/initialized\", {});\n          }\n        });\n\n        window.addEventListener(\"resize\", reportSize);\n        view.addEventListener(\"load\", reportSize);\n\n        // Every field here is required by the Apps initialize schema, and a\n        // conforming host rejects the request outright when one is missing \u2014\n        // which would strand the shell before any tool result arrives.\n        send({\n          jsonrpc: \"2.0\",\n          id: initializeId,\n          method: \"ui/initialize\",\n          params: {\n            appInfo: { name: \"connecta program view\", version: \"1\" },\n            appCapabilities: {},\n            protocolVersion: \"2026-01-26\"\n          }\n        });\n        reportSize();\n      })();\n    </script>\n  </body>\n</html>\n";
 //# sourceMappingURL=apps-shell.d.ts.map

package/dist/apps-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps-shell.d.ts","sourceRoot":"","sources":["../src/apps-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAErE,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,+BAA+B,CAAC;AAE/D;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,ssKAyIjC,CAAC"}
+{"version":3,"file":"apps-shell.d.ts","sourceRoot":"","sources":["../src/apps-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAErE,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,+BAA+B,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,07ZAsUjC,CAAC"}

package/dist/apps-shell.js

@@ -3,16 +3,16 @@
  *
  * 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";
 /**
@@ -29,10 +29,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">
@@ -65,17 +67,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;
@@ -87,8 +93,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
@@ -105,30 +111,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;
@@ -146,6 +335,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/dist/apps-shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"apps-shell.js","sourceRoot":"","sources":["../src/apps-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAC;AAErE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,2BAA2B,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAEjD,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,4BAA4B,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyIpC,CAAC"}
+{"version":3,"file":"apps-shell.js","sourceRoot":"","sources":["../src/apps-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAC;AAErE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,2BAA2B,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAEjD,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,4BAA4B,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsUpC,CAAC"}