@zackbart/connecta 0.22.2 → 0.23.0

package/documentation/meta-tools.md

@@ -8,9 +8,8 @@ annotations, and `get_result` pages bounded results.
 
 Every deployment requires an executor and `tools/list` is exactly seven:
 `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
-`authorize_connector`, `get_result`, and `skills`. Discovery breadth and
-batching live in `connecta.search`, `connecta.describe`, and `connecta.batch`
-inside a program ([#273](https://github.com/zackbart/connecta/issues/273)).
+`authorize_connector`, `get_result`, and `skills`. Discovery uses `connecta.search` and `connecta.describe`; programs compose
+calls with JavaScript promises ([#273](https://github.com/zackbart/connecta/issues/273)).
 
 Code-first is what a model sees. Read-only work has two routes: `call_tool` for
 one known address, and `execute_code` when discovery or any wider work is
@@ -21,8 +20,11 @@ The [guest API contract](./code-mode.md) is what a program is promised.
 
 The route is chosen before discovery. An unknown address, a result that will be
 reduced, a call whose arguments depend on an earlier result, or work with
-multiple operations starts with one `execute_code` call and keeps discovery,
-calls, and reduction inside it. Distinct operations get distinct short
+multiple operations starts with `execute_code` and keeps discovery, calls, and reduction inside it
+when the schemas and result shapes suffice. An unfamiliar provider result may
+return a small sample for inspection before continuing in another call. This
+exception avoids repeated guesses at text formats or collection roots; it does
+not restore a mandatory discovery-only round trip. Distinct operations get distinct short
 `connecta.search` queries in that program. A known address needs only
 `call_tool`.
 
@@ -41,11 +43,13 @@ The measurements never contain program source, arguments, values, addresses,
 credentials, logs, or raw error text.
 
 Nothing became unreachable. `connecta.describe` takes the same addresses and
-formats as the internal catalog service, `connecta.batch` runs 1–10 parallel
-read-only calls and returns typed outcomes, and an unfiltered
+formats as the internal catalog service, ordinary promises compose read-only
+calls, and an unfiltered
 `connecta.search({})` browses every catalog a program can reach. Live connector
 probing is an operator concern: the operator pages and `/health` own it.
 
+Program search includes a bounded `connectorTitle` on each tool when configured, so choosing an account or environment does not require a provider read. It is context, not a ranking input or proof of live access.
+
 The three discovery routes use deliberately different envelopes. These are
 their smallest successful one-tool shapes:
 
@@ -62,7 +66,7 @@ their smallest successful one-tool shapes:
 
 The deployment-derived `execute_code` description includes a live connector
 inventory before any catalog search. It preserves registry order and uses each
-canonical id, adding `shortcut <name>` only when the program namespace differs.
+canonical id and a distinct configured title without generating a second name for programs. Titles normalize whitespace and are capped at 48 UTF-8 bytes, so account and environment hints cannot consume the entire inventory.
 The complete inventory line is capped at 256 UTF-8 bytes. Entries stay whole,
 and a truncated line ends with the exact `+N more` count. This reads only the
 configured registry: it loads no catalog, probes no credential, grants no
@@ -177,6 +181,22 @@ This split avoids two normative copies while preserving a valid first program
 for clients that never fetch the skill. Deployments without connector guides
 receive none of the short conditional guide pointers in their definitions.
 
+## Task guidance
+
+`skills({ name: "investigate" })` provides on-demand guidance for purchase
+verification, experiment checks, and customer or deployment investigations.
+The execute description points to it when planning is unclear; routine reads need no additional guide fetch. It explains how to
+resolve app/account/environment, follow evidence across services, establish
+capability limits, and stop with a clear answer or a specific gap. It is shared
+guidance, not a saved workflow or a source of deployment-specific ids. Existing
+connector titles, purposes, and guides still own those distinctions.
+
+The usage skill keeps the executable mechanics. Its dependent-call example
+searches each operation separately, uses the page's `tools` array and canonical
+addresses, and reports unresolved evidence instead of inventing an address or
+querying another account. Its source runs against local fixtures in the QuickJS
+suite, including missing and approval-required evidence.
+
 ## Result representation
 
 For object results, `structuredContent` is the canonical full-fidelity value.
@@ -338,8 +358,7 @@ That route echoes the caller's own arguments back only while they fit a
 512-byte budget, and then whole — never clipped. An error envelope is not
 size-guarded the way a result is, so an unbounded echo would let a large
 argument object produce a refusal many times the deployment's result cap, on
-both `call_tool` and calls a program routes through `connecta.call` or
-`connecta.batch`. Over budget, `args` is absent and the `purpose` says to
+both `call_tool` and program calls through `connecta.call`. Over budget, `args` is absent and the `purpose` says to
 re-send what was just sent: the agent already holds its own arguments, and half
 of them would describe a call nobody made.
 
@@ -352,9 +371,7 @@ recovery query, each of which lands in both the text content and
 the address is the thing being corrected, a clipped one still identifies the
 mistake, and a short one — every real one — comes back exact and untagged.
 
-Shortcut ambiguity inside `execute_code` returns every colliding canonical
-address and points at `connecta.call`; the program or model must still choose
-which one matches the user's intent. `call_destructive_tool` accepts an optional
+`call_destructive_tool` accepts an optional
 `reason` of at most 500 characters for the host's human approval view. It is
 outer-call context only: Connecta neither treats it as authority nor passes it
 to the downstream connector, and an empty or whitespace-only one is read as no
@@ -395,7 +412,7 @@ about the mistake as all 40,000 would.
 A remote MCP tool's advertised `inputSchema` is checked in the shared
 invocation path before admission and provider dispatch. A mismatch is the
 non-retryable `invalid_args`, consistently across `call_tool`,
-`call_destructive_tool`, batch outcomes, and generated-code failures. The error
+`call_destructive_tool`, generated-code failures, and rejected promises. The error
 names the connector and operation and carries bounded `validation.issues`:
 JSON Pointer `path`, schema-keyword `code`, and expected shape. Submitted
 values are never copied into those findings.

package/documentation/operations.md

@@ -99,7 +99,7 @@ optional.
 | `discovery.persistCatalog?` | true | persist serializable catalogs as a manifest plus revision-addressed chunks |
 | `discovery.staleCatalogSeconds?` | 3600 | how long a complete expired catalog stays usable for agent SWR and as a refresh-failure fallback |
 | `discovery.probeTimeoutMs?` | 30_000 | per-connector deadline for catalog fan-out; a timed-out connector degrades alone. Not a tool-call deadline |
-| `calls.defaultTimeoutMs?` | **unset (opt-in)** | deadline for calls that pass no `timeoutMs`. Bounds one attempt, so retries can still extend total duration |
+| `calls.defaultTimeoutMs?` | **unset (opt-in)** | deadline for calls that pass no `timeoutMs`. Each admitted call makes one attempt |
 | `calls.maxResultBytes?` | 50_000 | inline result cap before truncation and `get_result` paging; a connector may override it. Invalid values warn and fall back |
 | `execute.maxEmittedBytes?` | 4_000_000 | aggregate `connecta.emit` bytes per run — a transport bound, not a context bound |
 | `execute.maxEmittedBlocks?` | 32 | content blocks `connecta.emit` accepts per run |
@@ -240,19 +240,18 @@ in.
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
 | `cloudflare-access-auth.test.ts` | trusted `ctx.access` human and service identities, absent/error fail-closed behavior, service-token MCP admission without operator mutation, human same-origin mutation, and the Clerk-to-ambient shell switch |
 | `cloudflare-provider.test.ts` | `cloudflare()` API and MCP construction, the code-mode safety manifest, API tool surface, current R2 and KV jurisdictions, useful output declarations, request building, projections including additive provider fields, typed failures, and credential test |
-| `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and `connecta.ui` findable before connector search |
+| `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and no rendering instructions |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
 | `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and unknown own-properties rejected by their complete path before construction does work |
 | `credentials.test.ts` | the pure stored-shape classifier (containment, not equality) and the AES-GCM vault: round-trip, ciphertext bound to its connector id, named field sets, masked metadata, wrong-key rejection, deletion, coexistence with OAuth keys |
 | `d1-activity-example.test.ts` | the Worker example's deployment-owned D1 activity store: actor namespace round-trip, payload-free friction reconstructed from the persisted code, and agreement with the package's friction table |
 | `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and generation races, runtime-local rotating-token refresh coordination across request scopes, refresh failure/retry, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
 | `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, and framing errors |
