@zackbart/connecta 0.34.1 → 0.35.0

package/documentation/operator-tests.md

@@ -175,6 +175,9 @@ updates run only through `workflow_dispatch`.
 On a matching Linux runner, `pnpm install --frozen-lockfile`, install Chromium with the command above,
 then run `pnpm run test:browser:snapshots`. The normal command is
 `pnpm run test:browser`. Missing baselines fail CI; retries cannot bless them.
+Visual comparisons run in their own Playwright project without retries, so a
+mismatch fails on its first attempt. When any attempt fails, CI uploads
+the HTML report, actual/expected/diff images and traces as `playwright-report`.
 Set `OPERATOR_VISUAL_INSPECT=1` to retain local screenshots under ignored
 `test-results/` for inspection, without updating committed baselines.
 

package/documentation/operator-ui.md

@@ -42,15 +42,15 @@ No select menu displays configuration. Copy is short labels; a failure names
 what to do next in one or two sentences and never quotes a route's or
 downstream's text.
 
-| Path               | Page                                                   | Who        |
-| ------------------ | ------------------------------------------------------ | ---------- |
-| `/`                | Overview (a member gets the member page)               | Maintainer |
-| `/endpoints`       | Endpoints; `#mcp/<pool>` opens that row                | Maintainer |
-| `/connectors`      | Connectors list; `?view=matrix` for the matrix         | Maintainer |
-| `/connectors/<id>` | Connector detail; `#tools`, `#connection`, `#activity` | Maintainer |
-| `/activity`        | Activity                                               | Maintainer |
-| `/tokens`          | Tokens, when token management is open to the viewer    | Maintainer |
-| `/settings`        | Settings                                               | Maintainer |
+| Path               | Page                                                         | Who        |
+| ------------------ | ------------------------------------------------------------ | ---------- |
+| `/`                | Overview (a member gets the member page)                     | Maintainer |
+| `/endpoints`       | Endpoints; `#mcp/<pool>` opens that row                      | Maintainer |
+| `/connectors`      | Connectors list; `?view=matrix` for the matrix               | Maintainer |
+| `/connectors/<id>` | Connector detail; `#tools`, `#connection`, `#activity`       | Maintainer |
+| `/activity`        | Activity                                                     | Maintainer |
+| `/tokens`          | Tokens, when agents are declared or token management is open | Maintainer |
+| `/settings`        | Settings                                                     | Maintainer |
 
 `/access` redirects to `/endpoints`, `/tools` to `/connectors`, and `/config`
 to `/settings`, replacing the history entry. Connector hashes `#config`,
@@ -109,6 +109,10 @@ instead of "0 tools".
 
 ### Endpoints
 
+Pool endpoint rows show the effective surface (`meta` or `native`) and whether
+code is on. These are read-only facts from deployment configuration; change
+`surface` and `executeCode` in deployment code.
+
 One row each for `/mcp` and every pool: the path, a read-only pill on a
 read-only endpoint, a copyable URL, who can use it, its connectors as colored
 monograms (four, then "+N"), its tool count over a read and write bar, and a
@@ -192,7 +196,7 @@ tabs:
 - **Connection.** An Authentication card (mode, OAuth client mechanism, who
   manages it, OAuth actions, and the credential card with masked last four,
   field states, and Replace, Test and Remove); a Diagnostics card of tiles
-  (catalog age, last call, drift counts) with a fix prompt beside each
+  (catalog age and last call) with a fix prompt beside each
   problem; and a Configuration card. Its badges name the kind (Remote MCP,
   HTTP API or Custom), provider, auth scope, endpoint host and usage guide.
   The auth row names the mode and draws each auth fact as a mono badge
