@zackbart/connecta 0.12.0 → 0.12.2

package/dist/skills.d.ts

@@ -1,6 +1,6 @@
 import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Connecta exposes integrations behind seven meta-tools, and execute_code is the primary one: write an async arrow function and use connecta.search (empty query browses every catalog), connecta.describe, connecta.call, and connecta.batch inside it for discovery, two or more calls, dependent steps, loops, joins, and reducing large results before they reach you. For a single read at an unknown address, search_tools with 2\u20134 distinctive action/object terms and includeSchemas=\"compact\", then one call_tool \u2014 a lone cold call is cheaper direct than through a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: \"usage\" }).";
-export declare const USAGE_SKILL = "# Connecta usage\n\n## The surface\n\nSeven tools: `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`, `authorize_connector`, `get_result`, `skills`. Broad discovery and multi-call work live inside a program rather than in top-level tools.\n\n## Choose the smallest execution tool\n\nUse exact addresses returned by discovery; never invent one. Search with 2\u20134 distinctive action/object terms rather than the full request.\n\n- One read at an unknown address: `search_tools({ query, includeSchemas: \"compact\" })`, then `call_tool` once. A lone cold call is cheaper direct than through a program.\n- Anything wider \u2014 two or more calls, dependent steps, loops, joins, branching, browsing a whole catalog, or a result that must be reduced: one `execute_code` run.\n- Any unannotated, write-capable, or destructive call: `call_destructive_tool`, individually and only after reviewing its schema and consequences. Generated code cannot make one.\n- Truncated result: retry with `fields` when possible; otherwise page it with `get_result`.\n- `auth_required`: use `authorize_connector`, give its recovery handoff to the operator, then retry the original call.\n\n## Inside a program\n\nOne async arrow function. The only capabilities are one global per connector (`<connectorId>.<toolName>(args)`), the four `connecta` functions, and `console.log`.\n\n- What exists: `connecta.search({})` browses every catalog; add `safety: \"readOnly\"` for only calls the program can execute, and `connector: \"<id>\"` to browse one. This filters discovery results, not authority, and each match carries its `address` and annotations.\n- Exact schemas for known addresses: `connecta.describe({ address: \"connector.tool\" })` for one or `connecta.describe({ addresses: [...] })` for many; `format: \"json\"` only for exact constraints.\n- Two to ten independent calls: `connecta.batch([...])`. Each outcome is `{ address, ok: true, data }` or `{ address, ok: false, error, errorDetails: { code, retryable } }`, which is also how a program tells a policy refusal from a transient failure.\n- Search inside the run rather than searching first, and return only the reduction the answer needs \u2014 never raw payloads.\n- Only tools annotated `readOnlyHint: true` are reachable; the read-only gate, credentials, and admission are enforced below the sandbox, so nothing a program does widens what it can reach.\n";
+export declare const CONNECTA_INSTRUCTIONS = "Connecta exposes seven meta-tools. execute_code is primary: use connecta.search, describe, call, and batch for discovery, multiple or dependent calls, loops, joins, and result reduction. connecta.ui(html) is a guest function inside execute_code, never a connector address or search_tools result; pass one HTML string for display-only, or bind named read-only refresh/drill-down calls in its optional reads argument, and return the same initial summary data the HTML renders. For one read at an unknown address, search_tools with 2\u20134 distinctive action/object terms and includeSchemas=\"compact\", then one call_tool \u2014 a lone cold call is cheaper direct than a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: \"usage\" }).";
+export declare const USAGE_SKILL = "# Connecta usage\n\n## The surface\n\nSeven tools: `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`, `authorize_connector`, `get_result`, `skills`. Broad discovery and multi-call work live in a program, not in top-level tools.\n\n## Choose the smallest execution tool\n\nUse exact addresses from discovery; never invent one. Search 2\u20134 distinctive action/object terms, not the whole request.\n\n- One read at an unknown address: `search_tools({ query, includeSchemas: \"compact\" })`, then `call_tool` once \u2014 one cold call is cheaper direct than a program.\n- Anything wider \u2014 two or more calls, dependent steps, loops, joins, branching, a whole-catalog browse, or a result to reduce: one `execute_code` run.\n- Any unannotated, write-capable, or destructive call: `call_destructive_tool`, one at a time, after reviewing its schema and consequences.\n- Truncated result: retry with `fields`, else page it with `get_result`.\n- `auth_required`: `authorize_connector`, hand its recovery text to the operator, retry the call.\n\n## Inside a program\n\nOne async arrow function. The only capabilities are one global per connector (`<connectorId>.<toolName>(args)`), the `connecta` functions, and `console.log`.\n\n- `connecta.search({})` browses every catalog; `safety: \"readOnly\"` narrows to calls a program can execute, `connector: \"<id>\"` to one. This filters results, not authority; matches carry `address` and annotations.\n- Exact schemas: `connecta.describe({ address: \"connector.tool\" })` for one, `{ addresses: [...] }` for many; `format: \"json\"` only for exact constraints.\n- Two to ten independent calls: `connecta.batch([...])`. Each outcome is `{ address, ok: true, data }` or `{ address, ok: false, error, errorDetails: { code, retryable } }` \u2014 how a program tells a policy refusal from a transient failure.\n- Search inside the run, not before it; return only the reduction the answer needs, never raw payloads.\n- Only tools annotated `readOnlyHint: true` are reachable; the gate, credentials, and admission are enforced below the sandbox \u2014 nothing a program does widens its reach.\n\n## Rendering a view\n\n`connecta.ui(html)` renders a display-only view on success for the client, never for the model. Fetch first, check the shape in code. On a surprise \u2014 empty array, missing key \u2014 return a trimmed first record instead of rendering: the wrong view becomes the sample you needed. Otherwise render from the variables you return; the model reads the return value, not the view.\n\n";
 /**
  * Appended to USAGE_SKILL only when the deployment actually has at least one
  * connector guide. A deployment with none — every deployment that has not

package/dist/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,qBAAqB,+yBAC8vB,CAAC;AAEjyB,eAAO,MAAM,WAAW,u3EAyBvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,2eAIpC,CAAC;AAEF,mDAAmD;AACnD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAI5E;AA0BD,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAGvE;AAyDD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,YAAY,EAAE,CAc3E;AAED,MAAM,MAAM,WAAW,GACrB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,WAAW,CAwCb"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,qBAAqB,o5BACm2B,CAAC;AAEt4B,eAAO,MAAM,WAAW,mgFA8BvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,2eAIpC,CAAC;AAEF,mDAAmD;AACnD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAI5E;AA0BD,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAGvE;AAyDD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,YAAY,EAAE,CAc3E;AAED,MAAM,MAAM,WAAW,GACrB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,WAAW,CAwCb"}

package/dist/skills.js

@@ -1,29 +1,34 @@
-export const CONNECTA_INSTRUCTIONS = 'Connecta exposes integrations behind seven meta-tools, and execute_code is the primary one: write an async arrow function and use connecta.search (empty query browses every catalog), connecta.describe, connecta.call, and connecta.batch inside it for discovery, two or more calls, dependent steps, loops, joins, and reducing large results before they reach you. For a single read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than through a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
+export const CONNECTA_INSTRUCTIONS = 'Connecta exposes seven meta-tools. execute_code is primary: use connecta.search, describe, call, and batch for discovery, multiple or dependent calls, loops, joins, and result reduction. connecta.ui(html) is a guest function inside execute_code, never a connector address or search_tools result; pass one HTML string for display-only, or bind named read-only refresh/drill-down calls in its optional reads argument, and return the same initial summary data the HTML renders. For one read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
 export const USAGE_SKILL = `# Connecta usage
 
 ## The surface
 
-Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Broad discovery and multi-call work live inside a program rather than in top-level tools.
+Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Broad discovery and multi-call work live in a program, not in top-level tools.
 
 ## Choose the smallest execution tool
 
-Use exact addresses returned by discovery; never invent one. Search with 2–4 distinctive action/object terms rather than the full request.
+Use exact addresses from discovery; never invent one. Search 2–4 distinctive action/object terms, not the whole request.
 
-- One read at an unknown address: \`search_tools({ query, includeSchemas: "compact" })\`, then \`call_tool\` once. A lone cold call is cheaper direct than through a program.
-- Anything wider — two or more calls, dependent steps, loops, joins, branching, browsing a whole catalog, or a result that must be reduced: one \`execute_code\` run.
-- Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, individually and only after reviewing its schema and consequences. Generated code cannot make one.
-- Truncated result: retry with \`fields\` when possible; otherwise page it with \`get_result\`.
-- \`auth_required\`: use \`authorize_connector\`, give its recovery handoff to the operator, then retry the original call.
+- One read at an unknown address: \`search_tools({ query, includeSchemas: "compact" })\`, then \`call_tool\` once — one cold call is cheaper direct than a program.
+- Anything wider — two or more calls, dependent steps, loops, joins, branching, a whole-catalog browse, or a result to reduce: one \`execute_code\` run.
+- Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, one at a time, after reviewing its schema and consequences.
+- Truncated result: retry with \`fields\`, else page it with \`get_result\`.
+- \`auth_required\`: \`authorize_connector\`, hand its recovery text to the operator, retry the call.
 
 ## Inside a program
 
-One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the four \`connecta\` functions, and \`console.log\`.
+One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the \`connecta\` functions, and \`console.log\`.
+
+- \`connecta.search({})\` browses every catalog; \`safety: "readOnly"\` narrows to calls a program can execute, \`connector: "<id>"\` to one. This filters results, not authority; matches carry \`address\` and annotations.
+- Exact schemas: \`connecta.describe({ address: "connector.tool" })\` for one, \`{ addresses: [...] }\` for many; \`format: "json"\` only for exact constraints.
+- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\` — how a program tells a policy refusal from a transient failure.
+- Search inside the run, not before it; return only the reduction the answer needs, never raw payloads.
+- Only tools annotated \`readOnlyHint: true\` are reachable; the gate, credentials, and admission are enforced below the sandbox — nothing a program does widens its reach.
+
+## Rendering a view
+
+\`connecta.ui(html)\` renders a display-only view on success for the client, never for the model. Fetch first, check the shape in code. On a surprise — empty array, missing key — return a trimmed first record instead of rendering: the wrong view becomes the sample you needed. Otherwise render from the variables you return; the model reads the return value, not the view.
 
-- What exists: \`connecta.search({})\` browses every catalog; add \`safety: "readOnly"\` for only calls the program can execute, and \`connector: "<id>"\` to browse one. This filters discovery results, not authority, and each match carries its \`address\` and annotations.
-- Exact schemas for known addresses: \`connecta.describe({ address: "connector.tool" })\` for one or \`connecta.describe({ addresses: [...] })\` for many; \`format: "json"\` only for exact constraints.
-- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\`, which is also how a program tells a policy refusal from a transient failure.
-- Search inside the run rather than searching first, and return only the reduction the answer needs — never raw payloads.
-- Only tools annotated \`readOnlyHint: true\` are reachable; the read-only gate, credentials, and admission are enforced below the sandbox, so nothing a program does widens what it can reach.
 `;
 /**
  * Appended to USAGE_SKILL only when the deployment actually has at least one

package/dist/skills.js.map

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

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.12.0";
+export declare const CONNECTA_VERSION = "0.12.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.12.0";
+export const CONNECTA_VERSION = "0.12.2";
 //# sourceMappingURL=version.js.map

package/documentation/code-mode.md

@@ -326,7 +326,8 @@ classify, use `errorDetails`; to hand a failure to the model with its type
 intact, let it escape uncaught — connecta re-attaches the typed details on the
 way out. The model-facing version of this lives in `execute_code`'s description,
 not in the always-loaded usage skill, which `test/meta-tools.test.ts` caps at
-1,800 bytes with three bytes spare.
+2,500 bytes — a budget the guide already spends nearly all of, so new text there
+displaces old rather than adding to what every request pays for.
 
 **E2.** The taxonomy. `retryable` is what connecta reports; `Y3` says what a
 program may do about it.
@@ -502,10 +503,9 @@ the security posture live in the [design record](./mcp-ui-design.md)
 [#277](https://github.com/zackbart/connecta/issues/277)); this section is the
 contract, and it wins where the two disagree.
 
-**U1.** `connecta.ui(html)` accepts exactly one argument: a non-empty string of
-HTML. A non-string, an empty string, an options bag, or an MCP block object
-throws catchably and nothing is accepted. There is no options parameter and no
-sugar form, for `M1`'s reason: sugar is how a one-shape contract grows hair.
+**U1.** `connecta.ui(html, options?)` accepts one non-empty HTML string and at
+most the bounded read manifest `V1` defines. The one-argument call stays
+display-only; every other shape throws catchably and accepts nothing.
 
 **U2.** At most one payload per run. A second call throws catchably, naming the
 constraint; the first accepted payload stands. One tool result renders one view,
@@ -513,7 +513,7 @@ and last-wins would silently discard a payload the program deliberately
 supplied.
 
 **U3.** Delivered on success only, and out of model context: the tool result
-gains `_meta["connecta/ui"] = { html }` and the JSON envelope gains `ui: true`,
+gains `_meta["connecta/ui"] = { html, reads? }` and the JSON envelope gains `ui: true`,
 so the model learns a view rendered without seeing its bytes. `structuredContent`
 stays the envelope alone. The single-label `connecta/ui` prefix is deliberate —
 connecta has no domain to reverse, and fabricating one to satisfy MCP's
@@ -526,27 +526,27 @@ with `emittedDiscarded: N` when one failure discards both.
 
 **U4.** The payload spends the aggregate emit byte budget
 (`ConnectaConfig.execute.maxEmittedBytes`), measured at the call as the
-serialized bytes of `{ html }` — `M5`'s measurement. Over budget throws
+serialized bytes of `{ html, reads? }` — `M5`'s measurement. Over budget throws
 catchably, naming the budget and the room remaining, with nothing partially
 accepted. It spends no block count (`maxEmittedBlocks`: it is not a block) and no
 host-call budget (`L4`). One transport bound covers everything rich a program
 delivers.
 
 **U5.** One static shell: a connecta-authored HTML5 document at
-`ui://connecta/program-ui/v1`, mimeType `text/html;profile=mcp-app`, declared on
+`ui://connecta/program-ui/v2`, mimeType `text/html;profile=mcp-app`, declared on
 `execute_code` via `_meta.ui.resourceUri` together with an explicit
-`_meta.ui.visibility: ["model"]` — the default `["model","app"]` would tell hosts
-the view may call `execute_code`. A `resources/read` handler answers exactly that
+`_meta.ui.visibility: ["model"]`. Only `call_tool` declares app visibility; all
+other tools say model-only. A `resources/read` handler answers exactly that
 URI and fails on any other; `resources/list` is served and returns an empty list.
 The version segment bumps whenever the shell's bytes change, because hosts cache
 templates by URI.
 
-**U6.** The shell is display-only. It renders the payload in a nested iframe
+**U6.** The shell renders the payload in a nested iframe
 (`srcdoc`, `sandbox="allow-scripts"`, no `allow-same-origin`) and declares no CSP
 domains, so the host applies its restrictive default and the `about:srcdoc` frame
-inherits `default-src 'none'; connect-src 'none'`. Program UI gets scripts and
-local interactivity and nothing else: no network, no tool calls, no conversation
-messages, no host-mediated links. The shell participates in the Apps lifecycle —
+inherits `default-src 'none'; connect-src 'none'`. One argument stays display-only;
+a `V1` manifest installs only named `connecta.read`, with no direct network, raw
+tool calls, discovery, conversation, writes, or links. The shell participates in the Apps lifecycle —
 initialize, tool-result, size-changed, resource-teardown — and forwards no
 channel whatsoever from the inner frame to the host. That isolation makes
 program views fixed-height by construction: with no bridge there is no
@@ -580,6 +580,27 @@ host fetches the shell, and the whole design is inert. Reading the *client's*
 declaration in order to register tool metadata conditionally stays refused
 (`U10`), knowingly against a spec SHOULD.
 
+**U12.** The return value, not the view, is what the model reads. `U3` puts the
+view out of model context, so a program that renders one also returns the summary
+the model should reason over, built from the same variables the initial view renders — a
+view the return value does not mirror is a view nobody in the loop can check.
+This binds program authors and nothing else: connecta never reads the HTML, diffs
+it against the return, or enforces the correspondence. A heuristic there would be
+the same mistake as automatic host-side projection, refused in `ethos.md`
+([#282](https://github.com/zackbart/connecta/issues/282)).
+
+**U13.** The always-loaded MCP instructions locate `connecta.ui(html)` before an
+agent chooses a route: it is a guest function inside `execute_code`, never a
+connector address or catalog result, takes one HTML string, and carries `U12`'s
+mirrored-return duty. The detailed tool description proved too late to stop cold
+agents from searching downstream catalogs for UI; the location distinction
+therefore rides `initialize`, under a 1,000-character ceiling for the complete
+instructions string. This promotes existing contract, not capability: the
+seven-tool surface, guest API, catalog, Apps delivery, and runtime do not change
+([#286](https://github.com/zackbart/connecta/issues/286)).
+
+Bounded view reads follow normative [`V1`–`V8`](./program-ui-read-calls.md) ([#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)).
+
 ## Retry semantics
 
 **Y1.** Connecta retries nothing beneath a program. `call_tool` accepts an
@@ -794,7 +815,7 @@ Two surfaces were added since, both additive by construction and each with its
 byte-for-byte no-call promise pinned by test:
 [emitted output](#emitted-output) (`M1`–`M10`,
 [#270](https://github.com/zackbart/connecta/issues/270)) and
-[rendered output](#rendered-output) (`U1`–`U11`,
+[rendered output](#rendered-output) (`U1`–`U12`,
 [#277](https://github.com/zackbart/connecta/issues/277)).
 
 ## Verification
@@ -861,6 +882,8 @@ the upstream `Executor` shape assignable.
 | `U6` | `test/execute-ui.test.ts` (valid HTML5, `srcdoc` and sandbox attributes, no `allow-same-origin`, no path from the inner frame to the host) |
 | `U7`, `U8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `U9` | `test/execute-ui.test.ts` (a `ui` byte aggregate distinct from `emitted`, absent when nothing was accepted) |
+| `U12` | `test/server.test.ts` (the `connecta.ui` bullet carries the return-value clause); a duty on program authors, so the description is the only place it can be enforced |
+| `U13` | `test/code-first-surface.test.ts`, `test/server.test.ts` (served `initialize.instructions` locate UI inside `execute_code`, exclude it from catalog search, state the one-string call and mirrored return, and stay within the complete 1,000-character budget) |
 | `X3` | `test/quickjs-executor.test.ts` (cancels a running child) |
 | `X4` | `test/guest-api-contract.test.ts` (string logs only) |
 | `X6` | `test/quickjs-executor.test.ts` (never-settling await) |

package/documentation/mcp-ui-design.md

@@ -319,14 +319,14 @@ official spec at all — it survives there as background prose, not as a deferre
 item with a queue position. Adopting a payload format the official spec never
 took, on the path the official spec superseded, is two bets on one square.
 
-**View-initiated tool calls from program UI.** Gated, not refused. The
-host-mediated `tools/call` path exists in the Apps spec and would go through
-the same admission, annotation, and consent path as any other call, so the
-safety story is not the blocker. What is missing is the argument: a
-program-authored UI that drives tools needs its own use case and its own
-consent story, and neither exists yet. Display-only until one arrives, and
-gated twice over: `U5` declares `_meta.ui.visibility: ["model"]` so no host is
-ever told the view may call, and `U6`'s shell has no bridge to call with.
+**View-initiated tool calls from program UI.** This original gate was split by
+[#287](https://github.com/zackbart/connecta/issues/287) on 2026-08-02. Bounded
+refresh, pagination, and drill-down reads are accepted through named bindings
+and the existing `call_tool`; mutations remain gated. The evidence, threat
+trace, and boundary between live reads and Executor's artifact product live in
+[`program-ui-read-calls.md`](./program-ui-read-calls.md). The normative contract
+is `V1`–`V8` in [`code-mode.md`](./code-mode.md); it supersedes this record's
+display-only clauses where they disagree.
 
 **Downstream MCP Apps template passthrough** (downstream connectors declaring
 their own `ui://` templates, proxied through connecta's `resources/read`).

package/documentation/program-ui-read-calls.md

@@ -0,0 +1,213 @@
+# Bounded reads from program UI — evidence and decision
+
+Decision note for [#287](https://github.com/zackbart/connecta/issues/287),
+2026-08-02. The implementation contract is [#289](https://github.com/zackbart/connecta/issues/289)
+and the normative clauses are `V1`–`V8` in [code-mode.md](./code-mode.md).
+
+## Verdict
+
+Accept explicitly bound, host-mediated **read-only** calls for refresh,
+pagination, and drill-down. Keep mutations gated. Keep the one-string
+`connecta.ui(html)` call display-only.
+
+This is not an acceptance of interactive applications in general. It adds no
+persistence, artifact catalog, sharing, component runtime, generated-code
+library, deep link, direct network, conversation channel, or write path. One
+successful program still delivers one request-local view and one ordinary text
+result.
+
+## What display-only could not do
+
+The current shell and the read-bound browser fixture were walked through with
+the same three shapes. In the display-only arm, local JavaScript could sort,
+filter, chart, expand already-delivered fields, and rerender indefinitely; every
+attempt to obtain bytes not present in the original HTML stopped at the nested
+frame. The read-bound arm exercised the same-origin-free nested frame, two
+concurrent refreshes, fixed and view-supplied arguments, a refused fabricated
+binding, a refused extra argument, and a host error.
+
+| Workflow | Display-only attempt | Is a fresh program run adequate? | Decision |
+| --- | --- | --- | --- |
+| Refresh a current status or metrics view | A button can repaint only the original snapshot. Putting a timer around it changes no data. | No. It spends another model turn, reruns composition, and creates another view merely to repeat the same read. | Accept an exact named read with optional filter or cursor keys. |
+| Page a cursor-backed list | The initial program can include the known next cursor, but the view cannot exchange it for the next page. Fetching every page up front defeats projection and can cross call/result budgets. | No. The model is an expensive pagination controller and has to reconstruct UI state it did not need. | Accept a binding whose declared `viewArgs` includes the cursor field. |
+| Drill from a projected list into one record | Local expansion can show only fields prefetched for every row. Prefetching every detail multiplies calls and payload for records the human never opens. | Usually no. A new prompt can fetch the record, but loses the direct row selection and creates a second result instead of filling the existing view. | Accept a binding whose declared `viewArgs` includes the record identifier. |
+| Sort, filter, chart, compare, or expand delivered data | Local HTML/JavaScript completes the interaction. | Yes; usually no new run is needed at all. | No call capability earned. |
+| Change, delete, approve, send, or deploy | Display-only correctly cannot act. | Yes. The ordinary `call_destructive_tool` path keeps the proposed effect and host approval in the transcript. | Remain gated. A click is not approval, and this decision adds no mutation bridge. |
+
+The accepted utility is therefore *live reads*, not “interactivity.” Local
+interactivity already existed.
+
+## Executor comparison
+
+Executor's inspected revision demonstrates a useful separation:
+
+- its generated iframe disables direct `fetch`, XHR, WebSocket, EventSource,
+  workers, and related network primitives;
+- declarative `tools.*` operations become one proxy-shaped call through a
+  trusted shell and an app-only action tool;
+- integration roles resolve against server-owned saved bindings, and writes
+  can pause for shell-owned interaction handling.
+
+That is evidence that a narrow bridge can keep untrusted markup away from raw
+network and credentials. It is not evidence for Executor's React runtime,
+saved artifacts, editing, previews, persistence, or deep-link fallback; those
+features provide longevity and authoring ergonomics, not the refresh,
+pagination, or drill-down read itself.
+
+Connecta takes the smaller shape. The trusted shell maps names to the already
+existing `call_tool`; bindings live in the completed result, not a database;
+and the ordinary fail-closed read path remains the authority. No app-only tool
+or eighth meta-tool is needed.
+
+Inspected Executor sources:
+
+- [artifact and app-only action registration](https://github.com/UsefulSoftwareCo/executor/blob/837e404acbebdf32924059d6b76f715565329307/packages/hosts/mcp/src/tool-server.ts#L1906-L2157)
+- [single proxy-shaped action grammar](https://github.com/UsefulSoftwareCo/executor/blob/837e404acbebdf32924059d6b76f715565329307/packages/hosts/mcp-apps-shell/src/shell/proxy.ts#L38-L140)
+- [disabled direct network primitives](https://github.com/UsefulSoftwareCo/executor/blob/837e404acbebdf32924059d6b76f715565329307/packages/hosts/mcp-apps-shell/src/shell/inner-renderer.tsx#L84-L131)
+
+## Contract in one pass
+
+```js
+await connecta.ui(html, {
+  reads: {
+    refresh: {
+      address: "metrics.current",
+      fixedArgs: { service: "api" },
+      viewArgs: ["window", "cursor"],
+    },
+    detail: {
+      address: "incidents.get",
+      viewArgs: ["id"],
+    },
+  },
+});
+```
+
+Program markup calls `await connecta.read("detail", { id })`. It never receives
+the address table. The outer shell checks the frame source, resolves `detail`,
+rejects keys other than `id`, merges the arguments, and asks the host to call
+the existing `call_tool` with `resultMode: "value"`.
+
+The declaration-time catalog lookup proves the view was not born broken or
+write-capable. The use-time `call_tool` lookup proves it is still read-only now.
+
+## Normative contract
+
+**V1. Manifest.** The second argument is exactly
+`{ reads: { name: { address, fixedArgs?, viewArgs? } } }`: 1–32 names matching
+`[A-Za-z][A-Za-z0-9_-]{0,63}`, one non-empty address per name, optional fixed
+arguments, and at most 32 distinct view-supplied keys. Extra fields, unsafe
+control names (`__proto__`, `constructor`, `prototype`), a view key colliding
+with a fixed key, and non-serializable content throw before acceptance.
+
+**V2. Declaration admission.** Every address resolves through the request-local
+catalog and passes the fail-closed `isExplicitlyReadOnly` classification before
+the payload is accepted. The lookup dispatches nothing and spends no host-call
+budget. `call_tool` repeats resolution and classification at use time.
+
+**V3. Delivery.** Bindings ride beside `html` under `_meta["connecta/ui"]`,
+share the existing emitted-byte aggregate, appear on success only, and never
+enter `content` or `structuredContent`. The one-string payload stays exactly
+`{ html }`.
+
+**V4. Inner bridge.** A manifest alone installs `connecta.read(name, args?)`.
+The outer shell accepts only its nested frame's exact `WindowProxy`, rejects an
+unknown name, non-object arguments, undeclared keys, and more than eight
+concurrent reads, then merges supplied keys into a null-prototype copy of fixed
+arguments. The inner frame receives no address table or raw JSON-RPC.
+
+**V5. Seven-tool boundary.** The shell calls only existing `call_tool` with
+`resultMode: "value"`. That tool alone is app-visible; the other six are
+explicitly model-only. No new MCP tool exists and the view cannot reach the
+destructive boundary.
+
+**V6. Ordinary admission.** A view read is a new MCP request crossing inbound
+auth, request admission, current catalog and credentials, fail-closed safety,
+connector admission, timeout, retry, result-size, and payload-free activity
+exactly as ordinary `call_tool` does. No server-side grant or pending promise
+survives the originating request.
+
+**V7. Stale and replayed views.** A stale view retains no frozen authority:
+removed tools, changed annotations, revoked credentials, lost inbound auth, and
+new policy fail current admission. Replay repeats a read and may spend rate
+limits, but cannot write. Cross-caller use is admitted as the current caller on
+the host's originating connection; deployment remains the audience boundary.
+
+**V8. Context, fallback, and parity.** Reads update only the human-visible view;
+the return summarizes the initial snapshot and refreshed data must be labelled
+as such. A host without app server tools keeps the ordinary result and initial
+view while a read fails locally. The existing provider bridge carries the
+manifest identically on both executors without changing `ExecuteResult`.
+
+## Threat and consent trace
+
+1. **Untrusted program declaration.** The guest supplies HTML and a strictly
+   shaped read manifest. The host rejects extra fields, unsafe control names,
+   fixed/view collisions, overlarge lists, unknown addresses, and anything not
+   explicitly read-only. This lookup executes nothing.
+2. **Result delivery.** On successful program completion only, HTML and
+   bindings ride result `_meta` under the existing aggregate byte budget. A
+   failed program delivers neither. The model sees only `ui: true` and the
+   program's initial summary.
+3. **Nested-frame request.** Only the exact payload `WindowProxy` may send the
+   `connecta/read` dialect to the trusted shell. A fabricated name fails before
+   a host call. Fabricated or prototype-shaped argument keys fail unless they
+   are explicitly declared; fixed keys cannot be overridden. Direct JSON-RPC
+   from the nested frame is ignored.
+4. **Host mediation.** The shell checks that the host advertised server-tool
+   calls, caps concurrent work, and emits one `tools/call` for `call_tool`.
+   `execute_code`, discovery, authorization, result paging, and the destructive
+   tool are model-only. The Apps host accepts calls only on the originating MCP
+   server connection.
+5. **Connecta admission.** The app call is a new authenticated request with a
+   fresh request scope. It crosses request admission, current catalog and
+   credential resolution, fail-closed read classification, connector call
+   admission, timeout, retry policy, result-size handling, and payload-free
+   activity recording. There is no UI bypass below the shell.
+6. **Result delivery.** The shell unwraps the ordinary value result and settles
+   only the matching inner-frame promise. Protocol errors and tool errors
+   reject it. It sends no result to model or conversation context.
+
+### Named failures
+
+- **Fabricated address:** markup cannot submit an address; raw JSON-RPC is not
+  forwarded. A declaration-time invented address fails catalog resolution.
+- **Fabricated binding name:** rejected by own-property lookup in the shell.
+- **Fabricated argument:** an undeclared key or non-object argument is rejected;
+  a declared value still faces the downstream input schema and policy.
+- **Stale view:** the later request reauthenticates and re-resolves the catalog.
+  A removed tool, newly unsafe annotation, revoked credential, or changed
+  admission policy fails current checks. No frozen grant exists server-side.
+- **Replay:** it repeats a read and may consume rate limits, but cannot cross to
+  a write. The view should disable duplicate controls while its promise is
+  pending; the shell also bounds concurrency.
+- **Cross-caller use:** the later request is admitted as the caller behind the
+  host's current originating connection. Connecta does not use identity to
+  scope tools inside one deployment; separate audiences remain separate
+  deployments. A copied manifest is no credential and grants nothing outside
+  ordinary inbound auth.
+- **Destructive call:** the shell names only `call_tool`, and that handler
+  refuses missing, false, or contradictory read-only annotation. The
+  destructive meta-tool is not app-visible. No human gesture is interpreted as
+  write consent.
+
+## Invariants and parity
+
+- **Seven tools:** unchanged; metadata makes one existing tool app-callable and
+  makes the other six explicitly model-only.
+- **Stateless request scope:** binding state survives only in the client's
+  completed result and trusted shell. The server stores no grant or pending
+  promise.
+- **Import-graph purity:** the shell remains a build-time string using browser
+  and Web APIs only.
+- **Workers/Node parity:** the second argument crosses the existing provider
+  bridge, leaving `Executor` and `ExecuteResult` unchanged; the same contract
+  case runs on both executors and both Vitest projects.
+- **Payload-free activity:** later reads use ordinary `call_tool` events, whose
+  schema has no arguments or results.
+- **Fallback:** hosts without Apps keep the ordinary result; Apps hosts without
+  server-tool calls keep the initial view and fail a read locally.
+
+The remaining gate is intentionally crisp: a mutation proposal needs real
+workflow evidence plus a host-tested consent and replay story. Read utility is
+not permission to smuggle that decision into this bridge.

package/ethos.md

@@ -95,7 +95,9 @@ proposing one without a new argument is not.
 | Program-generated UI (`connecta.ui` + the Apps shell) | accepted | one MCP Apps view per successful run: the program supplies HTML only, delivered in result `_meta`, which hosts keep out of model context, and rendered by connecta's static shell inside the host's sandboxed frame ([design record](./documentation/mcp-ui-design.md), [#266](https://github.com/zackbart/connecta/issues/266)) |
 | Serving connecta's own UI template via `resources/read` | accepted | a narrow carve-out from the resources-aggregation refusal, not a reversal of it: one static build-time shell at one URI, an empty `resources/list`, nothing downstream ever listed or aggregated ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Downstream MCP Apps template passthrough | gated | proxying downstream `resources/read` earns its way in when a downstream connector actually ships an Apps template ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| View-initiated tool calls from program UI | gated | the host-mediated path exists and would take the ordinary audit and consent route, but a program-authored UI driving tools needs its own argument; display-only until one arrives ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| View-initiated read calls from program UI | accepted | named bindings materially improve refresh, cursor pagination, and drill-down without persistence or a new tool; the trusted shell delegates only to the existing fail-closed `call_tool`, and the one-string UI remains display-only ([evidence](./documentation/program-ui-read-calls.md), [#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)) |
+| View-initiated mutation calls from program UI | gated | live-read utility says nothing about write consent: a click is not approval, stale/replayed effects need a host-tested story, and the ordinary destructive path keeps the action in the transcript ([#287](https://github.com/zackbart/connecta/issues/287)) |
+| Result sampling on the catalog surface (`sample` / `dryRun`) | refused | sampling is execution and cannot ride a catalog read; most tools carry required arguments no sampler can invent, and undeclared `outputSchema` (measured 0/30 and 3/30 on real deployments) is a real gap that is not a sampleable one — a program that checks the shape before rendering already hands back the first record inside the run it was going to make anyway, at zero new surface ([#282](https://github.com/zackbart/connecta/issues/282)) |
 | Legacy embedded `UIResource` delivery | refused | superseded upstream and rendered by none of the clients connecta faces; per-request minted URIs also fight the caching the Apps spec assumes ([#266](https://github.com/zackbart/connecta/issues/266)) |
 
 ## Invariants

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",