-| `execute.test.ts` | the code-mode host bridge: identifier sanitization, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
+| `execute.test.ts` | the code-mode host bridge: identifier sanitization, account titles in program discovery, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
 | `execute-emit.test.ts` | `connecta.emit` (M1–M10) — block validation, budgets, the provider, delivery after the result envelope on success only, and the defaults |
-| `execute-ui.test.ts` | display-only `connecta.ui` (U1–U13) — one-string validation, multiplicity and budget, the provider, `_meta` delivery, shell isolation, and the absence of a payload-to-host call path |
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
 | `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
-| `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, batch, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
+| `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, parallel-call, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
 | `identity-scope.test.ts` | identity-derived connector visibility, personal credential isolation, shared-auth operator control, and personal OAuth callback ownership |
 | `linear-provider.test.ts` | the Linear proxy's construction, guide, plan-aware catalog superset, and current workspace, template, and issue-sharing classifications |
 | `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
@@ -271,8 +270,8 @@ in.
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
 | `result-shapes.test.ts` | passive output-shape learning: value-free bounded inference, merging, 256-entry LRU eviction, 24-hour expiry, runtime isolation, read-only admission, declared-schema precedence, definition-change invalidation, discovery provenance, and failure isolation |
 | `revenuecat-provider.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the refund-preference read and argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot` |
-| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory and exact model-only Apps metadata → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, and deferred catalog reads through both discovery surfaces |
-| `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: every built-in answered ahead of connector routes inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
+| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory, account titles, on-demand investigation guidance, and no Apps metadata or resource capability → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, removed connector HTTP hooks rejected at construction, and deferred catalog reads through both discovery surfaces |
+| `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: built-in routes and unknown-path 404s inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
 | `startup-warnings.test.ts` | every construction-time `logger.warn` and, as importantly, the conditions that must *not* trigger one: open mode with a credential or OAuth connector, `publicUrl` unset beside OAuth, dropped branding and `uiAuth` URLs, a missing `verifyState`, a credential test-hook mismatch, and an unusable `calls.maxResultBytes` |
 | `stripe-provider.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, current eleven-tool classifications, admission, exact account selectors, and no-guess rule |
 | `operator-view.test.ts` | the app's pure state rules from `view.ts`: filtering, page routing, capability states, activity summaries, drift display, and identity reset |
@@ -300,7 +299,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
 | `quickjs-child-stderr.test.ts` | the QuickJS child-process boundary: an explicitly empty environment despite parent secrets and `NODE_OPTIONS`, plus abnormal exits retaining only an 8 KiB stderr tail in the parent-side diagnostic | mocks Node child-process streams |
-| `quickjs-executor.test.ts` | the child-process sandbox — code normalization, lazy namespace proxies, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection | runs the Node QuickJS child-process executor |
+| `quickjs-executor.test.ts` | executable usage example with dependent, missing, and approval-required evidence; the child-process sandbox — code normalization, provider bridges and canonical connector calls, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection | runs the Node QuickJS child-process executor |
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |
 | `template-file-activity.test.ts` | the Node template's own activity store — persistence across restart, torn-line repair, newest-first paging, and compaction past the slack window | runs it against real files |
@@ -312,7 +311,6 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | Suite | Covers |
 | --- | --- |
 | `browser/operator-ui.spec.ts` | the operator wiring in a real browser: Clerk loader order across its version redirect and a real load failure, the shell staying open until authentication, credential and access-token and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
-| `browser/program-ui.spec.ts` | the display-only Apps shell in a real browser: local payload JavaScript runs, `connecta` stays absent, and forged payload messages never become host tool calls |
 
 **The `_transportFactory` seam.** `RemoteMcpOptions._transportFactory` is
 internal, not public API: when set, `remoteMcp()` uses that `Transport` instead

package/documentation/provider-conventions.md

@@ -237,8 +237,8 @@ not send the agent to `authorize_connector`, you do not repair the argument
 object. You re-address — look the id up again, or accept the absence and carry
 on — and a program looping over ids inside `execute_code` can continue past
 `not_found` where `connector_call_failed` would have to abort the run, reading
-the code off a `connecta.batch` entry's `errorDetails` rather than off a caught
-error, which the guest bridge has already stripped to prose. That
+the code from a caught error or a rejected promise. The guest bridge preserves
+the typed classification. That
 control-flow difference is the H11 test being met; it is not a label for the
 cause.
 

package/documentation/upgrading.md

@@ -17,6 +17,51 @@ the release notes broke, and prove it with `connecta doctor`.
 Work on a branch. Every step below is reversible until you delete the old
 lockfile, and you want the diff reviewable by whoever owns this deployment.
 
+## 0.23.0 program API pruning
+
+This update removes MCP Apps rendering, connector shortcut globals,
+`connecta.batch`, automatic direct-call retries, and connector-owned HTTP routes. Refresh the client's MCP
+instructions and tool definitions after upgrading. The seven top-level tools,
+operator pages, credentials, result paging, and media emission remain.
+
+| Before | After |
+| --- | --- |
+| Connector `handleRequest(request, ctx)` | Move custom HTTP routes into the existing deployment fetch handler |
+| `await tracker.list_issues(args)` | `await connecta.call("tracker.list_issues", args)` using the exact address from discovery |
+| `await connecta.batch(calls)` | `Promise.all` over `connecta.call`, or `Promise.allSettled` to keep failures alongside successes |
+| `await connecta.ui(html)` | Return the data the client needs to render its own view |
+| `call_tool` or `call_destructive_tool` with `maxRetries` | Omit the removed argument; each call makes one attempt and returns typed failures with provider retry hints |
+
+A connector that still declares `handleRequest` refuses construction. Handle
+custom routes in the existing Node or Worker deployment before delegating other
+requests to `connecta.fetch`. The deployment owns authentication and security
+headers for its custom responses. Connecta returns 404 for unknown paths.
+Cloudflare Global API Key authentication and multi-field credentials remain
+supported; they need no migration.
+
+The direct-call schemas reject unknown arguments, including `maxRetries`, before
+invocation. Review stored programs and deployment-owned usage guides for the
+removed guest functions. Canonical addresses preserve punctuation; do not copy
+the old sanitized shortcut into the address string.
+
+```js
+async () => {
+  const outcomes = await Promise.allSettled([
+    connecta.call("tracker.list_issues", { state: "started" }),
+    connecta.call("tracker.list_projects", {}),
+  ]);
+  return outcomes.map((outcome) => outcome.status === "fulfilled"
+    ? { ok: true, data: outcome.value }
+    : { ok: false, code: outcome.reason.code, message: outcome.reason.message });
+}
+```
+
+Reduce large successful values before returning. Promise rejection reasons are
+Error objects; explicitly select their fields for JSON output. Every call still
+passes through the existing read-only checks, admission limits, deadlines, and
+20-call program budget. Rate-limited calls return `retryAfterMs` without waiting;
+the client can reissue after that delay. No storage migration is required.
+
 ## Read what you have first
 
 Three questions, in order. Answer all three before editing anything — the
@@ -57,7 +102,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.22.2 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.23.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +151,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.22.2
+npm pkg set dependencies.@zackbart/connecta=0.23.0
 npm install
 ```
 