@@ -204,29 +208,12 @@ tabs:
 - **Activity.** The [Activity](#activity) page for that connector, without
   connector chips or monograms.
 
-#### Read catalog drift
-
-The connector's drift panel reports the last catalog comparison in this
-runtime and identity partition. It never lists tool names or schemas. A
-personal OAuth refresh belongs to that user; another user or endpoint subject
-does not inherit it. A runtime restart or bounded observation eviction resets
-the report until another listing is served.
-
-“No catalog refresh yet” means this partition has no observation. “No reviewed
-baseline” means a listing was observed without a reviewed classification.
-“Matches the reviewed manifest” requires a baseline, successful verification,
-no differences, and schema pins for every live reviewed tool. “Schemas not
-pinned” and “Partial schema coverage” describe missing review evidence; they
-are not clean schema comparisons. “Schema verification unavailable” replaces
-an earlier successful report if hashing fails. Known differences remain visible
-alongside coverage or verification limits. Each operator refresh returns the
-comparison from the catalog it just loaded, including hashing failures and
-schema changes, without another downstream status probe.
-
-The unserved count excludes reviewed names explicitly marked optional for
-plan, feature, or permission gating. Present optional tools still participate
-in annotation and schema comparisons. Dropped tool names are counted even
-without a baseline, and do not establish one.
+#### Read catalog changes
+
+Catalog refresh activity reports added, removed, and changed tool counts within
+its identity partition. The UI no longer compares tools with a release-reviewed
+manifest or shows schema-pin coverage. Check live annotations and deployment
+classification in the catalog when reviewing exposure.
 
 ### Settings
 
@@ -260,9 +247,13 @@ editing controls. An empty section is not drawn.
 
 ### Tokens
 
-One row per agent declared in code, in `GET /ui/access-tokens` order: agent
-mark and name, pools as chips, a state pill (No token, Issued or Revoked), the
-issue or revoke date, and last seen ("never" when null). The heading note
+One row per agent declared in code, including OIDC-only agents when the token
+module is absent: agent mark and name, supported credentials (Agent token,
+Vercel OIDC, or both), pools as chips, a token state pill (Not configured, No
+token, Issued or Revoked), the issue or revoke date, and last seen ("never"
+when unknown). Not configured means the managed token module is absent and
+has no token controls; No token means that module has an unissued slot.
+An OIDC binding works independently of the token's state. The heading note
 reads "Declared in code"; nothing creates or renames an agent. Narrow screens
 stack each row into a card.
 
@@ -412,18 +403,36 @@ The maintainer view carries:
   code or credential material.
 - `root`: plain `/mcp`, its `readOnly`, and its `maintainers`, people only.
 - `pools`: every declared pool with `humanPath` (`/mcp/<name>`), `agentPath`
-  (`/agent/<name>`), `readOnly`, `owner` (the Workspace address its agents act
+  (`/agent/<name>`), `readOnly`, effective `surface` (`meta` or `native`),
+  `executeCode` (whether code is enabled), `owner` (the Workspace address its agents act
   as), its declared `tools` (never intersected; no `requireReadOnly` is ever
   true), and its `members`, agents as `{ kind: "agent", name }`. Every listed
   person carries a `label` from the same directory lookup activity actor
   labels use, on an interactive read only, and `null` without a directory
   (Cloudflare Access) or an entry. An open deployment's anonymous maintainer
   reads every `owner` as `null`.
-- `agents`: every agent declared in code, with its pools, its token slot
-  (`state`, `issuedAt`, `revokedAt`, `revision`) exactly as
-  `GET /ui/access-tokens` lists it, and `lastSeenAt`, the newest visible
-  activity row recorded for that agent, or `null` when activity is off or
-  none is visible. A slot read that fails answers 503 rather than drop agents.
+- `agents`: every agent declared in code, in deployment order, with its pools
+  and `credentialTypes` (`access_token`, `vercel_oidc`, or both). These are
+  immutable deployment descriptions: the token kind requires the managed
+  access-token module, and OIDC requires that agent's own workload binding.
+  They grant nothing. `token` is `null` when the token module is absent;
+  otherwise its slot (`state`, `issuedAt`, `revokedAt`, `revision`) is exactly
+  what `GET /ui/access-tokens` lists, including an unissued `state: "none"`.
+  A failed or incomplete slot read answers 503 rather than drop agents.
+  `lastSeenAt` is the newest sampled successful agent-endpoint admission or
+  visible historical activity timestamp, or `null` when unknown or withheld.
+  Admission means credential verification and membership in that declared pool
+  succeeded; it does not promise a completed call. Invalid credentials,
+  refused/undeclared pools and human routes record nothing. The observation
+  stores only the declared name and timestamp, independently of activity.
+  Admission observations sample at most once per minute: a valid stored time
+  less than 60 seconds behind the candidate skips the write, and an older
+  candidate never moves the time backwards. This is minute-level admission
+  evidence, not an exact timestamp for every request. Each observation uses at
+  most two atomic storage attempts under the smaller of the configured probe
+  deadline and 500 ms, within the request lifetime. Failure, timeout or
+  contention can lose a sample; a later eligible admission can try again.
+  Observation never refuses admission or retries MCP or tool work.
 - `matrix`: a cell per connector for plain `/mcp` (`pool: null`) and for each
   pool that serves it, with that endpoint's tool names or `"all"` and
   `runsAs`. A Workspace connector with a subject mapping is
@@ -447,10 +456,12 @@ The maintainer view carries:
   mechanism when known. Static and unobserved catalogs have a null age;
   persisted catalogs retain their original fetch time.
 - `live.activity`: available, unconfigured, forbidden, or unavailable history.
-  Last-call and last-seen lookups need the activity permission and read gate,
+  Historical last-call and last-seen lookups need the activity permission and read gate,
   scan up to 1,000 recent rows, filter connector/tool grants, restrict personal
   connectors to the caller's activity identity, and copy a validated timestamp
-  and outcome only. A null means unknown or absent in that window.
+  and outcome only. Admission last-seen reads require a maintainer and honor
+  the configured activity read gate, including when history is unavailable;
+  they work with no activity module. A null means unknown or withheld.
 - `connectors: []`.
 
 The member view is exactly that member's projection: `config`,
@@ -544,7 +555,14 @@ duplicate summary, token, config, detail or body reads. The passive retry schedu
 stays bounded and does not reset its budget on a deadline. Retry remains available
 during recovery configuration loading and supersedes and aborts the old cycle;
 identity changes, navigation and connector-page unmount also cancel it. Navigation
-that cancels pending data schedules a bounded reread for the destination. Failed reads retry after
+that cancels pending data schedules a bounded reread for the destination. A scoped OAuth poll publishes only its connector's detail and live row. It does
+not supersede a pending full admission or catalog/auth cycle, release its
+recovery guard, or clear its deadline. That full cycle still publishes other
+connectors as they settle and decides recovery, retaining the newer polled row
+even when its summary was pending or its deadline exposed Retry. Only a newer
+full cycle, mutation, identity change, or sign-out fences older work. Owed
+publication neither spends nor resets the failed-read retry budget and adds no
+timer. Failed reads retry after
 2, 2, 4, and 8 seconds. Refusals preserve the throttle and retry budget. After
 those four automatic retries, a focus return can request one more read after
 the eight-second backoff, without replenishing the automatic budget. Retry
@@ -601,6 +619,11 @@ 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.
 
+Activity label resolvers receive an optional `AbortSignal`. Pass it to user-directory
+fetches and stop work when it aborts: the reader has left or the label lookup
+budget has expired. Clerk label lookups follow the same lifetime and discard
+late answers after cancellation.
+
 ## Contributor reference
 
 ### Source and tests

package/documentation/provider-auth-migration.md

@@ -1,6 +1,11 @@
 # Provider auth migration
 
-Use this upgrade guide when moving a Stripe, Notion, Vercel, or Cloudflare
+Hosted selections described in this historical migration are now removed.
+For Stripe, Vercel, Cloudflare, Notion, Mixpanel, and GitHub hosted connections,
+use the [current hosted MCP migration guide](./hosted-mcp-migration.md).
+The API migrations below remain applicable.
+
+Use this upgrade guide when moving a Stripe, Vercel, or Cloudflare
 deployment from 0.30 to 0.31, where `auth` selects each provider's
 implementation.
 [Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
@@ -13,6 +18,9 @@ uses one implementation: configure two ids for both.
 
 ## Stripe
 
+For current API-key setup, use [Maintained provider setup](./providers.md#stripe).
+For the 0.35 argument and paging changes, use [Stripe surface migration](./provider-migration-0.35.md#stripe).
+
 ## Choose OAuth or an API key
 
 Import `stripe` from `@zackbart/connecta/providers/stripe`. Choose one of two setup paths:
@@ -84,7 +92,8 @@ or a generated one as `Idempotency-Key` and return it (DELETE sends none).
 Caller-supplied keys may contain up to 255 characters. An ambiguous POST write
 also returns the key in `uncertainCall.recovery.idempotencyKey`, including when
 the call deadline interrupts it. See [argument recovery](./meta-tools.md#argument-recovery)
-before retrying.
+before retrying: a custom connector that wraps or composes Stripe calls gets
+the key as a diagnostic only, never advice to reuse it.
 Every request, v1 and v2, sends `Stripe-Version: 2026-09-30.endive`, the
 version of the pinned index, whatever the account's default API version, so
 response shapes and accepted parameters follow that version. Check fields
@@ -100,56 +109,9 @@ connector need an OAuth connector beside it. Read the connector runtime guide wi
 
 ## Notion
 
-Every `notion()` call must now name `auth`. 0.30 defaulted to hosted MCP and
-selected the REST interface with `surface: "api"`; `surface` is gone:
-
-```ts
-connectors: [
-  notion("notion", { purpose: "Workspace content as the signed-in user", auth: { type: "oauth" } }),
-  notion("notion_bot", { purpose: "Internal integration content", auth: { type: "token" } }),
-]
-```
-
-| 0.30 configuration                                                                                                                        | Now                                                                                                                  |
-| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| No `surface`, or `surface: "mcp"`                                                                                                         | `auth: { type: "oauth" }`. Same endpoint, reviewed catalog, grant, and optional `callAdmission`.                     |
-| `surface: "api"`                                                                                                                          | `auth: { type: "token" }`. The integration token stored for the same connector id carries over; run its Test action. |
-| `credentialLabel` or `defaultPageSize`                                                                                                    | Token only, as before. Under OAuth they are refused by name at construction.                                         |
-| `integration_search`, `_get_page`, `_get_page_content`, `_get_data_source_schema`, `_query_data_source`, `_create_page`, `_append_blocks` | Unchanged names and contracts. `integration_append_blocks` also takes `checklist`.                                   |
-| `integration_get_database`                                                                                                                | `notion_api_read` `GET /v1/databases/{database_id}`.                                                                 |
-| `integration_get_page_property`                                                                                                           | `notion_api_read` `GET /v1/pages/{page_id}/properties/{property_id}`; `truncated_properties` names it.               |
-| `integration_list_users`, `integration_get_self`                                                                                          | `notion_api_read` `GET /v1/users` or `GET /v1/users/me`.                                                             |
-| `integration_list_comments`, `integration_add_comment`                                                                                    | `notion_api_read` `GET /v1/comments`; `notion_api_write` `POST /v1/comments`.                                        |
-| `integration_update_page_properties`, `integration_trash_page`                                                                            | `notion_api_write` `PATCH /v1/pages/{page_id}` with `properties`, or `in_trash` to trash or restore.                 |
-
-Both auth variants accept optional `callAdmission`. On a token connector it
-replaces the whole default policy of 180 calls per minute and 3 concurrent
-per runtime. Malformed policies throw at construction. Notion's
-[request limits](https://developers.notion.com/reference/request-limits) allow
-600 requests per minute per connection on Business and Enterprise and 180 on
-other plans, with a separate workspace-wide limit shared by all connections.
-Account for other runtimes and tools that make multiple HTTP requests when
-choosing an override.
-
-The token connector gains Connecta's generic REST tools over Notion's pinned
-API index (`notion_api_search`, `notion_api_details`, `notion_api_read`,
-`notion_api_write`), so every public operation is reachable with the bot's
-token: views, page moves and Markdown, meeting notes, custom agents and
-sessions, file uploads by `external_url`, and data source changes. Every call
-is checked against the index before it is sent, and results arrive as
-`{ status, data, page? }`. The read-only POST queries (search, data source,
-meeting notes, agents, sessions, and session events) use `notion_api_read`;
-`page.in: "body"` says their cursor goes back in the body. Notion's OAuth token
-endpoints and multipart file sends are refused. The 0.29 reconciliation table
-and the `surface: "api"` complement rules no longer apply to Notion.
-
-Lost per mode. A token connector acts as the integration bot, never as a
-person, and has none of the hosted MCP's search across connected apps, page
-duplication, team and skill search, attachment downloads, or page-to-skill
-conversion. An OAuth connector acts as the user, and has none of the generic
-REST tools or the `integration_*` projections and authoring helpers. Configure
-both ids when a deployment needs both; a failed call is never retried on the
-other. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
+The maintained Notion API provider is removed in 0.35. See the
+[provider removal migration](./provider-migration-0.35.md#remove-infisical-notion-and-mixpanel)
+and use generic `remoteMcp()` for the hosted server.
 
 ## Vercel
 
@@ -314,16 +276,7 @@ one; read or rotate withheld secrets in the vendor's dashboard.
   Failures of credential-bearing operations keep Stripe's type, code, and
   param but not its message. Create client-side sessions and links from your
   own server code.
-- **Notion** REST results and error text withhold the whole query and
-  fragment of canonical Notion file links, including links embedded in
-  Markdown and async task results. External proxy URLs keep their bytes;
-  AWS and Google signing-parameter values are withheld at any host. Writes
-  carrying the plain or encoded `[redacted]` placeholder in a Notion file
-  link's own query or fragment are refused before dispatch. See the
-  connector runtime guide through `connecta.skill("connector:<id>")` in `execute_code` for recognized hosts and scanning limits. Credential-named fields,
-  including database properties named like credentials, read as
-  `"[redacted]"`. Failures of the OAuth, file upload, bot user, and agent
-  operations keep Notion's code but not its message.
+
 - **Vercel** replaces environment values with `"[redacted]"` instead of
   dropping the field, and withholds Vercel's error text for every reviewed
   operation and every operation whose request takes a credential-named
@@ -341,4 +294,4 @@ one; read or rotate withheld secrets in the vendor's dashboard.
 [Decision 0005](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)
 explains why auth selects the implementation. Maintained provider source
 skills and review tables live under `src/providers/` in the repository;
-`src/providers/vercel/value-safety.ts` owns Vercel's reviewed table.
+`src/providers/vercel/safety.ts` owns Vercel's reviewed table.

package/documentation/provider-migration-0.29.md

@@ -1,12 +1,17 @@
 # Notion, Vercel and Cloudflare migration for 0.29
 
+Hosted selections described in this historical migration are now removed.
+For Stripe, Vercel, Cloudflare, Notion, Mixpanel, and GitHub hosted connections,
+use the [current hosted MCP migration guide](./hosted-mcp-migration.md).
+The API migrations below remain applicable.
+
 Use this upgrade guide for an existing deployment.
 [Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
 version changes; [integrating services](./integrating.md) covers new connectors.
 [The agent index](./README.md) routes package maintenance separately.
 
-This is the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709).
-Deploy it with the consolidated 0.29 release, not while the rework is in progress.
+This was the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709),
+which shipped as 0.29.0.
 Deployments that use Notion or Cloudflare must check their actual grants and
 connector ids in deployment configuration before that release.
 The provider audit establishes available auth modes, not production OAuth grants.
@@ -14,7 +19,7 @@ The provider audit establishes available auth modes, not production OAuth grants
 Cloudflare's part of this guide is superseded: `cloudflare()` now selects its
 implementation by `auth` and its key connector is complete on its own. Follow
 the [provider auth migration](./provider-auth-migration.md#cloudflare) for
-Cloudflare; the Cloudflare lines below record the 0.29 transition only.
+Cloudflare; the Cloudflare lines below record the transition shipped in 0.29.0 only.
 
 All three providers now default to hosted MCP. `surface: "api"` explicitly
 selects a REST complement and accepts only its API-specific options. The old
@@ -36,7 +41,7 @@ Notion has since moved to auth-selected implementations: `surface` is gone,
 and `auth: { type: "oauth" }` or `{ type: "token" }` selects hosted MCP or the
 REST connector. Upgrade with the
 [provider auth migration](./provider-auth-migration.md#notion); the rest of
-this paragraph records the 0.29 rules.
+this paragraph records the rules shipped in 0.29.0.
 Notion preserves headless/internal-integration capabilities. Add explicit
 `surface: "api"` to retain that identity and migrate old REST names to
 `integration_*`, for example `search` to `integration_search`, `create_page`
@@ -62,7 +67,7 @@ Writable endpoints may run `execute`; `readOnly` endpoints refuse it.
 
 Vercel's `surface` and ownership rules were later replaced: `auth` now selects
 the implementation. See the [provider auth migration](./provider-auth-migration.md#vercel).
-The 0.29 Vercel guidance follows for history. For Vercel, authorize the owning teams in hosted OAuth, migrate discovery/logs,
+The Vercel guidance shipped in 0.29.0 follows for history. For Vercel, authorize the owning teams in hosted OAuth, migrate discovery/logs,
 domain listing/adding, deployment cancellation and file uploads to live MCP
 schemas, and keep the independently authorized REST complement for value-safe
 project environment variables (including `upsert: false` create-only writes), domain verification/removal and deployment