@zackbart/connecta 0.12.1 → 0.13.0

package/documentation/meta-tools.md

@@ -19,6 +19,21 @@ The consolidation removed overlapping routing choices while preserving the
 cheaper direct path for one cold call. The [guest API contract](./code-mode.md)
 is what a program is promised.
 
+The route is chosen before discovery. 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 `connecta.search` queries in
+that program. Only one unknown-address read takes the cheaper top-level
+`search_tools` → `call_tool` path; a known address needs only `call_tool`.
+
+That routing is about read-only work, because that is the only work a program
+can do. Anything unannotated, write-capable, or destructive is inadmissible
+inside the sandbox, so multi-step destructive work discovers at the top level
+and runs each step through `call_destructive_tool` — where the host can put the
+question to a human. Telling an agent never to search at the top level for
+multiple calls would close the only route that work has
+([#295](https://github.com/zackbart/connecta/issues/295)).
+
 `execute_code` accepts optional `diagnostics: true` when a caller is measuring
 a workflow. It adds only compact request-local timing and serialized-size
 aggregates; normal calls carry no diagnostics block or response-context cost.
@@ -35,17 +50,23 @@ probing is an operator concern: the operator pages and `/health` own it.
 
 Start an unknown-address lookup with two to four distinctive action/object
 terms, not the full request, and omit `limit` so the default eight-result page
-stays small. Set `safety: "readOnly"` when the result is headed to `call_tool`
-or generated code; `safety: "approvalRequired"` finds the complementary set
-that must cross `call_destructive_tool`. Omitting `safety`, or setting it to
-`"all"`, preserves the complete configured catalog. This is only a discovery
-filter: it neither grants authority nor changes invocation admission.
+stays small. When the integration is obvious, set `connector` to its id: a
+scoped search loads that catalog alone, while an unscoped search must fan out
+across every configured connector. Leave the search unscoped when the right
+integration is genuinely ambiguous. Set `safety: "readOnly"` when the result is
+headed to `call_tool` or generated code; `safety: "approvalRequired"` finds the
+complementary set that must cross `call_destructive_tool`. Omitting `safety`,
+or setting it to `"all"`, preserves the complete configured catalog. This is
+only a discovery filter: it neither grants authority nor changes invocation admission.
 `includeSchemas: "compact"` adds each match's input and any declared output
 shape. Bounded plain-object schemas also expose `inputKeys`,
 `requiredInputKeys`, and `outputKeys`; a truncated shape omits its corresponding
 list rather than repeating a large partial inventory. Matches carry declared
-behavior annotations. When
-that shape is sufficient, call the returned address directly. Reserve schema
+behavior annotations. Lexical rank is only one signal: select a candidate whose
+required inputs are available, whose schema is complete enough for the call,
+and whose safety and declared outputs fit the work. A reducer uses `outputKeys`
+before inspecting the value; it does not assume a collection is named `items`
+or `results`. When that shape is sufficient, call the returned address directly. Reserve schema
 expansion through `connecta.describe` for a search without schemas, an
 ambiguous compact shape, or exact
 constraints that require `format: "json"`.
@@ -60,6 +81,51 @@ types; other shapes become `unknown /* truncated */`. The match also carries
 `includeSchemas: "json"` or use the existing describe path when exact
 constraints matter.
 
+## Connector guide selection
+
+A connector may attach a deployment-owned guide as markdown, preserving the
+original `usageGuide: string` configuration, or as
+`{ content, summary?, required? }`. The structured form does not register a
+connector or create a shared runtime template. `content` remains the markdown
+returned verbatim by `skills`; `summary` is normalized and capped at 120
+characters for discovery. When it is absent, Connecta derives the same bounded
+fallback used by the skills listing: the first meaningful body line, with a
+heading used only when the guide has no body. `required: true` is reserved for generic
+API wrappers and cross-operation conventions a complete downstream schema
+cannot express.
+
+Search and describe results keep the existing `guide: "connector:<id>"`
+pointer and add `guideSummary`. A matching tool also carries
+`guideRequired: true` and `guideRequiredReasons` when Connecta can prove review
+is necessary:
+`connector_required` for the explicit configuration above,
+`approval_required` for an unannotated or write-capable tool, and
+`schema_truncated` when a requested compact input or output shape was capped.
+The boolean is an instruction, not a server-side gate — nothing refuses the
+call, so the agent is told to fetch the guide before making it, for any reason
+listed. `connector_required` and `approval_required` survive exact schema
+expansion; `schema_truncated` is cleared by the describe that returns the exact
+shape, and describe reports whatever reasons remain in the same two fields.
+Otherwise it reads the
+bounded summary: connector-specific sequencing, units, pagination, aliases,
+and generic API conventions still require the guide when they affect the task,
+while a complete and unambiguous one-read schema proceeds directly.
+Guide lookup always uses an exact name returned by `skills({})`, search, or
+describe; callers do not manufacture `connector:<id>` from an unmarked
+connector.
+
+A connector-scoped lexical miss retains that connector's guide metadata under
+`queryAnalysis`. This matters for generic wrappers whose broad tool name does
+not contain endpoint vocabulary: a required guide remains discoverable before
+the caller falls back to an empty-query browse, rather than disappearing with
+the zero-tool page.
+
+The built-in `usage` skill is byte-identical across deployments and says to
+read it at most once per task. Connector guides remain scoped to the deployment
+that listed them, even when two deployments happen to use identical content.
+Deployments without connector guides receive none of the conditional guide
+sentences in their always-loaded tool descriptions.
+
 ## Result representation
 
 For object results, `structuredContent` is the canonical full-fidelity value.
@@ -122,7 +188,13 @@ results explain that no single tool covered every term and recommend splitting
 distinct intents. A true negative says that no matching capability is
 configured and recommends refining, connector-scoping, or browsing; when a
 connector catalog was unavailable, the response includes
-`unavailableConnectorCount` instead of making that stronger claim. Analysis
+`unavailableConnectorCount` instead of making that stronger claim. A search
+explicitly scoped to that unavailable connector also receives `catalogError` —
+the bounded classified failure (`code`, `message`, `retryable`, and any
+`retryAfterMs`) so the caller can tell a transient outage from one a deployment
+operator must clear. It carries nothing else the call-path classifier knows: a
+discovery read is not a call. Unscoped searches keep the count only — one
+connector's failure is not another search's context. Analysis
 from a connector-filtered search includes `connectorScope` and speaks only
 about that connector; `unknownConnector` distinguishes an unconfigured ID from
 a known connector with no match. Analysis covers at most eight distinct terms

package/documentation/mixpanel.md

@@ -0,0 +1,72 @@
+# Mixpanel prebuilt connection
+
+Import `mixpanel()` independently from
+`@zackbart/connecta/providers/mixpanel`. It wraps Mixpanel's hosted MCP server
+with regional endpoint selection, OAuth by default, a provider-rate admission
+budget, a task-oriented usage guide, and a vetted safety classification. It
+adds no provider dependency and is not reachable from Connecta's root entry.
+
+```ts
+import { mixpanel } from "@zackbart/connecta/providers/mixpanel";
+
+const analytics = mixpanel("product_analytics", {
+  title: "Production product analytics",
+  purpose: "Product and growth decisions for the production app",
+  region: "us",
+  instructions: "Use the Core Product project unless the request says otherwise.",
+});
+```
+
+The `id` owns the ordinary connector namespaces; use a different id for every
+Mixpanel account. `purpose` is required because an agent choosing between two
+instances needs to know which account answers the question. Account
+`instructions` are appended to the maintained guide and cannot change the
+connector's safety classification.
+
+`region` accepts `"us"` (the default), `"eu"`, or `"in"` and selects the
+corresponding [official hosted endpoint](https://docs.mixpanel.com/docs/mcp#mcp-server-urls).
+OAuth is the recommended default and keeps each connector instance's flow and
+tokens in its connector-scoped storage. Mixpanel service accounts are also
+supported with an explicit header override:
+
+```ts
+mixpanel("automation_analytics", {
+  purpose: "Headless release-health reporting",
+  auth: {
+    type: "headers",
+    headers: { Authorization: `Bearer Basic ${env.MIXPANEL_SA_TOKEN}` },
+  },
+});
+```
+
+Keep that encoded service-account value in the runtime's secret store; it is a
+password, not ordinary configuration. Mixpanel currently labels service-account
+MCP authentication beta. Prefer OAuth unless the deployment is intentionally
+headless.
+
+The wrapper classifies the documented observational tools as reads and the
+documented create, update, edit, merge, dismiss, duplicate, and delete tools as
+writes. An unfamiliar tool added by the downstream fails closed onto
+`call_destructive_tool` until a Connecta release reviews it.
+
+That classification is **fill-in only**. It supplies the annotations Mixpanel
+leaves unset and may always tighten one — but it never contradicts an explicit
+downstream annotation. A tool on the read allowlist that arrives carrying
+`destructiveHint: true` or `readOnlyHint: false` keeps exactly what the
+downstream said and stays behind `call_destructive_tool`: the downstream is
+telling you this release's allowlist is stale, and the fail-closed invariant
+does not bend for a maintained connection. Maintained writes that only create
+something new (`Create-Dashboard`, `Create-Cohort`, `Create-Metric`, and the
+rest) leave `destructiveHint` unset; `readOnlyHint: false` already routes them
+through the destructive path, and asserting destruction only inflates the
+approval copy the host shows a human.
+
+Experiments and Feature Flags — 15 of the 63 classified tools — are Mixpanel
+beta surfaces. Expect their names and schemas to move faster than the rest.
+
+The connection also declares a per-runtime call-admission budget matching
+Mixpanel's documented 600 requests per hour — a best-effort approximation of
+the per-user limit, not an enforcement of it. Each runtime keeps its own
+counter, so N Worker isolates or Node processes serving one deployment can each
+admit up to 600. Discovery traffic is outside connector call admission and
+still needs restrained use.

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

@@ -15,9 +15,12 @@ order, and amending it is a design decision, not a drive-by edit.
 - **A deployment is a small config-as-code file.** Changing what agents can
   reach is an edit and a redeploy. One deployment, one tenant, one audience —
   more audiences means more deployments.
-- **Two equal ways in.** `remoteMcp()` proxies a downstream MCP server;
-  `api()` hand-writes a deliberate tool surface over a plain HTTP API. Both
-  come out identical: same addresses, same catalog, same safety rules.
+- **Curated when available, open when not.** Prefer an explicitly imported
+  prebuilt connection when Connecta maintains one: it carries the provider's
+  known-good endpoint, authentication defaults, tool ergonomics, and concise
+  usage guidance. `remoteMcp()` and `api()` remain equal, first-class
+  primitives for custom and unsupported integrations. Every path produces the
+  same `Connector`: same addresses, same catalog, same safety rules.
 - **Seven tools, an executor required.** The primary surface is a program, so
   every deployment runs an executor — a Dynamic Worker on Cloudflare, QuickJS
   behind its optional-peer subpath on Node — and one without refuses to boot
@@ -66,6 +69,8 @@ proposing one without a new argument is not.
 | Multi-tenancy / account model | refused | one deployment per tenant; deploy again instead |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | Runtime connector registration | refused | config-as-code is the security model |
+| Prebuilt connections as the preferred authoring path | accepted | an a-la-carte provider constructor, imported and constructed in the deployment file, encodes maintained defaults for providers connecta actually uses — preferred *when maintained*, with no promise of one per provider; it returns exactly one ordinary `Connector` with no extra privileges — never a bundle, a group, a preset, or a registry — its tools are hand-written or proxied from a downstream MCP catalog, never generated from a schema document; its vetted annotations classify what the downstream leaves unannotated and never overrule an explicit one; `remoteMcp()` and `api()` stay first-class ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Provider registry / integration marketplace | refused | prebuilt connections are imports, not listings; discovery happens in documentation, never at runtime ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Protocol sessions & server push | refused | stateless per request |
 | Resources & prompts aggregation | refused | tools only; connecta's own Apps shell is the one `resources/read` carve-out ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Elicitation passthrough | refused | no route through a stateless aggregator |
@@ -95,7 +100,8 @@ 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)) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.12.1",
+  "version": "0.13.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.",
@@ -64,6 +64,10 @@
     "./auth/clerk": {
       "types": "./dist/auth/clerk.d.ts",
       "import": "./dist/auth/clerk.js"
+    },
+    "./providers/mixpanel": {
+      "types": "./dist/providers/mixpanel.d.ts",
+      "import": "./dist/providers/mixpanel.js"
     }
   },
   "scripts": {