@@ -130,7 +175,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.22.2 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.23.0 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +231,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.22.2 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.23.0 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,7 +252,14 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
-### 0.21.2 → 0.22.2
+### 0.22.3 → 0.23.0
+
+Migrate stored programs and custom connector routes using the
+[0.23.0 migration](#0230-program-api-pruning). Refresh client instructions
+and tool definitions so account titles and the revised discovery guidance take
+effect. No storage migration is required.
+
+### 0.21.2 → 0.22.3
 
 Connector and user policy remain config-as-code. If `identity.connectorAccess`
 is configured, every interactive human may now manage the authentication of
@@ -572,10 +624,8 @@ all, so this is not a hook to stub out with `() => true`.
 previously fell through to connector `handleRequest` and then to a 404, so a
 connector that served any of the three is now shadowed without warning. `GET /`
 returns the operator shell where 0.6.1 returned 404, and a non-GET on those
-routes or on `/ui` returns 405 instead of falling through. Move such a handler
-to a path the core does not own: `handleRequest` still runs for everything the
-built-in routes miss, so it can add a route and never shadow one
-([architecture](./architecture.md)).
+routes or on `/ui` returns 405 instead of falling through. For the current release, move custom handlers into the deployment: connector
+`handleRequest` is now removed. See the [current migration](#0230-program-api-pruning).
 
 ### Removed options that throw
 

package/ethos.md

@@ -1,7 +1,6 @@
 # connecta — ethos
 
-What connecta is, what it refuses to be, and the invariants every change must
-preserve. A contradiction needs a design decision, not a drive-by edit.
+Connecta’s scope, refusals, and invariants. Contradictions require a design decision.
 
 ## What this is
 
@@ -40,9 +39,8 @@ preserve. A contradiction needs a design decision, not a drive-by edit.
 
 ## Decisions
 
-Shapes considered and turned down. Proposing one again without a new argument
-is not allowed. Accepted designs live in their subsystem guide and the
-CHANGELOG, not here.
+Revisiting a verdict requires a new argument. Accepted designs live in
+subsystem guides and the CHANGELOG.
 
 | Decision | Verdict | Why |
 | --- | --- | --- |
@@ -53,7 +51,7 @@ CHANGELOG, not here.
 | Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
 | Protocol sessions & server push | refused | stateless per request |
-| Resources & prompts aggregation | refused | tools only; the Apps shell is the one `resources/read` carve-out ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Resources & prompts aggregation | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Elicitation passthrough | refused | no route through a stateless aggregator |
 | Repository formatter | refused | style is authored, not enforced |
 | Host-side projection of program results | refused | a program projects; a heuristic drops fields invisibly ([#223](https://github.com/zackbart/connecta/issues/223)) |
@@ -67,6 +65,11 @@ CHANGELOG, not here.
 | Legacy embedded `UIResource` delivery | refused | superseded upstream, rendered by no client we face ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Effect as the core effect system | refused | −4% of the core for +75 KB gzip and a second async paradigm; re-measure at v4 stable ([#470](https://github.com/zackbart/connecta/issues/470)) |
 | Shared bounded queue under both admission controllers | refused | built and measured −17 lines for a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
+| MCP Apps rendering and `connecta.ui` | removed | clients render returned data |
+| Connector shortcut globals | removed | canonical addresses need no sanitization |
+| `connecta.batch` | removed | JavaScript promises suffice |
+| Automatic direct-call retries | removed | callers own retry timing |
+| Connector HTTP routes | removed | deployments own custom routes |
 | Caller-selected toolkits | removed | only config may derive an identity's connector view ([#178](https://github.com/zackbart/connecta/issues/178)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
@@ -75,14 +78,14 @@ CHANGELOG, not here.
 | Semantic tool search | gated | keyword search has not been shown to fail ([#27](https://github.com/zackbart/connecta/issues/27)) |
 | MRTR / `input_required` passthrough | gated | relayable statelessly; no host or downstream emits it yet ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | needs refresh-churn evidence ([#206](https://github.com/zackbart/connecta/issues/206)) |
-| Downstream MCP Apps template passthrough | gated | needs a downstream that ships one ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Downstream MCP Apps template passthrough | refused | clients own presentation; Connecta serves tools and data |
 | Worker Access inbound auth | provisional | Managed OAuth and Clerk migration need production evidence ([#506](https://github.com/zackbart/connecta/issues/506)) |
-| Program UI tool calls | removed | the read bridge added a second contract without improving agent data retrieval; views are display-only again ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
+| Program UI tool calls | removed | duplicated calls without improving retrieval ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
 
 ## Invariants
 
-One line each; the enforcing tests live beside the subsystem documentation.
-Breaking one is a design change wearing a disguise.
+Tests beside subsystem documentation enforce these invariants. Breaking one
+requires a design decision.
 
 - **Fail-closed read-only.** A missing, false, or contradictory annotation never gets the benefit of the doubt.
 - **Generated code cannot mint capabilities.** Admission, credentials, and classification are enforced below the sandbox.
@@ -97,6 +100,4 @@ Breaking one is a design change wearing a disguise.
 - **Human routes manage auth, never capability.** Signed-in humans manage auth for visible connectors; operators also manage tokens and global activity.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
-Connecta began as a radical simplification of
-[executor](https://github.com/UsefulSoftwareCo/executor); this file is the
-record of that simplification holding.
+Connecta simplifies [executor](https://github.com/UsefulSoftwareCo/executor).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "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.",

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.22.2",
+    "@zackbart/connecta": "0.23.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/dist/apps-shell.d.ts

@@ -1,37 +0,0 @@
-/**
- * The one MCP Apps template connecta serves (`U5`, `U6`).
- *
- * 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.
- *
- * The address carries a version segment because hosts are permitted to
- * 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/v3";
-/** The mimeType the Apps spec requires of an HTML template. */
-export declare const PROGRAM_UI_MIME_TYPE = "text/html;profile=mcp-app";
-/**
- * The result `_meta` key carrying the payload (`U3`). A plain single-label
- * prefix rather than the reverse-DNS form MCP's SHOULD prefers: connecta has
- * no domain to reverse, and fabricating one to satisfy a SHOULD is a worse
- * answer than the shape the key format's MUST already permits.
- */
-export declare const PROGRAM_UI_META_KEY = "connecta/ui";
-/** The one extension identifier connecta advertises (`U11`). */
-export declare const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
-/**
- * The shell document. Dependency-free and deliberately small: it speaks the
- * 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.
- */
-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";

package/dist/apps-shell.js

@@ -1,174 +0,0 @@
-/**
- * The one MCP Apps template connecta serves (`U5`, `U6`).
- *
- * 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.
- *
- * The address carries a version segment because hosts are permitted to
- * 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/v3";
-/** The mimeType the Apps spec requires of an HTML template. */
-export const PROGRAM_UI_MIME_TYPE = "text/html;profile=mcp-app";
-/**
- * The result `_meta` key carrying the payload (`U3`). A plain single-label
- * prefix rather than the reverse-DNS form MCP's SHOULD prefers: connecta has
- * no domain to reverse, and fabricating one to satisfy a SHOULD is a worse
- * answer than the shape the key format's MUST already permits.
- */
-export const PROGRAM_UI_META_KEY = "connecta/ui";
-/** The one extension identifier connecta advertises (`U11`). */
-export const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
-/**
- * The shell document. Dependency-free and deliberately small: it speaks the
- * 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.
- */
-export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>connecta program view</title>
-    <style>
-      html,
-      body {
-        margin: 0;
-        padding: 0;
-        background: transparent;
-      }
-      #program-view {
-        display: block;
-        width: 100%;
-        min-height: 480px;
-        border: 0;
-      }
-    </style>
-  </head>
-  <body>
-    <iframe
-      id="program-view"
-      title="Program-rendered view"
-      sandbox="allow-scripts"
-      srcdoc=""
-    ></iframe>
-    <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.
-        var host = window.parent;
-        var view = document.getElementById("program-view");
-        var initializeId = "connecta-ui-initialize";
-        var lastWidth = 0;
-        var lastHeight = 0;
-
-        function send(message) {
-          if (!host || host === window) return;
-          host.postMessage(message, "*");
-        }
-
-        function notify(method, params) {
-          send({ jsonrpc: "2.0", method: method, params: params });
-        }
-
-        // 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
-        // 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
-        // only lever; a content-height signal would cost the isolation.
-        function reportSize() {
-          var width = Math.ceil(document.documentElement.clientWidth);
-          var height = Math.ceil(document.documentElement.scrollHeight);
-          if (width === lastWidth && height === lastHeight) return;
-          lastWidth = width;
-          lastHeight = height;
-          notify("ui/notifications/size-changed", {
-            width: width,
-            height: height
-          });
-        }
-
-        function payloadHtml(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;
-        }
-
-        function render(params) {
-          var html =
-            payloadHtml(params) ||
-            payloadHtml(params && params.result) ||
-            payloadHtml(params && params.toolResult);
-          if (html === null) return;
-          view.srcdoc = html;
-          reportSize();
-        }
-
-        window.addEventListener("message", function (event) {
-          if (event.source !== host) return;
-          var message = event.data;
-          if (!message || message.jsonrpc !== "2.0") return;
-          if (message.method === "ui/notifications/tool-result") {
-            render(message.params);
-            return;
-          }
-          if (message.method === "ui/resource-teardown") {
-            // A host->view request, not a notification: the host waits for
-            // this reply before it tears the view down. There is nothing to
-            // release, so answer immediately rather than make it time out.
-            if (message.id !== undefined && message.id !== null) {
-              send({ jsonrpc: "2.0", id: message.id, result: {} });
-            }
-            return;
-          }
-          // Only a completed handshake earns "initialized". A JSON-RPC error
-          // response carries the same id, and announcing initialization on one
-          // would assert a handshake that never happened.
-          if (message.id === initializeId && message.result !== undefined) {
-            notify("ui/notifications/initialized", {});
-          }
-        });
-
-        window.addEventListener("resize", reportSize);
-        view.addEventListener("load", reportSize);
-
-        // Every field here is required by the Apps initialize schema, and a
-        // conforming host rejects the request outright when one is missing —
-        // which would strand the shell before any tool result arrives.
-        send({
-          jsonrpc: "2.0",
-          id: initializeId,
-          method: "ui/initialize",
-          params: {
-            appInfo: { name: "connecta program view", version: "1" },
-            appCapabilities: {},
-            protocolVersion: "2026-01-26"
-          }
-        });
-        reportSize();
-      })();
-    </script>
-  </body>
-</html>
-`;