@zackbart/connecta 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to this package are documented here.
 
+## 0.33.0 — 2026-10-16
+
+Connecta 0.33.0 makes pools the access model, and every deployment with inbound auth must change its configuration (#837). Work through `documentation/migration-0.33.md` before upgrading; it maps every removed option to its replacement. A new top-level `maintainers` list names the people who reach plain `/mcp` and administer the deployment. Each pool now has a static `members` list and serves exactly its `tools` to those members. Agents are declared by name in `agents`, each with one rotatable `cta_` token. Each removed option fails at startup with a message naming its replacement, so a deployment that starts has nothing silently ignored: `identity` (even `{}`) and its `connectorAccess`, `credentialAdministration`, `personalConnection`, `accessTokenManagement` and `activityAccess`, plus the top-level `grant` and pool `grant`.
+
+Agents move from `/mcp/<pool>` to `/agent/<pool>`, which admits only a declared agent's `cta_` token for a pool it belongs to. `/mcp`, `/mcp/<pool>` and the operator routes refuse `cta_` tokens, so point every agent at `/agent/<pool>`. Deployments behind Cloudflare Access add one Access application for `<host>/agent/*` with a single Bypass policy, after which agents send only their token. Tokens issued by earlier releases stop admitting until trusted provisioning adopts each one for an agent (`AccessTokenManager.adopt`, or `npm run adopt-token` in the Node template). Creating, renaming and human-bound tokens are gone, along with `maxActive`. Programmatic callers construct `AccessTokenManager` with `{ agents }` and call `rotate` where they called `create`, and `revoke(agent, options)`. Activity names agents by name. Rotation is an immediate cutover. HTTP issue, rotate and revoke requests must send the observed slot revision as `expect`; a stale revision gets 409 `slot_changed`. `AccessTokenManager.rotate`, `revoke` and `adopt` accept optional `expect` and reject a stale revision with `AccessTokenError.code: "slot_changed"`. A pool can set `owner`, the Google Workspace address its agents act as, so one Workspace connector serves a pool per person. An agent never reaches a `subject` mapping function, so a 0.32 mapping that answered for machine tokens must move to `owner`.
+
+This release also defines how to organize an agent's pools. Each agent has one Connecta connection whose client picks the pool per turn. The base pool `<agent>` holds shared connectors and is used in group chats, scheduled runs and anything else without exactly one identified person. An `<agent>-<user>` pool adds that person's own connector ids, and its `owner` is their Workspace address; it is used only in a one-on-one with that person. Never mount a second Connecta connection beside the first. The rules and an example are in the auth guide, "Organizing an agent's pools".
+
+The shipped documentation is now written first for the agent running a deployment from the installed package (#858). `documentation/README.md` has an operator task index: add or remove a connector, organize an agent's pools, add a person, connect a shared credential, issue, rotate or revoke an agent token, upgrade, and diagnose with `connecta doctor`. Each row links to a self-contained section, and the Node template and Worker example route agents through it. Existing deployments should add the pointer line from the migration guide to their own `AGENTS.md`.
+
+The operator UI is rebuilt as an admin console and a member page (#834). Maintainers land on Endpoints, which lists `/mcp` and every pool with who can use it, its tools grouped by connector and who each connector runs as. They also get Connectors with a connector × endpoint matrix, Activity, Tokens with one row per agent and in-row issue, rotate and revoke, and Settings. Old URLs redirect (`/access` to `/`, `/tools` to `/connectors`, `/config` to `/settings`). Pool members get one page with their endpoints and client setup, their own accounts to connect or disconnect, and shared connectors by name only; anyone else sees a No access page. A saved dark mode no longer flashes light on load, and private browsing no longer breaks token sign-in. The UI reads operator contract v2 from `GET /ui/api/config`, which is now the page's only gate: 401 when signed out, 404 for anyone who is neither a maintainer nor a member, and 200 with `role` otherwise. Contract v1 and its types are removed, and `/ui/data` and `/ui/connectors/<id>` are maintainer-only. The UI also recovers from transient Cloudflare Access and auth failures without a reload (#830).
+
+Security: 0.29.0 through 0.32.0 buffered an unauthenticated POST carrying `Mcp-Method: subscriptions/listen` with no size limit before authentication, so an anonymous client could exhaust memory on deployments without an edge gate such as Cloudflare Access. Every MCP endpoint now authenticates before reading any body and caps the pre-dispatch read at 64 KiB. Stripe, Vercel, Cloudflare and Notion REST responses now withhold signed URL parameters, and writes that carry the redaction placeholder are refused before sending (#812, #818).
+
+The release also fixes Notion property filtering, Gmail's charset notice under truncation, recovery of long caller idempotency keys, Cloudflare ownership lookups against call admission, and `callAdmission` values that silently disabled rate limits. Notion token connectors accept `callAdmission`, and the fake-vendor agent evaluations now run.
+
+### Added
+
+- Add the operator UI contract v2 types (`OperatorUiContractV2` and its pool, member, agent, connector and matrix types) from the pools-are-the-access-model decision, with maintainer and member fixtures; `GET /ui/api/config` serves it (see Changed).
+- **Breaking:** Pools take an optional `owner`, the Google Workspace address agents in that pool act as on a Workspace connector (`gmail()`, `drive()`, `sheets()`, `slides()`, `forms()`, `docs()`) whose `subject` is a mapping function, so one connector serves a pool per person instead of one connector per mailbox. People always act as themselves through the mapping, in any pool. An agent acts as the owner of the pool it came through, resolved before and instead of the mapping, which is never called for an agent. An agent in a pool without an owner fails `auth_required` before any request leaves, and the message names no address. A fixed `subject` address still applies to every caller, agents included, and ignores owners. Nothing in arguments, headers, or programs can choose the owner. `owner` must be a Workspace email address, checked at construction by the rule a fixed `subject` uses, and `describeConfig()` pools add `owner` (`null` when unset). `/ui/api/config` serves the address only to an authenticated maintainer; an open deployment's anonymous caller reads `null`. Breaking for agents only: people and fixed subjects behave as before. In 0.32 a `cta_` token reached the mapping function, which usually answered `undefined` for a caller with no principal (`auth_required`). Now an agent never reaches it, so a mapping that answered for machine tokens, by token subject or otherwise, no longer applies; set that address as the `owner` of the agent's pool.
+- Operator contract v2 `runsAs` for shared connectors now says where the credential lives (`vault`, `missing`, `oauth`, `config` or `unauthenticated`), so a credential supplied in deployment config, or a connector that needs none, is not shown as unsaved.
+- Activate ten deterministic agent evaluations for Stripe, Notion, Cloudflare, and Vercel REST connectors, with state, recovery, pin, paging, and value-safety graders and saved evidence for offline regrading.
+  
+  Model Stripe idempotency by account and mode, reject refused named write attempts in read-only graders, bind analytics counts to their metrics, and align environment confirmation with its prompt. Replace fixture-invalid measurements with fresh live trials.
+- Allow Notion token connectors to replace the default call-admission policy with `callAdmission`. The default remains 180 calls per minute and 3 concurrent. Malformed policies, including falsy values other than `undefined`, fail at construction for both token and OAuth connectors. Shared admission validation also rejects malformed nested budgets instead of silently disabling their limit.
+
+### Changed
+
+- Endpoints shows who can use each endpoint: `/mcp` lists its maintainers and each pool its members, people by name (or raw id) and agents as `agent:<name>`, with long lists collapsed behind "+N more". Tokens lists one row per agent declared in code with its pools, token state, date and last seen; issue, rotate and revoke keep their confirmations, a new secret appears once in a dialog, an unknown or aborted outcome is a failure notice that is never retried, and an agent missing from the live slot list cannot be acted on until a refresh lists it. Pool members get their own page with their endpoints and client setup, connect, reconnect or disconnect for their personal OAuth accounts, a credential form for personal credential slots whose Add, Replace, Test and Clear follow `manage.actions`, and the names of connectors shared with them. Every token and member action is checked again immediately before it is sent, so a slot list or contract refreshed meanwhile stops it, and a token operation with an unknown outcome disables that agent's controls until a refresh. Every token mutation, Issue included, sends the slot revision the operator confirmed against as `expect` (P3b of #837); a slot without a revision is never acted on, a contract revision that differs from the list's unresolves the slot, and a 409 `slot_changed` reads "Changed since you looked, refresh".
+- The operator UI reads operator contract v2 and refuses v1. Endpoints lists `/mcp` and every pool, with an agent URL for pools that have agent members, and each expanded row shows who every connector runs as. Connectors adds a Matrix view of connectors by endpoint, where a cell opens its exact tools. Pool members see only their endpoints and client setup, and someone who is neither a maintainer nor a member sees a No access page. A shared connector's runs-as names where its credential comes from.
+- **Breaking:** Agents move from `/mcp/<pool>` to `/agent/<pool>`. An agent endpoint admits only the built-in `cta_` adapter and a member agent of that pool, serves exactly the pool's tools with its `readOnly`, binds result handles to `/agent/<pool>`, answers a missing or invalid credential with a machine-only `WWW-Authenticate: Bearer` challenge, and publishes no protected-resource metadata. It never runs Clerk or Access and ignores cookies, Clerk handshake parameters, `ctx.access`, and Access headers. Only a raw pathname byte-equal to `/agent/` plus a pool name is an agent endpoint; every other path in the agent namespace (any case, escapes, doubled slashes, trailing slash, extra segments) is routed first and answers the pool 404 before auth, so no path Cloudflare Access bypasses as `/agent/*` reaches a human route. Breaking: `/mcp`, `/mcp/<pool>`, and the operator, connect, and callback routes refuse `cta_` tokens without reading token storage (401 on MCP and operator data routes, 403 on interactive-only routes), so point every agent at `/agent/<pool>`; `connecta doctor` checks `/agent/<pool>` for a `cta_` token and requires `--pool`, and the Node template's doctor checks `/agent/local-machine`. Deployments behind Cloudflare Access add one self-hosted Access application per agent hostname for `<host>/agent/*` with a single Bypass policy beside the Worker-level application, after which agents send only their `cta_` token (deploying guide, "Agent endpoints behind Cloudflare Access"). The `agent_not_maintainer` denial reason is removed.
+- **Breaking:** Machine clients are agents declared by name in a new top-level `agents` option, each with one `cta_` token slot that operators issue, rotate, and revoke from `/ui/access-tokens`, the operator UI, or `AccessTokenManager.rotate` and `revoke`. Rotation is an immediate cutover: the old secret refuses on its next request, and of concurrent rotations exactly one returns a secret. The agent's slot is the only authority admission consults, and each operation commits by one compare-and-set on it and only moves forward: a rotation cancelled before its commit publishes nothing, and one cancelled after it moves the slot to revoked within one deadline that bounds every storage call of the operation, the commit's acknowledgement included (otherwise it reports the outcome unknown, never success; rotate again for a replacement secret). The request path deletes nothing it did not just write: superseded records and lookups stay behind, inert, so storage grows by one small record per rotation or adoption. A token admits only while it is bound to a currently declared agent, so removing a name stops its token on the next request. Admitted agents carry `identity.agent` (set only by the built-in adapter; any other provider returning `agent` is refused), have no principal and so no personal connectors, and are attributed in activity by agent name rather than token record id. Breaking: creating, renaming, and human-bound tokens are removed from the routes, manager, and UI; tokens issued by earlier releases stop admitting until trusted provisioning adopts each machine token for an agent with `AccessTokenManager.adopt(tokenId, agent)` (Node template: `npm run adopt-token`), which keeps its secret without rewriting the legacy record and takes a never-deleted claim so a legacy token is adopted by at most one agent, once, and human-bound tokens cannot be adopted; `accessTokens(storage, { maxActive })` throws; `describeConfig()` adds `agents` and drops `modules.accessTokens.maxActive`; grant callbacks that matched token record ids should match `identity.agent`. The Node template replaces `provision-token` with `npm run rotate-token -- <agent>` and declares `local-machine`.
+- Record the decision that pools are the access model: maintainers alone use plain `/mcp`, pool members get exactly their pool's tools, agents are declared in code and reach `/agent/<pool>` with a `cta_` token, and a pool owner sets the Google Workspace account agents act as.
+- **Breaking:** Management follows `maintainers` and pool `members` (#837). Shared credentials and OAuth grants, and agent token list, issue, rotate, and revoke, take an interactive maintainer; activity reads take a maintainer principal, interactive or not, within the optional `readGate`. A personal connector's own account may be connected and disconnected, always in the caller's own partition, by an interactive maintainer or by an interactive member of a pool containing that connector, through `authorize_connector` at their pool, the `/connect` link and callback, and `/ui/oauth/<id>` and `/ui/credentials/<id>`, which now admit such a member for their pools' personal connectors. Agents and other machine credentials manage nothing. Pool members get the private 404 on activity and token routes. A `cta_` credential is refused before token storage is read: 401 on activity data routes and 403 on interactive token-management routes. Breaking: `identity.credentialAdministration`, `identity.personalConnection`, `identity.accessTokenManagement`, and `identity.activityAccess` are removed and each fails construction naming its replacement; `describeConfig()` drops `identity`; the `ConnectaIdentityConfig` and `ConnectorPermission` types are no longer exported.
+- **Breaking:** Add the 0.33 migration guide (`documentation/migration-0.33.md`), mapping every removed access option to `maintainers`, pool `members`, and `agents`, with agent endpoints, pool owners, token revisions, operator contract v2, and the 0.29.0–0.32.0 pre-auth listen fix. Add connecta's agent pool layout as a documented standard in the auth guide ("Organizing an agent's pools") and decision 0007: one Connecta connection per agent, a base pool `<agent>` with shared connectors and no `owner`, and an `<agent>-<user>` pool per person with that person's own connector ids and their Workspace address as `owner`. The Node template and Worker example agent guidance follow it. Breaking: the empty `identity` option is removed: `identity`, even `{}`, now fails construction, still naming each retired key's replacement. The Access bypass probe requires `--profile`.
+- **Breaking:** `GET /ui/api/config` serves operator contract v2 and is the operator page's only gate: 401 with the auth challenge when signed out (an agent token gets the machine-only 401 every human route gives it), the private 404 for anyone who is neither a maintainer nor a pool member, and 200 with `role` otherwise. A maintainer gets the whole view: `root` and every pool with their members and directory labels, pool owners, every declared agent with its token slot and last activity, and a connector × endpoint matrix naming who each connector runs as. A pool member gets only their own pools and connectors, with their own connection state and the actions they may take. Contract v1, `you.grants`, `you.permissions`, `hasGrant`, and the `OperatorViewer` and `OperatorPool` types are removed; `you.interactive` remains, and `OperatorUiContract` now names v2. `/ui/data` and `/ui/connectors/<id>` stay maintainer-only. `/ui/oauth/<id>` gates each verb on its own hooks: connecting needs `startAuth`, `finishAuth` and `verifyState`, and disconnecting needs only `disconnectAuth`, so a connector provisioned out of band can be disconnected. `DELETE /ui/credentials/<id>` refuses to clear an empty partition or slot with 409 `credential_required`. `connecta doctor --config` reads v2 and refuses a member's view.
+- **Breaking:** Pools are the access model (decision 0006). A new top-level `maintainers` list names the people who reach plain `/mcp`, which serves the whole catalog with the deployment `readOnly`, and the operator routes that administer the deployment (catalog, activity, shared connector auth, access tokens); it is required whenever an inbound provider other than the built-in agent-token adapter is configured. Each pool now requires a non-empty static `members` list and serves exactly its `tools` to those members, with no intersection against anything else. A reference is a bare principal id resolved in the namespace of the deployment's one interactive provider, `{ namespace, id }`, or `"agent:<name>"` for a declared agent; ambiguous, unknown, repeated, or misplaced references (an agent in `maintainers`) fail construction. A non-maintainer at `/mcp`, a non-member, and an undeclared pool get the identical 404 after auth, logged as `not_maintainer`, `not_pool_member`, or `pool_not_declared`; result handles stay bound to their endpoint and paging re-admits the caller. A pool member may connect their own personal connector in that pool through `/connect/<id>`, which starts directly for non-maintainers. Shared connector auth (issuing a link, starting, completing the callback, disconnecting, and writing a credential) requires a maintainer. Breaking: `identity.connectorAccess` (with its guarded `{ tool, requireReadOnly: true }` grants; use a `readOnly: true` pool), the top-level `grant` (use `maintainers`), and pool `grant` (use `members`) are removed and fail construction naming their replacement; `describeConfig()` drops `hasGrant` at the root and on pools and `identity.connectorAccess`, and adds `maintainers` and pool `members`; anyone neither a maintainer nor a pool member gets the private 404 on operator routes, and the member access the management and operator contract entries describe is all a member gets there. Agent members reach their pools at `/agent/<pool>` (agent endpoints entry) and are refused at plain `/mcp`; `connecta doctor --pool <name>` checks a pool, and the Node template (`CONNECTA_MAINTAINERS`, a `local-machine` pool for the `local-machine` agent, `npm run doctor`) and Worker example (`CONNECTA_MAINTAINERS`, a `ci` pool for the `ci` agent) are updated accordingly.
+- **Breaking:** Agent token slots carry an opaque `revision` that changes on every commit to the slot (issue, rotate, revoke, adopt). `GET /ui/access-tokens`, the slot each mutation returns, and operator contract v2's `OperatorAgent.token` list it. Breaking: `POST` (issue or rotate) and `DELETE` (revoke) `/ui/access-tokens/<agent>` now require `{ "expect": "<revision>" }` as a JSON body (`DELETE` also takes `?expect=<revision>`); a missing or malformed `expect` is 400, and a slot whose revision differs is 409 `{ error, code: "slot_changed" }` before anything is minted or written. The slot's compare-and-set commits only from the slot with that revision, so a change landing between the read and the commit refuses the same way instead of being overwritten or revoked. `AccessTokenManager.rotate`, `revoke`, and `adopt` take the same optional `expect`; without it they behave as before. Each revocation stores a random, non-secret `revocationId`, so no two revocations store the same slot and a call recognizes only its own: of two conditional revocations of one slot, exactly one succeeds and the other is 409 `slot_changed`.
+- Make the shipped documentation an operator entry point with self-contained connector, people, credential, token, pool, upgrade, and diagnosis procedures, and separate contributor references.
+- Record a production Cloudflare probe showing that a path-scoped Access Bypass application for `<host>/agent/*` overrides a Worker-level Access application on that path only, with the edge's path matching and the pathnames the Worker receives, so `/agent/<pool>` can carry a single `cta_` credential behind Access.
+- Rework the operator dashboard around Endpoints, Connectors, Activity, Tokens and Settings with a top bar, light and dark Geist typography, expandable endpoint tool lists, three connector tabs and catalog search. Preserve legacy links and existing permission gates.
+
+### Fixed
+
+- Operator pages apply a saved color scheme before first paint, through a small blocking hashed initializer, so a viewer who saved dark mode on a light system no longer sees a light frame. A deployment's pinned scheme still wins. Operator pages also load when browser storage throws, as in private browsing; a bearer token is then not remembered.
+- Charge Cloudflare zone-ownership lookups for account pin enforcement to the
+  connector's shared call-admission budget. An exhausted budget refuses the lookup
+  and enclosing call before sending the lookup or target request. Keep the separate
+  limits of three ownership lookups per call and 60 per five minutes per connector.
+- Keep Gmail's unsupported-charset UTF-8 fallback notice in a separate `bodyNote` field on message, thread, and draft reads so body truncation cannot remove it.
+- Give load-sensitive test setup, static scans and child processes explicit deadline headroom while preserving correctness, CPU budget and heartbeat assertions.
+- Send selected properties to Notion as repeated `filter_properties` URL parameters for named page reads and data source queries, reducing response size while preserving the projected page title. Page reads whose deduplicated selection plus title exceeds Notion's 100-filter limit fetch all properties and project locally instead.
+- Review 22 additional Notion hosted MCP tools from a live catalog, preserving write enforcement for mutations and documenting signed download and upload credentials.
+- Recover operator pages from transient Cloudflare Access and auth-state failures without reloading. Distinguish unavailable identity lookups from rejected identities, prevent caching refusals, reconcile catalog and auth refreshes, scope and cancel bounded OAuth status polling, prevent queued focus recovery after sign-out, preserve shared passive retry throttling and backoff across Access refusals, coalesce passive returns through slow catalog/auth recovery with a 15-second admission deadline that releases Retry without aborting healthy pending reads, and show unreadable credentials as unavailable.
+- Preserve caller-supplied REST idempotency keys up to the schema's 255-character limit in `uncertainCall.recovery` after an ambiguous write. Versions 0.31.0 through 0.32.0 echoed caller-supplied keys only up to 128 characters. Other recovery values retain their 128-character cap, and keys longer than 255 characters are still rejected before dispatch.
+- Refuse malformed `callAdmission` policies at construction across connector and maintained provider factories, including custom connectors registered by a deployment. Only omission or `undefined` selects the documented default; `false`, `null`, `0`, and `""` no longer silently disable admission or select a default.
+
+### Security
+
+- Affected versions: 0.29.0–0.32.0. An unauthenticated POST with `Mcp-Method: subscriptions/listen` to `/mcp` or `/mcp/<pool>` was buffered with no byte cap before authentication and request admission, so an anonymous client could hold unbounded memory per request without taking an admission permit. Every MCP endpoint (`/mcp`, `/mcp/<pool>`, and `/agent/<pool>`) now authenticates first, and endpoint admission follows, before any body is read. Every pre-dispatch body read is bounded: classification reads at most 64 KiB, and past that connecta answers 413 with JSON-RPC code `-33006` and stops reading. A confirmed modern listen still takes no permit and is refused as unsupported; any other body carrying that header takes a permit before dispatch.
+- Withhold the whole query and fragment of canonical Notion file links embedded in every REST response and error string, including Markdown and async results. Match only each URL's actual authority, preserving external proxies and look-alike hosts with ordinary parameters; AWS and Google signing parameter values are still withheld at any host. Refuse writes carrying the exact plain or encoded `[redacted]` placeholder in a Notion file link's own query or fragment before dispatch. Admission checks every adjacent Markdown destination, recognizes leading spaces, tabs, or one line ending, and respects balanced or escaped parentheses. Both scans stay linear. Split rich-text runs, encoded hosts or signing names, bare hosts without `//`, and userinfo before a file host are outside this scan's threat model.
+- Withhold AWS SigV4/Google V4 signing-parameter values in every decoded Stripe, Vercel, and Cloudflare REST string, and generic credential-named URL queries/fragments only on reviewed diagnostic paths and vendor error text. Preserve ordinary code/key/token URLs in customer descriptions, metadata, billing text, DNS TXT, KV values and operator HTML. Refuse withheld URL destinations before every supported write transport, including decoded raw/base64 and multipart uploads, documented base64 JSON fields, and JSON object keys; scan every JSON key and value iteratively within the host's request-size limit without separate depth/breadth ceilings. Decode documented base64 fields once within their encoded length, retaining Cloudflare KV's 25 MiB value limit instead of applying the response cap. Cover indexed Vercel deployment lists and Cloudflare telemetry source payloads and invocation maps, with a pinned-operation guard for embedded-URL rules. Scan original escaped text and relative Markdown destinations before projections. Binary/base64 response bodies remain unchanged; Cloudflare omits envelope cursors that sanitizing would change. Notion retains its reviewed file-host and write-admission policy.
+
 ## 0.32.0 — 2026-10-14
 
 Connecta 0.32.0 makes each endpoint simply writable or read-only, and lets a deployment keep chosen callers, such as an agent's token, off plain `/mcp` (#820, #821). A deployment can then give an agent one token and per-person pools, and the agent sees only the pool its client picks for each turn.

package/README.md

@@ -31,8 +31,10 @@ flowchart LR
     style Connecta fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:2px
 ```
 
-You choose which services to connect and who can use them. Your agent keeps
-the same connection as those services change.
+You choose which services to connect and who can use them: the maintainers
+you name reach everything, and everyone else, people and agents alike, reaches
+only the pools of tools you list them in. Your agent keeps the same connection
+as those services change.
 
 ## From a question to an answer
 
@@ -114,16 +116,22 @@ deployment owner. Permission to use a connection is separate from permission
 to manage its credentials.
 
 People sign in through Clerk on Node or Cloudflare Access on Workers. Machine
-clients use tokens issued by your Connecta deployment. A deployment can serve
-several people within one tenant, each with the access you assign.
+clients are agents you name in deployment code, each with one token issued by
+your Connecta deployment. Agents connect through their own address for each
+pool, separate from the one people use, so an agent sends only its token, even
+behind Cloudflare Access. A deployment can serve
+several people within one tenant, each with the access you assign. An agent
+that serves several people keeps one connection and switches pools per turn:
+a shared pool for group chats and scheduled work, and a pool per person, with
+that person's own accounts, used only when that person is the one talking.
 
 ## A place to see your connections
 
 The optional operator UI shows connected services, available tools, access,
-and configuration. Authorized people can connect accounts, manage credentials,
-and issue client tokens. Optional activity history shows who called what,
+and configuration. Maintainers manage shared credentials, issue or rotate agent
+tokens, and read the optional activity history, which shows who called what,
 when, and whether it worked, without recording arguments, results, or program
-code. The UI's controls follow the signed-in person's permissions.
+code. Pool members connect their own accounts on personal connections.
 
 Your agent or developer changes the integrations and access rules in deployment
 code. The UI helps you inspect them and manage authentication.

package/bin/connecta.mjs

@@ -20,7 +20,7 @@ function usage() {
   console.log(`Usage:
   connecta init [directory]
   connecta migrate-state <state.json> <connecta.sqlite>
-  CONNECTA_TOKEN=<bearer> connecta doctor [--config] [--url http://localhost:8787]
+  CONNECTA_TOKEN=<bearer> connecta doctor [--config] [--url http://localhost:8787] [--pool <name>]
   CF_ACCESS_CLIENT_ID=<id> CF_ACCESS_CLIENT_SECRET=<secret> connecta doctor --url https://worker.example`);
 }
 
@@ -78,7 +78,8 @@ async function init() {
   console.log(`  ${shellCd(target)}`);
   console.log("  npm install");
   console.log("  # Choose readOnly in src/connecta.config.ts: false writes with client approval, true refuses writes.");
-  console.log('  npm run --silent provision-token -- "local-machine"');
+  console.log("  # Declare each machine client in agents in src/connecta.config.ts; local-machine is the first.");
+  console.log("  npm run --silent rotate-token -- local-machine");
   console.log("  # Save the returned cta_ token privately for your MCP client and doctor.");
   console.log("  npm start");
   console.log("  # README.md covers database paths and Docker provisioning.");
@@ -137,13 +138,19 @@ async function doctorFetch(url, init = {}) {
 async function doctor() {
   for (let index = 0; index < args.length; index++) {
     if (args[index] === "--config") continue;
-    if (args[index] !== "--url" || !args[++index] || args[index].startsWith("--")) {
+    if (!["--url", "--pool"].includes(args[index]) || !args[++index] || args[index].startsWith("--")) {
       usage();
       process.exitCode = 1;
       return;
     }
   }
   const requestedUrl = option("--url", "http://localhost:8787");
+  // An agent token reaches only /agent/<pool> for the pools that list the
+  // agent; /mcp and /mcp/<pool> admit people alone.
+  const pool = option("--pool", undefined);
+  if (pool !== undefined && !/^[a-z0-9_-]+$/.test(pool)) {
+    throw new Error("Doctor --pool must be a pool name: lowercase letters, digits, _ and -.");
+  }
   const parsedUrl = new URL(requestedUrl);
   if (parsedUrl.username || parsedUrl.password) {
     throw new Error("Doctor URL must not contain credentials.");
@@ -167,6 +174,10 @@ async function doctor() {
       "Set CONNECTA_TOKEN or a CF_ACCESS_CLIENT_ID/CF_ACCESS_CLIENT_SECRET pair so doctor can inspect the MCP surface.",
     );
   }
+  const agent = Boolean(token?.startsWith("cta_"));
+  if (agent && pool === undefined && !args.includes("--config")) {
+    throw new Error("An agent token reaches only /agent/<pool>: pass --pool with a pool that lists the agent.");
+  }
   const authHeaders = {
     ...(token ? { Authorization: `Bearer ${token}` } : {}),
     ...(accessClientId && accessClientSecret
@@ -189,7 +200,12 @@ async function doctor() {
     } catch {
       throw new Error("Deployment returned an invalid config contract.");
     }
-    if (contract?.schemaVersion !== 1 || contract.config?.schemaVersion !== 1) {
+    // Operator contract v2 (#837) serves a pool member their own view, which
+    // carries no config; only a maintainer's carries the snapshot.
+    if (contract?.schemaVersion === 2 && contract.role === "member") {
+      throw new Error("The config snapshot is for maintainers only.");
+    }
+    if (contract?.schemaVersion !== 2 || contract.role !== "maintainer" || contract.config?.schemaVersion !== 1) {
       throw new Error("Deployment returned an unsupported config contract.");
     }
     // The server builds this with describeConfig's allowlist; do not print
@@ -221,8 +237,10 @@ async function doctor() {
     { name: "connecta-doctor", version: CONNECTA_VERSION },
     { versionNegotiation: { mode: "auto", probe: { timeoutMs: DOCTOR_TIMEOUT_MS } } },
   );
-  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/mcp`), {
-    requestInit: { headers: authHeaders },
+  // Agent endpoints bypass Access at the edge and read only the cta_ token.
+  const endpoint = agent ? `/agent/${pool}` : `/mcp${pool ? `/${pool}` : ""}`;
+  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}${endpoint}`), {
+    requestInit: { headers: agent ? { Authorization: `Bearer ${token}` } : authHeaders },
     fetch: doctorFetch,
   });
   let negotiatedVersion;

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.32.0";
+export const CONNECTA_VERSION = "0.33.0";

package/dist/access-tokens.d.ts

@@ -1,38 +1,182 @@
-import type { IdentityReference, InboundAuth, KVStorage } from "./types.js";
+import type { InboundAuth, KVStorage } from "./types.js";
 import type { AccessTokensModule } from "./module-contracts.js";
-export interface AccessTokenMetadata {
-    id: string;
+/**
+ * One declared agent's token slot as management sees it. Never secret
+ * material. `revision` is opaque: it changes on every commit to the slot and
+ * is what `expect` names to make an operation conditional on this view.
+ */
+export type AgentTokenSlot = {
     name: string;
-    tokenPrefix: string;
-    createdAt: string;
-    revokedAt?: string;
-}
-export interface CreatedAccessToken {
+    state: "none";
+    revision: string;
+} | {
+    name: string;
+    state: "issued";
+    issuedAt: string;
+    revision: string;
+} | {
+    name: string;
+    state: "revoked";
+    revokedAt: string;
+    revision: string;
+};
+/** A newly issued secret, returned once, and the slot that now admits it. */
+export interface IssuedAgentToken {
     token: string;
-    accessToken: AccessTokenMetadata;
+    agent: AgentTokenSlot;
 }
+/** Why a token operation was refused, for routes and provisioning scripts. */
+export declare class AccessTokenError extends Error {
+    readonly code: "unknown_agent" | "conflict" | "slot_changed" | "not_adoptable" | "aborted" | "outcome_unknown";
+    readonly name = "AccessTokenError";
+    constructor(code: "unknown_agent" | "conflict" | "slot_changed" | "not_adoptable" | "aborted" | "outcome_unknown", message: string);
+}
+/** Options every token mutation takes. */
+export interface AccessTokenOperationOptions {
+    /**
+     * The request this operation serves. Checked before the commit point, the
+     * slot's compare-and-set: an abort before it publishes nothing. An abort
+     * after a rotation commits revokes the slot, since the secret cannot be
+     * delivered.
+     */
+    signal?: AbortSignal;
+    /**
+     * The request's own deadline, in epoch milliseconds, when it has one. The
+     * operation ends at the earlier of this and `OPERATION_WINDOW_MS` after it
+     * starts.
+     */
+    deadline?: number;
+    /**
+     * The slot `revision` the caller decided from. When set, the operation
+     * refuses with `slot_changed` before minting or writing anything if the
+     * slot's current revision differs, and its commit compare-and-sets from
+     * exactly the slot with that revision, so a change that lands between the
+     * read and the commit refuses the same way instead of being overwritten.
+     */
+    expect?: string;
+}
+/** Whether `value` has the shape of a slot revision. */
+export declare function isSlotRevision(value: unknown): value is string;
 /**
- * Deployment-scoped personal access tokens. Secret material is never
+ * Agent tokens: one slot per agent declared in code. Secret material is never
  * recoverable: authentication indexes a SHA-256 digest of a random 256-bit
- * token, while separately enumerable metadata powers operator management.
+ * token, and only that digest persists. A token admits only while its record
+ * is bound to a currently declared agent and that agent's slot names it.
  */
 export declare class AccessTokenManager {
     private readonly storage;
     readonly auth: InboundAuth;
-    private readonly maxActive;
+    private readonly agents;
+    private readonly agentOrder;
     constructor(storage: KVStorage, options?: {
-        maxActive?: number;
+        agents?: readonly string[];
     });
+    private declared;
     private read;
-    list(): Promise<AccessTokenMetadata[]>;
-    create(name: unknown, createdBy: string | IdentityReference): Promise<CreatedAccessToken>;
-    rename(id: string, name: unknown): Promise<AccessTokenMetadata | null>;
-    revoke(id: string, revokedBy: string): Promise<AccessTokenMetadata | null>;
-    private updateRecord;
-    private updateActive;
+    private readSlot;
+    /** One slot per declared agent, in declaration order. */
+    list(): Promise<AgentTokenSlot[]>;
+    /**
+     * Issue the agent's first token, or replace its current one.
+     *
+     * 1. The slot is read. With `expect`, a slot whose revision differs refuses
+     *    with `slot_changed` before any secret is minted.
+     * 2. The new record and its lookup are written. They are inert: admission
+     *    requires the slot to name the record.
+     * 3. `signal` is checked.
+     * 4. One compare-and-set of the slot, from exactly what was read to
+     *    `issued` with the new record, is the only commit point. From it the
+     *    new secret admits and the previous one refuses. Of concurrent
+     *    rotations exactly one commits; the others publish nothing and refuse
+     *    with `slot_changed` when they named `expect`, a conflict otherwise.
+     * 5. If the request has ended once the commit is decided, the secret cannot
+     *    be delivered, so the slot moves forward to `revoked`. Everything after
+     *    the commit runs inside one `OperationWindow`; if it cannot settle in
+     *    time this rejects with `outcome_unknown` ("rotate again"), never success.
+     *
+     * Nothing is ever deleted except this call's own record and lookup, while
+     * they are known to be uncommitted. The previous record and lookup stay
+     * behind, inert, because the slot no longer names them.
+     */
+    rotate(name: string, issuedBy?: string, options?: AccessTokenOperationOptions): Promise<IssuedAgentToken>;
+    /** Whether the agent's slot names `tokenId`, read back inside the window. */
+    private slotNames;
+    /**
+     * Move the slot forward to `revoked` if it still names `tokenId`, inside the
+     * window. An unsettled outcome is reported, never swallowed.
+     */
+    private revokeIfNamed;
+    /**
+     * Revoke the agent's token. One compare-and-set of the slot to `revoked` is
+     * the commit; `signal` is checked after the read and before it. The record
+     * and lookup stay behind, inert. With `expect`, a slot whose revision
+     * differs refuses with `slot_changed` before anything is written, and so
+     * does a slot that changes between the read and the commit; without it,
+     * whatever the slot names by then is revoked instead.
+     */
+    revoke(name: string, options?: AccessTokenOperationOptions): Promise<AgentTokenSlot>;
+    /**
+     * Settle a conditional revocation whose commit went unanswered, inside the
+     * window. Only a slot carrying this call's own `revocationId` is its
+     * success. A slot still as read is revoked again from exactly that slot,
+     * with the same id; anything else is `slot_changed`.
+     */
+    private settleRevocation;
+    /**
+     * Trusted provisioning: let a declared agent keep using a machine token
+     * issued before agents. The legacy record is never changed.
+     *
+     * 1. A write-once claim, `access-token:v1:adopted:<legacy id>`, is set from
+     *    absent to the agent's name. It is never deleted: once any adoption has
+     *    started, the legacy token belongs to that agent forever, even after it
+     *    is revoked or rotated away, so a retired secret can never be adopted
+     *    again. It is inert to admission; an abort after it leaves the token
+     *    adoptable only by the same agent.
+     * 2. A new record carrying `agent` and the legacy digest is written; it is
+     *    inert until the slot names it.
+     * 3. `signal` is checked.
+     * 4. One compare-and-set of the slot from none to `issued` with the new
+     *    record is the commit. Adopt delivers no secret, so once committed it is
+     *    completed even if the request ended.
+     * 5. The digest's lookup is moved from the legacy record to the new one by
+     *    compare-and-set; from then the existing secret admits as the agent.
+     *
+     * The commit and everything after it run inside one `OperationWindow`.
+     * Retrying an adoption whose slot already names a record with this digest
+     * completes step 5 and succeeds. With `expect`, a slot whose revision
+     * differs refuses with `slot_changed` before the claim, and so does a
+     * commit that loses its compare-and-set. Human-bound, revoked, and claimed tokens are
+     * refused, as is an agent whose slot names anything else.
+     */
+    adopt(tokenId: string, name: string, options?: AccessTokenOperationOptions): Promise<AgentTokenSlot>;
+    /**
+     * Step 4 of adoption, idempotent and inside the window: point the digest's
+     * lookup at the record the slot names. If another agent's adoption took the
+     * lookup first, this slot can never admit, so it moves forward to `revoked`
+     * and this refuses.
+     */
+    private completeAdoption;
+    /** The declared agent whose issued slot names a record with this digest, if any, read inside the window. */
+    private agentCarrying;
+    /**
+     * Trusted provisioning: the legacy records `adopt` can take, oldest first:
+     * unbound, unrevoked, never claimed by an adoption, still the owner of their
+     * digest's lookup, and with a digest no declared agent's slot carries. Ids, names and creation times
+     * only; never secret material.
+     */
+    unboundTokens(): Promise<Array<{
+        id: string;
+        name: string;
+        createdAt: string;
+    }>>;
     private authorize;
 }
-/** Opt in using the same storage namespace that held the v0.23 records. */
-export declare function accessTokens(storage: KVStorage, options?: {
-    maxActive?: number;
-}): AccessTokensModule;
+/** accessTokens() takes no options: the agents declared in code bound its slots. */
+type AccessTokensOptions = Record<never, never>;
+/**
+ * Agent token authentication and management over the deployment's storage.
+ * Reuse the storage that held earlier tokens so their records stay readable;
+ * `createConnecta` binds the module to `agents`.
+ */
+export declare function accessTokens(storage: KVStorage, options?: AccessTokensOptions): AccessTokensModule;
+export {};