@zackbart/connecta 0.30.0 → 0.32.0

package/documentation/integrating.md

@@ -35,7 +35,7 @@ const tracker = linear("tracker", {
 ```
 
 Linear defaults to OAuth; its read-only endpoint requests only the downstream
-read scope. That is separate from Connecta pool trust. Read the
+read scope. That is separate from a Connecta `readOnly` endpoint. Read the
 [Linear skill](https://github.com/zackbart/connecta/blob/main/src/providers/linear/SKILL.md)
 and [factory options](https://github.com/zackbart/connecta/blob/main/src/providers/linear/index.ts)
 for API-key framing, workspace instructions, and admission choices.
@@ -49,11 +49,73 @@ mapping from admitted identity to the downstream account; a request must not
 choose its own account. Gmail never sends mail, and Drive never permanently
 deletes files.
 
-Notion, Vercel, and Cloudflare default to hosted MCP. Their explicit
-`surface: "api"` choices retain selected REST capabilities, with Notion's
-internal-integration identity preserved. To use both, configure distinct IDs
-and independent credentials. Read the [0.29 migration guide](./provider-migration-0.29.md)
-and its provider reconciliation tables for retained and removed names.
+Wispr Flow uses OAuth only through `wisprFlow()` from
+`@zackbart/connecta/providers/wispr-flow`. It reaches the authorized account's
+Notetaker content, with personal and work accounts holding separate data.
+Its [provider guide](https://github.com/zackbart/connecta/blob/main/src/providers/wispr-flow/SKILL.md)
+owns account access, search limits, transcript permissions and paging. The
+reviewed classification includes task writes listed in Claude's directory even
+though Wispr's public help describes read-only access; discover the account's
+actual tools before assuming those writes exist.
+
+Stripe requires `auth`: `{ type: "oauth" }` reaches Stripe's hosted MCP
+server, and `{ type: "apiKey" }` with `mode` reaches Connecta's REST connector
+with an operator-managed key. Notion requires `auth` the same way:
+`{ type: "oauth" }` acts as the signed-in user over Notion's hosted MCP, and
+`{ type: "token" }` acts as an internal integration over Connecta's REST
+connector. Cloudflare requires `auth` too: `{ type: "oauth" }` reaches its
+hosted MCP server, and `{ type: "apiToken" }` or `{ type: "globalApiKey" }`
+reaches Connecta's REST connector, with an optional `pin` of accounts and zones
+(required for a Global API Key unless `unpinned: true`). Vercel requires `auth`
+as well: `{ type: "oauth" }` reaches Vercel's hosted MCP server, and
+`{ type: "token" }` with an optional `teamId` reaches Connecta's REST connector
+with an operator-managed access token. Vercel admits only reviewed and approved
+MCP clients to its hosted server, an operational gate outside Connecta. See the
+[provider auth migration](./provider-auth-migration.md).
+To use both implementations of one provider, configure two connector ids with
+independent credentials.
+
+Planning Center's `excludeApps` removes whole products from a connection, for
+example `planningCenter("pco", { purpose, excludeApps: ["giving"] })` for a
+deployment that keeps agents away from donor and financial data. Excluded
+products lose their named tools, guide text, and version pins, and the
+`pco_api_get` and `pco_api_mutate` hatches refuse their paths before sending.
+The check reads the exact URL the transport would fetch, and while any product
+is excluded a hatch path must be literal: dot segments, empty segments,
+backslashes, whitespace, and percent-encoded `/`, `\`, `?`, `#`, or `%` are
+refused rather than normalized.
+
+Exclusion also closes the routes through which the excluded product's data is
+reachable through another product. While any product is excluded the connection removes
+`list_lists`, `list_list_people`, and `run_list` and refuses every People list,
+list result, rule, and condition, by path or `include`, because a list's
+conditions can draw on any product, such as a donor list built from Giving
+donations, and lists can depend on other lists. Planning Center publishes a
+list's conditions, but a reliable check would have to follow every nested list,
+so the connection does not attempt one. It refuses webhook event and delivery
+payloads, since a payload can carry any product's records, and every change to
+an existing webhook subscription by id, since the id does not name its product.
+A new subscription must name a reachable product's event. People cannot be
+excluded.
+
+What exclusion guarantees is that agents reach none of the excluded product's
+endpoints, no live cross-product query such as a People list, and no webhook
+payload or change to an existing subscription. It does not hide records that the church's own
+automations or staff have copied into a reachable product. A
+[Giving automation](https://help.planningcenter.com/en/144355-automations-in-giving.html)
+can add first-time donors to a People workflow, and those workflow cards stay
+readable, as do donor details recorded in notes, custom fields, or form
+answers. Those are People data once written, so the connection does not refuse
+them by guessing at their origin.
+
+For a hard boundary, give the connection a personal access token belonging to a
+Planning Center user with No Access in the excluded product. Planning Center
+sets permissions per product for each user, does not grant Giving to
+organization administrators automatically, and lets People workflows be shared
+per workflow; a token carries its user's permissions, so Planning Center itself
+refuses what that user cannot see. `excludeApps` is defense in depth on top of
+that boundary: it narrows what Connecta exposes, not what the token can do
+elsewhere.
 
 ## Another remote MCP server
 
@@ -126,9 +188,10 @@ which binds the grant to configured API origins and manages authentication.
 [Downstream OAuth on api()](./auth.md#downstream-oauth-on-api) owns a concrete
 HTTP example and the client setup contract.
 
-Mark every side-effecting tool `readOnlyHint: false`. On read-only endpoints
-writes use `call_destructive_tool`; trusted programs may write within their
-grants. Host approval is independent of tool definition. Use declared output
+Mark every side-effecting tool `readOnlyHint: false`. On a writable endpoint
+writes use `call_destructive_tool` or a program, within the caller's grants; a
+`readOnly` endpoint refuses them and omits them from search. Client approval is independent of
+tool definition. Use declared output
 schemas when known; runtime observations cannot replace them.
 
 ## Separate ownership from visibility

package/documentation/meta-tools.md

@@ -2,7 +2,7 @@
 
 Connecta keeps one small tool surface in model context and resolves downstream
 tools behind it. `search_tools` finds addresses, the call tools enforce the
-stored classification, `execute_code` runs programs under pool trust, and `connecta.result` inside programs
+stored classification, `execute_code` runs programs on a writable or read-only endpoint, and `connecta.result` inside programs
 pages bounded results.
 
 This guide is the contract an MCP client sees. The in-program `connecta.*` API
@@ -31,10 +31,13 @@ configuration adds a seventh or removes one, so a client's cached tool list
 never depends on the storage behind the deployment. There was an eighth,
 `resume_execution`, while programs paused at writes; it left with pausing
 ([#672](https://github.com/zackbart/connecta/issues/672)). `execute_code`
-is annotated `readOnlyHint: true, destructiveHint: false` on a `read-only`
-endpoint, and `readOnlyHint: false, destructiveHint: true` on a `trusted`
-endpoint. Approval belongs to the host. Pool trust never changes connector
-visibility or tool grants. The four tools with structured-only success results
+is annotated `readOnlyHint: true, destructiveHint: false` on a read-only
+endpoint, and `readOnlyHint: false, destructiveHint: true` on a writable one.
+Approval belongs to the client. A read-only endpoint keeps all six tools, omits
+write tools from `search_tools` results and describe, and refuses every write
+call; `readOnly` never changes connector visibility or read grants. Guides
+(`queryAnalysis.guideSummary`, `skills`, `connecta.skill`, skill
+`resources/read`) are documentation and may name tools the endpoint refuses. The four tools with structured-only success results
 advertise `outputSchema`. The two direct-call tools omit it because their default
 mode returns native `content`. Default-mode successes declare
 `_meta["dev.connecta/format"]: "json" | "text"`; value mode places the value in
@@ -70,9 +73,11 @@ credentials, logs, or raw error text.
 
 Connecta's discovery tools carry read-only hints. `authorize_connector`
 requests interactive authentication changes; `call_destructive_tool` sends
-writes and is annotated destructive. `execute_code` reports the selected pool's
-trust in its description and annotations. Its host may approve the whole
-program on a trusted endpoint. `call_destructive_tool.reason` is dropped before
+writes and is annotated destructive. `execute_code` states whether the endpoint
+is read-only or writable in its description and annotations. On a writable
+endpoint the client may approve the whole program as a write. On a read-only
+endpoint, the `call_tool`, `call_destructive_tool`, and `search_tools`
+descriptions say so too; `call_destructive_tool` still runs reads there. `call_destructive_tool.reason` is dropped before
 anything runs.
 
 ## Routing between the call surfaces
@@ -93,12 +98,16 @@ page the completed direct-call result or oversized program return with
 `connecta.result` after the write runs once. Sampling or slicing a write's output
 inside the program can still discard the answer.
 
-A `trusted` pool lets the same program discover and dispatch writes.
-A `read-only` pool refuses writes before validation or dispatch with
-`destructive_tool_requires_approval` and a `nextAction` naming
-`call_destructive_tool` and the canonical address. Each write then uses its
-own top-level call. Connecta never pauses, replays, or approves a program.
-Top-level discovery remains available for catalog inspection and write routing.
+On a writable endpoint the same program discovers and dispatches writes, capped
+by `execute.maxWrites`, and `call_destructive_tool` sends one known write. On a
+read-only endpoint nothing writes: `search_tools`, `connecta.search`, and
+`connecta.describe` omit write tools as if the connector lacked them, and
+every write call through `call_tool`, `call_destructive_tool`, or a program is
+refused before validation or dispatch with `read_only_endpoint`,
+`retryable: false`, and no `nextAction`. Connector guides are not filtered and
+may still name such a write. No route on that endpoint writes; the agent
+reports it. Connecta
+never pauses, replays, or approves a program.
 
 Both search routes return the flat page specified under
 [lexical discovery](#lexical-discovery), using the catalog's shared output schema.
@@ -129,14 +138,14 @@ Read-only lookup belongs in `connecta.search` inside the program; top-level
 `search_tools` stays for explicit catalog inspection and approval-required
 discovery. Both take the same arguments.
 
-| Argument           | What it does                                                                                                                                                                                                                                                            |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `query`            | two to four action/object terms; empty or whitespace-only browses                                                                                                                                                                                                       |
-| `connector`        | scopes to one id, loading that catalog alone instead of fanning out across every configured connector. Set it when the integration is obvious, omit it when the right one is genuinely ambiguous                                                                        |
-| `safety`           | `"readOnly"` selects stored `read` verdicts; `"approvalRequired"` selects stored `write` verdicts; omitted or `"all"` selects both. Each row carries `classification: "read" \| "write"`. These legacy filter names do not describe host approval policy or pool trust. |
-| `limit` / `offset` | page the ranked results; omit `limit` initially so the default eight-result page stays small                                                                                                                                                                            |
-| `includeSchemas`   | `"compact"` for the rendered routing view, `"json"` for the exact schema, `"typescript"` for a function signature ([below](#typescript-signatures))                                                                                                                     |
-| `fullDescriptions` | unabridged tool purposes, at the obvious cost                                                                                                                                                                                                                           |
+| Argument           | What it does                                                                                                                                                                                                                                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `query`            | two to four action/object terms; empty or whitespace-only browses                                                                                                                                                                                                                                   |
+| `connector`        | scopes to one id, loading that catalog alone instead of fanning out across every configured connector. Set it when the integration is obvious, omit it when the right one is genuinely ambiguous                                                                                                    |
+| `safety`           | `"readOnly"` selects stored `read` verdicts; `"approvalRequired"` selects stored `write` verdicts; omitted or `"all"` selects both. Each row carries `classification: "read" \| "write"`. These legacy filter names do not describe client approval policy; a read-only endpoint has no write rows. |
+| `limit` / `offset` | page the ranked results; omit `limit` initially so the default eight-result page stays small                                                                                                                                                                                                        |
+| `includeSchemas`   | `"compact"` for the rendered routing view, `"json"` for the exact schema, `"typescript"` for a function signature ([below](#typescript-signatures))                                                                                                                                                 |
+| `fullDescriptions` | unabridged tool purposes, at the obvious cost                                                                                                                                                                                                                                                       |
 
 Neither `connector` nor `safety` grants authority or changes invocation
 admission; they select what discovery shows and nothing else.
@@ -381,7 +390,7 @@ caught catalog-load errors, unknown-tool failures, and recovery messages that
 list visible connectors or local guides. Returns with no downstream calls still
 require matching identity, origin and endpoint, current auth, and pool membership. A page must
 match those bindings and pass current auth, connector/tool grants, pool membership,
-and trust checks. Old entries lacking bindings fail closed. A random UUID is a
+and read-only checks. Old entries lacking bindings fail closed. A random UUID is a
 handle, never an access grant.
 
 New entries store UTF-8 bytes in a base64 envelope split across storage keys,
@@ -512,13 +521,10 @@ format: "text", text }`. The page size is clamped to the original call's inline
 cap and a 32 KiB program bridge ceiling, with UTF-8 alignment and forward progress. Reassemble inside the sandbox;
 returning pages unchanged can hit the program result cap. The admitted subject
 and principal, endpoint/pool, request origin, connector, and tool bindings must
-match. The host rechecks current access and trust before returning each page; a
-read-only endpoint cannot read a write stash. Caller arguments select no partition.
-
-A write on a read-only endpoint returns an inline truncation notice and any
-usable bounded preview. It says paging is unavailable and the write already
-ran; it carries no result handle or recovery action and stores no unreachable
-stash. Write paging remains available on trusted endpoints.
+match. The host rechecks current access and whether the endpoint is read-only
+before returning each page; a read-only endpoint cannot read a write stash.
+Caller arguments select no partition. A read-only endpoint never runs a write,
+so every write result it could page came from a writable endpoint.
 
 A refused stash write cannot undo a downstream success. Direct calls and program returns produce
 a paging-unavailable notice, without a handle or recovery action. A write's
@@ -820,10 +826,11 @@ attempted tool name; an unknown tool scopes the same query to the connector that
 answered. The suggested route follows the route the caller took:
 `tool: "search_tools"` for a top-level call, `function: "connecta.search"` with
 the same arguments when the miss happened inside `execute_code`, which has no
-way to call a tool. `call_tool` reaching an unannotated, write-capable, or
-destructive tool returns `nextAction` for `call_destructive_tool` with the
-canonical address, and so does the same call inside a program, unless config
-marks that pool trusted. Nothing is executed by these records.
+way to call a tool. On a writable endpoint, `call_tool` reaching an unannotated,
+write-capable, or destructive tool returns `destructive_tool_requires_approval`
+with `nextAction` for `call_destructive_tool` and the canonical address. On a
+read-only endpoint every write path returns `read_only_endpoint` with no
+`nextAction`. Nothing is executed by these records.
 
 `connecta.describe` keeps its failures inline instead, so one miss cannot
 discard the other schemas; each failed entry carries a human `error`, typed
@@ -924,13 +931,20 @@ scoped registry, including an empty list when none are accessible. They never
 list connectors from another pool or identity's grants.
 
 A write that times out after dispatch returns `write_outcome_unknown` with
-`retryable: false` and an agent-only `uncertainCall: { address, args?, argsOmitted?, argsRedacted? }`.
-No write is automatically replayed. `args` may be partial reconciliation context
+`retryable: false` and an agent-only `uncertainCall: { address, args?, argsOmitted?, argsRedacted?, recovery? }`.
+No write is automatically replayed. `recovery` carries facts the connector
+recorded before dispatch (`src/call-recovery.ts`), such as the `idempotencyKey`
+a REST connector generated; a deliberate retry that reuses it with the exact
+original arguments cannot repeat the write while the vendor retains the key
+(Stripe may prune v1 keys after 24 hours). After that, look the object up before
+retrying. When a connector recorded such facts, any other dispatched write whose
+outcome is unknown (a lost response body, a 5xx) also carries `uncertainCall`
+with them under its own code, and program write accounting keeps it. `args` may be partial reconciliation context
 with `argsRedacted: true`. A withheld echo or arguments over the 512-byte budget
 carry `argsOmitted: true`; sensitive or unresolved schemas also carry
 `argsRedacted: true`. When `args` is absent or redacted, use the original
-arguments if reconciliation requires another call. A timeout before dispatch remains `timeout`. Trusted
-program write accounting keeps this detail even if the guest catches the
+arguments if reconciliation requires another call. A timeout before dispatch remains `timeout`.
+Program write accounting keeps this detail even if the guest catches the
 failure or returns early. Multiple uncertain writes use `uncertainCalls`,
 bounded to ten calls with `uncertainCallsTruncated` when more exist.
 

package/documentation/operating.md

@@ -15,14 +15,17 @@ instructions and `skills` usage guide for deployment-specific context.
 | ------------------------------------------------------------------ | --------------------------------------------------------- |
 | One known read, with usable arguments and a small result           | `call_tool`                                               |
 | Discover a tool, chain calls, combine services, or reduce a result | `execute_code`                                            |
-| One write on a read-only endpoint                                  | `call_destructive_tool`                                   |
+| One known write on a writable endpoint                             | `call_destructive_tool`                                   |
 | Obtain connector instructions                                      | `skills` with the returned guide name                     |
 | Start a required authentication handoff                            | `authorize_connector`, using the returned recovery action |
 
-The endpoint's trust is part of its tool descriptions. On a `trusted` endpoint,
-programs may write within the caller's grants, and `execute_code` is annotated
-as a write. On `read-only`, every write is a separate top-level call. The host
-controls approval. Never change pool, identity, or trust to work around a refusal.
+Whether the endpoint is read-only or writable is part of its tool
+descriptions. On a writable endpoint, programs and `call_destructive_tool` may
+write within the caller's grants, and `execute_code` is annotated as a write;
+the client controls approval. On a read-only endpoint, search and describe omit
+write tools and every write call is refused with `read_only_endpoint`, even one
+a connector guide names; tell the user rather than looking for another route. Never change pool, identity, or `readOnly` to work
+around a refusal.
 [Routing between the call surfaces](./meta-tools.md#routing-between-the-call-surfaces)
 owns the full decision rules.
 
@@ -35,9 +38,9 @@ failed catalog or a service outside the caller's grants.
 
 For normal reads, keep discovery, calls, and reduction in one program when the
 schemas suffice; return the answer rather than catalog matches. Use top-level
-`search_tools` for catalog inspection or to discover a write on a read-only
-endpoint, then dispatch each write with `call_destructive_tool`. An unfamiliar
-read result may return a bounded sample for inspection before the next program.
+`search_tools` for catalog inspection or to find one known write on a writable
+endpoint, then dispatch it with `call_destructive_tool`. An unfamiliar read
+result may return a bounded sample for inspection before the next program.
 
 Use the exact returned `address`, including punctuation. A TypeScript signature
 is guidance for writing JavaScript; do not paste types into executable code.

package/documentation/operator-tests.md

@@ -72,9 +72,8 @@ gh run download RUN_ID --name operator-linux-snapshots \
 
 The workflow uploads all generated baselines and never commits them. Review the
 images and changed files, commit the intentional changes, and push again. The
-normal CI browser job must compare and pass against that commit. Opening the
-initial PR also runs the update workflow, so the first baselines can be generated
-before the workflow reaches main. Later updates use `workflow_dispatch`.
+normal CI browser job must compare and pass against that commit. Snapshot
+updates run only through `workflow_dispatch`.
 
 On a matching Linux runner, `npm ci`, install Chromium with the command above,
 then run `npm run test:browser:snapshots`. The normal command is

package/documentation/operator-ui.md

@@ -42,7 +42,9 @@ from `connecta/ui`. `src/operator-ui/contract.ts` is also the browser's type
 source. The response has `schemaVersion: 1`, `config`, `configSources`, `live`, and `you`.
 `config` is the construction-time `describeConfig()` snapshot, filtered to
 visible connectors, granted tools, classification overrides, and admitted
-pools. Pool tools are the intersection with the caller's identity grants.
+pools. `config.hasGrant` reports whether deployment code configures a grant for
+plain `/mcp`; Access displays that fact and Config includes its provenance.
+Pool tools are the intersection with the caller's identity grants.
 `configSources` labels each serialized leaf as `default` or `config`, based on
 option presence rather than equality with the default. Factory descriptions carry
 relative `optionSources` paths so resolved module and transport defaults retain
@@ -52,6 +54,10 @@ ids and pool names and are filtered after disclosure; hidden values leave no
 provenance keys. It contains no source code or credential material.
 Every response is private, `no-store` JSON. Only GET is allowed, with the
 same auth gate and identity partition as `/ui/data` and `/ui/connectors/:id`.
+These catalog reads, activity reads, and connector auth routes also require
+admission through the default `/mcp` grant. Refusals return private JSON 404s;
+there is no per-pool UI view. Public HTML shells and static assets carry no
+catalog data. Access-token management retains its interactive permission gate.
 
 `live.connectors` carries status and problem codes, complete registry tools
 with their final read/write classification, catalog age in milliseconds, and
@@ -69,7 +75,7 @@ personal connectors to the caller's activity identity. Each retained fact
 copies a validated timestamp and outcome only. A null call means unknown or
 absent in that window, not proof of no calls. `live.activity` distinguishes
 available, unconfigured, forbidden, and unavailable history. `you` names no
-identity or auth material; it reports grants, root and admitted-pool trust,
+identity or auth material; it reports grants, whether the root and admitted pools are read-only,
 and effective activity, token, and per-connector auth permissions.
 
 `connecta doctor --config` fetches this authenticated contract and prints only
@@ -112,7 +118,7 @@ id and typed actor when available, otherwise a fresh id and system actor. No
 names, descriptions or schemas enter the event. Private catalog changes require
 a matching principal owner even when the connector uses shared auth. Empty credential declarations
 report `credential_required` before running a connector status or catalog probe.
-The Access adapter reports inbound provider kinds, admitted pools, grants, trust
+The Access adapter reports inbound provider kinds, admitted pools, grants, read-only endpoints
 and endpoint setup; token controls retain their existing permission gate.
 Configuration remains in deployment code. The UI mutates only credentials,
 OAuth connections and client tokens through the existing routes.