@zackbart/connecta 0.10.6 → 0.12.0

package/documentation/code-mode.md

@@ -20,19 +20,11 @@ are stable and cited by the tests in [Verification](#verification).
 
 ## Deploy-time capability
 
-The `executor` passed to `createConnecta()` is the complete switch, and it selects
-the whole surface rather than one tool
-([#224](https://github.com/zackbart/connecta/issues/224)): with a live `Executor`,
-`tools/list` is exactly seven — `execute_code`, `search_tools`, `call_tool`,
-`call_destructive_tool`, `authorize_connector`, `get_result`, `skills`; without one
-it is the nine base meta-tools, whose `list_connectors`, `describe_tools`, and
-`batch_call` are what seven folds into `connecta.search`, `connecta.describe`, and
-`connecta.batch`.
-
-No feature flag, and no code tool advertised before it can be honored.
-`surface: "classic"` beside an executor is the one override (ten tools, the eval
-gate's incremental arm); `surface: "code-first"` without one throws at
-construction rather than advertise an absent program surface.
+The `executor` passed to `createConnecta()` is required. `tools/list` is exactly
+seven — `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
+`authorize_connector`, `get_result`, and `skills`. Construction fails when the
+executor is missing, and the removed `surface` option is rejected rather than
+ignored ([#273](https://github.com/zackbart/connecta/issues/273)).
 
 On Node, install the optional `quickjs-emscripten` peer and use the package's
 QuickJS subpath:
@@ -51,25 +43,20 @@ const connecta = createConnecta({
 CPU, wall-time, memory, stack, queue, result, log, and IPC bounds are configured
 on the executor. Server bundlers must keep the `@zackbart/connecta/quickjs`
 package files external so the child entry stays on disk. The
-[Node example](../examples/node/README.md) is enabled; remove its `executor` field
-for the nine-tool compatibility deployment.
+[Node example](../examples/node/README.md) carries the complete setup.
 
-On Cloudflare Workers, the Worker Loader binding is both the paid capability and
-the configuration switch:
+On Cloudflare Workers, the Worker Loader binding provides the required sandbox:
 
 ```ts
 createConnecta({
-  ...(env.LOADER
-    ? { executor: new DynamicWorkerExecutor({ loader: env.LOADER }) }
-    : {}),
+  executor: new DynamicWorkerExecutor({ loader: env.LOADER }),
   // connectors, auth, storage…
 });
 ```
 
-Leave the binding absent on the Workers Free plan. Its absence must also be
-represented as optional in the deployment's `Env` type. The
+Dynamic Workers require the Workers Paid plan. The
 [Worker example](../examples/worker/README.md#code-mode) carries the complete
-binding and package setup.
+required binding and package setup.
 
 ## What an executor must implement
 
@@ -305,8 +292,8 @@ const outcomes = await connecta.batch([
 order. A success is `{ address, ok: true, data }`. A failure is
 `{ address, ok: false, error, errorDetails }`, where `error` is the message and
 `errorDetails` is the typed object described in [Errors](#errors) — the same two
-field names `batch_call` uses. One failing call never rejects the batch, and more
-than ten calls throws.
+field names the host's internal batch path uses. One failing call never rejects
+the batch, and more than ten calls throws.
 
 **S8.** `connecta.batch` is the classification channel: because a thrown host
 error crosses the bridge as a bare message (`E1`), a batch of one is the supported
@@ -381,7 +368,9 @@ guest: admission rejection (`executor_overloaded`, retryable, with
 (`executor_closed`), deadline expiry, and sandbox crashes end the run and are
 reported to the model as an error result. One seam: a host call still in flight
 when the run is cancelled fails with `cancelled`, catchable on the way out but
-never worth acting on (`Y3`).
+never worth acting on (`Y3`). When shutdown tears down a program that had
+already started, accepted blocks and UI are reported as discarded under `M4`
+and `U3`; a failure before execution started carries no discard fields.
 
 **E6.** An error the program raises itself — a `TypeError`, a call to a
 `connecta` member that is not a provider function (including an inherited one
@@ -500,6 +489,97 @@ response, and `emit` resolving means "accepted," never "delivered."
 aggregate — count and serialized bytes, numbers only (`R8`), present only
 when something was emitted.
 
+## Rendered output
+
+`connecta.emit` gave programs pixels; it did not give them a *view*. This is the
+one the human looks at directly while the model keeps its cheap textual summary:
+one MCP Apps view per successful run, assembled where composition already
+happens. Programs supply HTML content and nothing else — the only `ui://` URI in
+the system is connecta's build-time shell, so nothing a client could dereference
+is derived from anything a program said. The argument, the refused shapes, and
+the security posture live in the [design record](./mcp-ui-design.md)
+([#266](https://github.com/zackbart/connecta/issues/266),
+[#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.
+
+**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,
+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`,
+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
+reverse-DNS SHOULD would be a worse answer than the shape the key format's MUST
+already permits. A program that never calls `connecta.ui` produces the
+byte-for-byte ordinary response (`R6`). A failed program delivers nothing and
+reports `uiDiscarded: true` *only* when a payload had been accepted — a field on
+the structured envelope, a trailing line on the plain-text paths — coexisting
+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
+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
+`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
+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
+(`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 —
+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
+content-height signal, the shell reports only its own box, and content taller
+than that scrolls inside the inner frame rather than growing the view.
+
+**U7.** Structural executor parity, per `M8`: `connecta.ui` is a provider
+function, `ExecuteResult` and the `Executor` interface are unchanged, and both
+executors get it through the bridge they already have.
+
+**U8.** Request-local and unstreamed, per `M9`. The payload exists only in the
+finished response, and `connecta.ui` resolving means "accepted," never
+"rendered."
+
+**U9.** `diagnostics: true` adds a distinct `ui` aggregate — the payload's byte
+size, a number and nothing else (`R8`), present only when a payload was accepted.
+UI bytes are not folded into `emitted`: that aggregate pairs a block count with
+the bytes those blocks cost, and bytes without a block would desync the pair.
+
+**U10.** `_meta.ui.resourceUri` is declared unconditionally. A host without the
+extension ignores unknown `_meta` and sees the ordinary envelope, which *is* the
+text fallback the Apps spec mandates; `connecta.ui` never fails because a client
+cannot render. A stateless aggregator cannot reliably know, and connecta is not a
+nanny.
+
+**U11.** connecta declares `io.modelcontextprotocol/ui` in its server capability
+declaration, and that is the one extension it advertises. The Apps extension must
+be explicitly negotiated and a conforming client acts on one only when both sides
+declare it, so without this declaration no host reads `_meta.ui.resourceUri`, no
+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.
+
 ## Retry semantics
 
 **Y1.** Connecta retries nothing beneath a program. `call_tool` accepts an
@@ -603,9 +683,9 @@ calls — which makes moving work into the sandbox an optimization, not a blindf
 server identity. Typed codes derive an optional `friction`: `tool_not_found`,
 `schema_retry`, `destructive_reroute`, or `auth_required`. The fifth class,
 `result_too_large`, cannot reach an `execute_code` event: it belongs to a
-`call_tool` result — or a `batch_call` child's — too large to return inline,
-and a program's own return is refused paging by design rather than truncated
-into friction. There is nowhere to put arguments, results, program source, or
+`call_tool` result too large to return inline, and a program's own
+return is refused paging by design rather than truncated into friction. There is
+nowhere to put arguments, results, program source, or
 raw error text; a caught failure is still recorded. `address` is
 canonical (`A1`) where a tool resolved, otherwise the name the program used —
 for a shortcut its sanitized alias, the honest record of what was attempted.
@@ -692,8 +772,8 @@ entry. Programs that ran before still run.
 
 - **`connecta.batch` failures gained `errorDetails`** (`S7`). They carried only a
   message, which left a program unable to tell a policy refusal from a transient
-  failure. Additive, and it reuses `batch_call`'s field names so one shape covers
-  both surfaces.
+  failure. Additive, and it reuses the host's internal batch field names, so a
+  program and the host describe a failed call the same way.
 - **A policy refusal can no longer look retryable** (`E7`). Pinned in code rather
   than read out of message text, so a connector named `svc-503` stops flipping a
   permanent refusal to `retryable: true`. This reaches the call tools too.
@@ -710,9 +790,12 @@ The middle three were places where the contract described behavior the code did
 not quite have. The code moved, because the described behavior is the one worth
 having.
 
-One surface was added since: [emitted output](#emitted-output) (`M1`–`M10`,
-[#270](https://github.com/zackbart/connecta/issues/270)) — additive by
-construction, with the byte-for-byte no-emit promise pinned by test.
+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`,
+[#277](https://github.com/zackbart/connecta/issues/277)).
 
 ## Verification
 
@@ -746,7 +829,7 @@ the upstream `Executor` shape assignable.
 | `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, batch and uncaught validation recovery), `test/meta-tools.test.ts` (direct, destructive, batch, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts` |
 | `E3` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`) |
 | `E4` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (destructive) |
-| `E5` | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts` |
+| `E5` | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.test.ts` (mid-run shutdown) |
 | `E6`, `X8` | `test/guest-api-contract.test.ts` (unknown and inherited members, wrapped-message precedence), `test/quickjs-executor.test.ts` |
 | `E7` | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts` |
 | `R1`, `R3` | `test/guest-api-contract.test.ts` (pass-through, truncation is success) |
@@ -766,22 +849,28 @@ the upstream `Executor` shape assignable.
 | `V1`–`V4` | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, and the identity clamp) |
 | `M1` | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (every rejected shape) |
 | `M2`, `M3` | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path) |
-| `M4` | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths) |
+| `M4` | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.test.ts` (mid-run shutdown) |
 | `M5`, `M7` | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched) |
 | `M6`, `M9` | verdicts; `M1`'s strict typing and `M2`'s collect-then-deliver are their enforcement |
 | `M8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `M10` | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted) |
+| `U1`, `U2` | `test/guest-api-contract.test.ts` (invalid and repeated calls throw catchably, first payload stands), `test/execute-ui.test.ts` (every rejected shape) |
+| `U3` | `test/guest-api-contract.test.ts` (`_meta` payload and `ui: true`, identical on both executors), `test/execute-ui.test.ts` (`structuredContent`, byte-for-byte no-call path, discard structured and plain, coexistence with `emittedDiscarded`), `test/quickjs-executor.test.ts` (mid-run shutdown) |
+| `U4` | `test/execute-ui.test.ts` (one shared byte aggregate crossed in either order; block count and host-call budget untouched) |
+| `U5`, `U10`, `U11` | `test/server.test.ts` (the shell URI, mimeType, and body; every other URI fails; empty listing; `execute_code`'s `_meta.ui`; exactly one declared extension) |
+| `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) |
 | `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) |
 | `X7` | `P3`'s tests; the Workers superset is deliberately unused |
 
-The surface itself is checked by `test/server.test.ts` (the exact seven, nine, and
-ten tool lists) and `test/code-first-surface.test.ts` (the fold's construction
-rules, refusals, copy, and measured size). The release audit compares the same
-two shapes:
+The surface itself is checked by `test/server.test.ts` (the exact seven-tool
+list) and `test/code-first-surface.test.ts` (the fold's construction rules, the
+required executor, the refusals a removed top-level tool now gets, copy, and
+measured size). There is one shape left to audit, so there is one audit:
 
 ```sh
 npm --prefix eval/current-version run audit
-npm --prefix eval/current-version run audit -- --executor disabled
 ```

package/documentation/connectors.md

@@ -33,7 +33,7 @@ Connecta deliberately sits between protocol generations
   [#206](https://github.com/zackbart/connecta/issues/206).
 - **Multi-round-trip results:** a downstream `input_required` result becomes a
   non-retryable `input_required_unsupported` failure. `call_tool`, the
-  `execute_code` host bridge, and classic's `batch_call` all preserve the
+  `execute_code` host bridge and internal batch path both preserve the
   structured code. Relaying the
   opaque `requestState` is architecturally possible but gated until real hosts
   and downstreams adopt it.

package/documentation/mcp-2026-07-28.md

@@ -17,7 +17,7 @@ deliberately gated. The migration is tracked in
 | 8 | `ttlMs` and `cacheScope` on cacheable lists | adopt | `tools/list` returns `ttlMs: 3_600_000` and `cacheScope: "private"`. |
 | 9 | Honor downstream list cache hints | gated | Keep the fixed five-minute TTL plus fingerprint until refresh-churn evidence warrants complexity ([#206](https://github.com/zackbart/connecta/issues/206)). |
 | 10 | Native Tasks extension | refuse | Tasks address duration, while `get_result` addresses response size. Polling plus paging would add round trips without replacing the stash. |
-| 11 | Extensions capability framework | decline | No client consumes a Connecta extension declaration. |
+| 11 | Extensions capability framework | decline | Decline as a general surface. The one extension Connecta declares is `io.modelcontextprotocol/ui`, which the MCP Apps extension requires before a host will use the program-UI shell template at all ([#266](https://github.com/zackbart/connecta/issues/266)). |
 | 12 | `Mcp-Method` and `Mcp-Name` POST headers | adopt | SDK v2 handles the headers; CORS allows `mcp-method, mcp-name`. |
 | 13 | RFC 9207 `iss` validation and `application_type` | adopt via SDK | The callback preserves all query parameters for SDK validation. |
 | 14 | Credentials keyed to issuer; re-register when AS changes | adopt | Version-2 credential envelopes store issuer; mismatch advances the generation epoch and invalidates registration and tokens. |