@zackbart/connecta 0.32.0 → 0.34.0

package/examples/worker/src/connecta.config.ts

@@ -4,8 +4,9 @@
  * One MCP endpoint aggregating a downstream remote MCP and an HTTP API, guarded
  * by Cloudflare Access. It needs three resources and nothing else: one D1
  * database (CONNECTA_DB) holding every piece of state, the Worker Loader
- * binding (LOADER) behind execute_code, and one secret
- * (CREDENTIAL_ENCRYPTION_KEY) sealing credentials in that database. Access
+ * binding (LOADER) behind execute_code, and two secrets: DOWNSTREAM_TOKEN for
+ * the example Notion connector and CREDENTIAL_ENCRYPTION_KEY sealing
+ * credentials in that database. Access
  * admits the request before this Worker runs and supplies trusted human
  * identity through ctx.access. Machines use stored cta_ tokens inside connecta.
  *
@@ -16,7 +17,7 @@
  *
  * Setup (this example has no package.json of its own — it self-references the
  * installed `@zackbart/connecta` package):
- *   1. `npm install` in the connecta package root (../../ from here) so the
+ *   1. `pnpm install` in the connecta repository root (../../ from here) so the
  *      package import and wrangler resolve. A copy in its own repository
  *      installs `@zackbart/connecta @cloudflare/codemode` instead. Codemode is
  *      an optional peer.
@@ -31,9 +32,15 @@
  *      Claude's https://claude.ai/api/mcp/auth_callback plus ChatGPT's
  *      https://chatgpt.com/connector_platform_oauth_redirect and
  *      https://chatgpt.com/connector/oauth/* forms (see ../AGENTS.md).
+ *      Then add one self-hosted Access application per hostname for
+ *      `<host>/agent/*` with a single Bypass policy (Everyone), so agents send
+ *      only their cta_ token (README.md § "Let agents through Access").
  *   5. Use the Workers Paid plan required by the `worker_loaders` binding.
- *   6. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
- *      lives. Point your MCP client at `<PUBLIC_URL>/mcp`.
+ *   6. List the maintainers' Access user ids (the identity's user_uuid, else
+ *      its email) in the CONNECTA_MAINTAINERS var, comma-separated.
+ *   7. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
+ *      lives. Point a maintainer's MCP client at `<PUBLIC_URL>/mcp`, and an
+ *      agent's at `<PUBLIC_URL>/agent/ci`.
  */
 import { api, defineConfig, remoteMcp } from "@zackbart/connecta";
 import { activityHistory } from "@zackbart/connecta/activity";
@@ -55,6 +62,8 @@ export interface Env {
   CREDENTIAL_ENCRYPTION_KEY?: string;
   DOWNSTREAM_TOKEN: string;
   PUBLIC_URL: string;
+  /** Comma-separated Access user ids (user_uuid, else email) of the maintainers. */
+  CONNECTA_MAINTAINERS: string;
   /** "on" switches on activity history, in CONNECTA_DB. */
   CONNECTA_ACTIVITY?: string;
   /**
@@ -77,26 +86,34 @@ export default defineConfig((env: Env) => {
     // Required adapter owns each run's handles; direct upstream construction throws.
     executor: workerExecutor({ loader: env.LOADER }),
     // Access owns edge admission and proves human identity for MCP and the
-    // operator pages. Machines need Access service headers at the edge plus a
-    // stored cta_ bearer inside connecta; a service identity alone is refused.
+    // operator pages. Agents use /agent/<pool>, which Access bypasses and
+    // connecta authenticates with the cta_ bearer alone; a service identity
+    // alone is refused everywhere.
     auth: [cloudflareAccessAuth()],
-    // Always installed over the same D1 storage. Empty storage admits no
-    // machine client; an Access-authenticated operator can provision tokens.
+    // Machine clients are agents declared here by name, each with one cta_
+    // token. A signed-in maintainer issues, rotates, and revokes it
+    // in the operator UI; removing a name stops its token on the next request.
+    agents: ["ci"],
+    // Always installed over the same D1 storage. An agent with no issued token
+    // admits nothing.
     accessTokens: accessTokens(storage),
-    // Code-owned roster. Access proves the identity; connecta derives
-    // connector visibility and management permissions from the stable id it
-    // supplies. Add `connectorAccess` and `activityAccess` to split members
-    // from operators; here every signed-in human may manage every connector
-    // and access token. Machine tokens never receive interactive authority.
-    identity: {
-      credentialAdministration: () => "all",
-      personalConnection: () => "all",
-      accessTokenManagement: () => true,
-    },
-    // Connectors that declare a `credential` slot become editable by every
-    // signed-in human who can see that connector, encrypted with this key
-    // before anything reaches D1. A saved replacement takes effect on the
-    // next call; credentials fail at use.
+    // Code-owned roster. Access proves the identity; maintainers alone use
+    // plain /mcp, which serves every connector, and the operator UI, where they
+    // administer shared credentials, manage agent tokens, and read activity.
+    // Startup refuses an empty list.
+    maintainers: env.CONNECTA_MAINTAINERS.split(",")
+      .map((id) => id.trim())
+      .filter(Boolean),
+    // Everyone else uses a pool that lists them, which serves exactly its
+    // tools: people at /mcp/<name>, agents at /agent/<name>. Members are
+    // Access user ids or "agent:<name>". The starter pool is the agent's base
+    // pool (shared connectors, no owner), named after the agent as the agent
+    // pool layout requires.
+    pools: { ci: { tools: ["echo"], members: ["agent:ci"] } },
+    // Connectors that declare a `credential` slot become editable by a
+    // maintainer (shared) or by the member it belongs to (personal),
+    // encrypted with this key before anything reaches D1. A saved replacement
+    // takes effect on the next call; credentials fail at use.
     vault: env.CREDENTIAL_ENCRYPTION_KEY ? encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY) : undefined,
     // Payload-free activity at /ui/api/activity in CONNECTA_DB. The shared
     // D1 mapping persists the build version and validated client facts, and

package/examples/worker/wrangler.jsonc

@@ -13,9 +13,12 @@
   "vars": {
     // "CONNECTA_ACTIVITY": "on",
     "PUBLIC_URL": "https://connecta.example.workers.dev",
+    // Comma-separated Access user ids (user_uuid, else email) of the
+    // maintainers. This one matches the local dev identity below.
+    "CONNECTA_MAINTAINERS": "operator@example.com",
   },
 
-  // Local-only Access identity. Remove this block to exercise the
+  // Local-only Access identity (Wrangler 4.123.0 or later). Remove this block to exercise the
   // unauthenticated path in `wrangler dev`; production identity comes from the
   // Worker-level Access application, not from this file.
   "access": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",
@@ -8,6 +8,7 @@
   "engines": {
     "node": ">=22.13.0"
   },
+  "packageManager": "pnpm@12.4.2",
   "publishConfig": {
     "access": "public"
   },
@@ -187,20 +188,20 @@
     "build:operator-ui": "node scripts/build-operator-ui.mjs",
     "check:operator-ui": "node scripts/build-operator-ui.mjs --check",
     "check:clerk-sdk": "node scripts/build-clerk-sdk.mjs --check",
-    "build": "npm run providers:generate && npm run clean && tsc -p tsconfig.build.json && node scripts/prune-declarations.mjs",
+    "build": "pnpm run providers:generate && pnpm run clean && tsc -p tsconfig.build.json && node scripts/prune-declarations.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.operator-ui.json --noEmit",
     "test": "vitest run",
     "test:browser:install": "playwright install chromium",
     "test:browser": "playwright test",
     "test:browser:snapshots": "node scripts/update-operator-snapshots.mjs",
-    "pretest:browser:snapshots": "npm run build:operator-ui",
+    "pretest:browser:snapshots": "pnpm run build:operator-ui",
     "test:node": "vitest run --project node",
     "test:workers": "vitest run --project workers",
     "check:docs": "node scripts/check-doc-links.mjs",
     "check:lint": "oxlint -D correctness --report-unused-disable-directives .",
     "check:unused": "knip --include dependencies,unlisted,exports,nsExports,types,nsTypes",
     "check:examples": "tsc -p tsconfig.template.node.json && tsc -p tsconfig.examples.worker.json",
-    "check:security": "npm audit --omit=dev --audit-level=moderate",
+    "check:security": "pnpm audit --prod --audit-level moderate",
     "check:package": "node scripts/check-package.mjs",
     "check:declarations": "node scripts/check-declarations.mjs --dist .",
     "check:bundle": "node scripts/bundle-size.mjs",
@@ -211,23 +212,23 @@
     "eval:smoke": "tsx eval/run-smoke.ts",
     "eval:perf": "tsx eval/run-perf.ts",
     "eval:report": "tsx eval/report.ts",
-    "check:core": "npm run format:check && npm run check:providers-generated && npm run check:docs && npm run check:changes && npm run check:operator-ui && npm run check:clerk-sdk && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run build && npm run check:declarations && npm run check:bundle && npm run check:examples",
+    "check:core": "pnpm run format:check && pnpm run check:providers-generated && pnpm run check:docs && pnpm run check:changes && pnpm run check:operator-ui && pnpm run check:clerk-sdk && pnpm run check:lint && pnpm run check:unused && pnpm run typecheck && pnpm run test && pnpm run build && pnpm run check:declarations && pnpm run check:bundle && pnpm run check:examples",
     "check:fast": "node scripts/check-fast.mjs",
-    "check": "npm run check:core && npm run test:browser",
-    "release:check": "npm run check && npm run check:security && npm run check:package",
-    "prepack": "npm run check",
+    "check": "pnpm run check:core && pnpm run test:browser",
+    "release:check": "pnpm run check && pnpm run check:security && pnpm run check:package",
+    "prepack": "pnpm run check",
     "check:changes": "node scripts/changelog.mjs --check && node scripts/check-node-suites.mjs && node --test scripts/changelog.test.mjs",
     "changelog:assemble": "node scripts/changelog.mjs",
     "providers:generate": "tsx scripts/generate-providers.mjs",
     "check:providers-generated": "tsx scripts/generate-providers.mjs --check",
-    "prebuild": "node scripts/generate-version.mjs && npm run build:operator-ui",
-    "pretest": "node scripts/generate-version.mjs && npm run build:operator-ui",
-    "pretest:node": "node scripts/generate-version.mjs && npm run build:operator-ui",
-    "pretest:workers": "node scripts/generate-version.mjs && npm run build:operator-ui",
-    "pretest:browser": "npm run build:operator-ui",
-    "pretypecheck": "node scripts/generate-version.mjs && npm run build:operator-ui",
-    "precheck:bundle": "npm run build:operator-ui",
-    "precheck:fast": "npm run check:operator-ui",
+    "prebuild": "node scripts/generate-version.mjs && pnpm run build:operator-ui",
+    "pretest": "node scripts/generate-version.mjs && pnpm run build:operator-ui",
+    "pretest:node": "node scripts/generate-version.mjs && pnpm run build:operator-ui",
+    "pretest:workers": "node scripts/generate-version.mjs && pnpm run build:operator-ui",
+    "pretest:browser": "pnpm run build:operator-ui",
+    "pretypecheck": "node scripts/generate-version.mjs && pnpm run build:operator-ui",
+    "precheck:bundle": "pnpm run build:operator-ui",
+    "precheck:fast": "pnpm run check:operator-ui",
     "eval:regrade": "tsx eval/regrade.ts",
     "eval:compare": "tsx eval/compare.ts",
     "format": "oxfmt --write .",
@@ -263,7 +264,8 @@
     "@cloudflare/codemode": "^0.5.0",
     "@cloudflare/vitest-pool-workers": "^0.18.8",
     "@cloudflare/workers-types": "^4.20250101.0 || ^5.0.0",
-    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/hanken-grotesk": "^5.3.0",
+    "@fontsource-variable/jetbrains-mono": "^5.3.0",
     "@playwright/test": "^1.62.0",
     "@radix-ui/react-dialog": "^1.2.0",
     "@radix-ui/react-slot": "^1.4.0",
@@ -272,7 +274,6 @@
     "@tailwindcss/oxide": "^4.3.3",
     "@tanstack/react-query": "^5.104.1",
     "@tanstack/react-router": "^1.170.41",
-    "@tanstack/react-table": "^8.21.3",
     "@types/node": "^22.0.0",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",

package/templates/node/.env.example

@@ -26,6 +26,9 @@ CONNECTA_DATABASE=
 # may write a credential; machine access tokens grant no interactive authority.
 CLERK_PUBLISHABLE_KEY=
 CLERK_SECRET_KEY=
+# Required with Clerk: comma-separated Clerk user ids of the maintainers, who
+# alone use plain /mcp and the operator UI.
+CONNECTA_MAINTAINERS=
 
 # Credential vault. Base64-encoded 32-byte AES key encrypting the values an
 # operator saves inside a connection on /. Generate one with:

package/templates/node/AGENTS.md

@@ -2,6 +2,12 @@
 
 This repository is deployment configuration, not a copy of Connecta itself.
 
+Start every operator task at
+`node_modules/@zackbart/connecta/documentation/README.md#operator-tasks`.
+That installed index routes adding/removing connectors, organizing agent pools,
+adding people, connecting shared credentials, issuing/rotating/revoking agent
+tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
+
 - Edit `src/connecta.config.ts` for connectors, authentication, storage, public
   URL, and optional modules. `src/index.ts` only starts it.
 - Keep `executor: quickJsExecutor()` for the prescribed six-tool code-first
@@ -19,15 +25,36 @@ This repository is deployment configuration, not a copy of Connecta itself.
 - Prefer `api()` when the agent must see an exact reviewed capability surface;
   `remoteMcp()` follows the downstream server's evolving tool catalog.
 - Optional modules (Clerk sign-in, credential vault, activity history) are type-checked code in `src/connecta.config.ts`, switched on by
-  their environment variables. Follow README "Select optional modules". Auth management requires explicit
-  `credentialAdministration` or `personalConnection` permissions; visibility
-  alone never grants it. Clerk supplies human identity; `cta_` access tokens cover machine clients.
+  their environment variables. Follow README "Select optional modules". Shared auth management
+  requires a signed-in maintainer, and a pool member manages only their own
+  account on a personal connector in their pools; visibility alone never grants it. Clerk supplies human identity; machine clients are the
+  `agents` declared by name in `src/connecta.config.ts`, each with one `cta_` token.
   Keep `accessTokens(storage)` installed even before the first token exists.
-  Bootstrap machines with `npm run provision-token -- "machine-name"` against
-  the same database the server uses. `CONNECTA_TOKEN` is only for clients and
-  doctor; never add a configured static bearer or an open startup mode.
+  Issue or rotate an agent's token with `npm run --silent rotate-token -- <agent>`
+  against the same configuration and database the server uses; bind a token
+  from before agents once with `npm run adopt-token -- <token-id> <agent>`.
+  Plain `/mcp` serves `maintainers` only; other people reach `/mcp/<pool>` and
+  agents `/agent/<pool>` for a pool listing them in `members` (`npm run doctor`
+  checks `/agent/local-machine`). Human endpoints refuse `cta_` tokens. `CONNECTA_TOKEN` is only for clients and doctor; never add a configured
+  static bearer or an open startup mode.
   All state, activity included, lives in the one SQLite file `CONNECTA_DATABASE`
   names, through `@zackbart/connecta/sqlite`.
+- Organize agent pools by connecta's agent pool layout:
+  `node_modules/@zackbart/connecta/documentation/auth.md#organizing-an-agents-pools`
+  ([online](https://github.com/zackbart/connecta/blob/main/documentation/auth.md#organizing-an-agents-pools)).
+  Each agent keeps one Connecta connection whose harness, never the model,
+  picks the pool per turn. Tiers are nested pools of shared connectors with
+  no `owner`, each spreading the tool list below. Recommended names are
+  `<agent>` for the lowest and `<agent>-<tier>` above it; any named pool,
+  including an existing `team` or `leadership` pool, may be a tier if all its
+  human members are cleared for it. A chat gets the most capable tier everyone
+  present is cleared for, and the lowest when anyone present is unknown.
+  `<agent>-<user>` (that user's highest tier plus their own connector ids,
+  `owner` set to their Workspace address) is used only in a one-on-one with
+  that user. List only cleared people in a tier, and never another person in
+  a `<agent>-<user>` pool: its per-user connectors act as that user for every
+  member. Never add a second Connecta connection or mount downstream tools
+  directly.
 - Brand the operator UI in `operatorUi({ branding })`: product and owner names,
   description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
   `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand

package/templates/node/Dockerfile

@@ -2,8 +2,8 @@
 # image installs @zackbart/connecta from the registry exactly like any other
 # consumer, so nothing here depends on the Connecta repository.
 #
-# Provision a stored machine token on the volume first; README.md gives the
-# exact build, provisioning, and startup commands. Empty storage is fail-closed.
+# Issue a declared agent's token on the volume first; README.md gives the
+# exact build, rotation, and startup commands. Empty storage is fail-closed.
 FROM node:22-slim
 
 WORKDIR /app

package/templates/node/README.md

@@ -8,11 +8,12 @@ maintenance. This README and [local agent instructions](./AGENTS.md) own the
 runnable steps for a copied Node deployment.
 
 This is the prescribed Node deployment. It runs locally from source and as
-a container. Install, provision a machine token, then start it:
+a container. Install, issue the declared `local-machine` agent's token, then
+start it:
 
 ```sh
 npm install
-npm run --silent provision-token -- "local-machine"
+npm run --silent rotate-token -- local-machine
 # Save the returned cta_ token privately. It is shown only once.
 npm start
 ```
@@ -24,39 +25,59 @@ warning, and npm 12 does not block the script. A later esbuild version needs a
 new explicit review and approval; do not replace the pinned entry with a broad
 package-name approval.
 
-Point an MCP client at `http://localhost:8787/mcp` with
-`Authorization: Bearer <returned-cta-token>`. `CONNECTA_TOKEN` is a client and
+Point an agent's MCP client at `http://localhost:8787/agent/local-machine`, the agent
+endpoint of the pool that lists `agent:local-machine`, with
+`Authorization: Bearer <returned-cta-token>`. Agents use only `/agent/<pool>`:
+`/mcp` and `/mcp/<pool>` are for people and refuse `cta_` tokens, and plain
+`/mcp` serves only the `maintainers`. `CONNECTA_TOKEN` is a client and
 doctor variable only. Setting it never configures server authentication.
 
-`accessTokens(storage)` is always installed. With no stored tokens and no
-Clerk keys, the server can start and answer `/health`, but every MCP request
-is refused. There is no open startup or configured static bearer fallback.
+`accessTokens(storage)` is always installed. With no issued agent token and
+no Clerk keys, the server can start and answer `/health`, but every MCP
+request is refused. There is no open startup or configured static bearer
+fallback.
 
-## Provision machine tokens
+## Agent tokens
 
-Run `npm run --silent provision-token -- "machine-name"` from this project
-on a trusted machine. `src/provision-token.ts` imports the installed package's
-`AccessTokenManager`, then calls `manager.create(name, "local-provisioning")`
-on `sqliteStorage(openSqlite(process.env.CONNECTA_DATABASE || "./.connecta.sqlite"))`.
-The server uses that same database path. If you override it, use the same
-`CONNECTA_DATABASE` for provisioning and startup:
+Machine clients are agents, declared by name in `agents` in
+`src/connecta.config.ts`; the template declares `local-machine`. Each agent
+has one token. Run `npm run --silent rotate-token -- <agent>` from this
+project on a trusted machine to issue it, or to rotate it: the previous secret
+stops working on its next request. `src/rotate-token.ts` loads the same
+configuration the server does, so it uses the same database and refuses an
+agent the configuration does not declare. If you override the database path,
+use the same `CONNECTA_DATABASE` for rotation and startup:
 
 ```sh
 export CONNECTA_DATABASE=/absolute/path/connecta.sqlite
-npm run --silent provision-token -- "build-agent"
+npm run --silent rotate-token -- local-machine
 npm start
 ```
 
 The local commands read the process environment; they do not load `.env`.
+To run them with the values in `.env`, export it into the shell first:
+`set -a; . ./.env; set +a`.
 Compose reads `.env` for the container commands below. Keep the returned
-secret in a client secret store and out of source control and logs. Each run
-creates a new token; it cannot recover an old secret. Only the hash persists.
-The token is unbound to a human principal and has no interactive management
-authority. Its name is a label, and deployment identity and pool rules decide
-its access on every request. To revoke it locally, use `manager.list()` to
-find its id, then `manager.revoke(id, "local-provisioning")` against that same
-storage. An explicitly permitted Clerk operator can also manage tokens.
-Never expose this provisioning script as an HTTP route or run it at startup.
+secret in a client secret store and out of source control and logs. A
+rotation cannot recover an old secret; only the hash persists. An agent has no
+human principal, no personal connectors, and no interactive management
+authority; deployment identity and pool rules decide its access on every
+request through `identity.agent`. To stop an agent, remove its name from
+`agents` and restart, or revoke its token with
+`new AccessTokenManager(storage, { agents }).revoke(name)` against the same
+storage. An explicitly permitted Clerk operator can also issue, rotate, and
+revoke from the operator UI. Never expose these scripts as an HTTP route or
+run them at startup.
+
+### Tokens issued before agents
+
+Tokens from earlier releases stay in storage but stop admitting until they are
+bound to an agent. Declare the agent, then run `npm run adopt-token` with no
+arguments to list the machine tokens that can be bound, and
+`npm run adopt-token -- <token-id> <agent>` to bind one, so that machine's
+existing secret keeps working. A token binds once, and only to an agent whose
+token was never issued. Human-bound tokens issued from the operator UI cannot
+be adopted and stay refused; issue the agent a new token instead.
 
 ## Run it in Docker
 
@@ -66,12 +87,12 @@ Same source, same configuration, one long-lived service:
 cp .env.example .env
 # edit .env for the database path and any optional modules
 docker compose build
-docker compose run --rm --no-deps connecta npm run --silent provision-token -- "container-machine"
+docker compose run --rm --no-deps connecta npm run --silent rotate-token -- local-machine
 # Save the returned cta_ token privately for clients and doctor.
 docker compose up -d
 ```
 
-The provisioning container writes through the installed package API into the
+The rotation container writes through the installed package API into the
 same named volume and `CONNECTA_DATABASE` as the service. An empty volume
 admits no machine client. Compose never passes `CONNECTA_TOKEN` to the server;
 no environment value can substitute for a stored token.
@@ -99,9 +120,9 @@ server, then copy the old file into the database once, before the first start:
 npx connecta migrate-state .connecta-state.json .connecta.sqlite
 ```
 
-In the container, run it against the volume, e.g. `docker compose run --rm
-connecta npx connecta migrate-state /data/connecta-state.json
-/data/connecta.sqlite`. It copies every live entry with its expiry, keeps any
+In the container, mount the old file and import it into the volume:
+`docker compose run --rm -v "$PWD/.connecta-state.json:/import/state.json:ro"
+connecta npx connecta migrate-state /import/state.json /data/connecta.sqlite`. It copies every live entry with its expiry, keeps any
 key the database already holds, and never changes the old file; delete that
 once the deployment is verified. The 0.28 activity log
 (`.connecta-activity.jsonl`) is not imported; history starts fresh.
@@ -120,9 +141,9 @@ off. `.env.example` lists each one, and `npm run typecheck` checks every module
 whether or not it is switched on.
 
 The template explicitly enables `ui: operatorUi()` from
-`@zackbart/connecta/ui`. Open `http://localhost:8787/` and supply a
-stored machine token to inspect Connections. Sign in with Clerk for human
-connection management. Omit that option and import for an API-only
+`@zackbart/connecta/ui`. Open `http://localhost:8787/` and sign in with
+Clerk as a maintainer to inspect Connections and manage connections. Agent
+`cta_` tokens are refused by every human route, the operator UI included. Omit that option and import for an API-only
 server. OAuth callbacks remain in core even with no UI.
 
 The page labels each tool as a read or write and each endpoint as writable or
@@ -144,7 +165,10 @@ Connection management needs an interactive identity. A machine access token
 never authorizes browser credential mutations. `@clerk/backend`
 ships as a dependency of this template. To enable Clerk, set both
 `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` (one without the other refuses to
-start) and set `PUBLIC_URL`.
+start), set `PUBLIC_URL`, and list your Clerk user id in `CONNECTA_MAINTAINERS`
+(comma-separated; startup refuses Clerk without a maintainer). Maintainers
+alone use plain `/mcp` and the operator UI; add other people to a pool's
+`members` in `src/connecta.config.ts`.
 Enable `aud_claim_enabled: true` in Clerk's instance OAuth application settings
 (`PATCH /v1/instance/oauth_application_settings` in Clerk's Backend API), then
 read the setting back. Both JWT and opaque OAuth tokens are supported.
@@ -164,18 +188,20 @@ audience. New DCR registrations need new entries, so prefer audience binding
 for standard host onboarding. Clerk session tokens work only on operator
 routes. [Inbound auth](https://github.com/zackbart/connecta/blob/main/documentation/auth.md#clerk-oauth-tokens-and-operator-sessions)
 explains configuration, verification, and fixed rejection reason codes.
-Machine clients use connecta-issued `cta_` access tokens
-through `accessTokens(storage)`, which `src/connecta.config.ts` configures on
-the database. Grant explicit `identity.accessTokenManagement` permissions to
-let a signed-in human mint them. Trusted local provisioning above works without
+Machine clients are the declared `agents`, each using a connecta-issued
+`cta_` token through `accessTokens(storage)`, which `src/connecta.config.ts`
+configures on the database. A signed-in maintainer issues, rotates, and
+revokes them from the operator UI. Trusted local rotation above works without
 Clerk and never requires opening the server.
 
-Set the code-owned identity resolvers deliberately. `connectorAccess` governs
-use; `credentialAdministration` permits shared-auth changes, and
-`personalConnection` permits the signed-in principal's personal-auth changes.
-Both management permissions default to none. Use `authScope: "personal"` for a
-connector where each person should connect their own downstream account.
-`activityAccess` separately selects readers of global activity.
+Set who uses what in code: `maintainers` for plain `/mcp` and the operator UI,
+and each pool's `members` for `/mcp/<pool>` (people) and `/agent/<pool>`
+(agents), which serve exactly that pool's `tools`. Agent endpoints publish no
+protected-resource metadata and accept only `cta_` tokens. Maintainers alone
+administer shared credentials and OAuth grants, manage agent tokens, and read
+activity. Use `authScope: "personal"` for a connector where each person should
+connect their own downstream account: a member connects their own account on
+the personal connectors in their pools.
 
 ### Credential vault
 
@@ -191,13 +217,13 @@ Keep this key outside the database. Losing it makes saved values unreadable;
 upgrades must reuse it. The shipped `time` connector declares no credential
 slot. Add `credential: { label: "API token" }` to an `api()` connector and read
 it through `await ctx.credential?.get()`, or use a Notion
-connector with `auth: { type: "token" }`, which declares its own slot. Authorized humans manage the slot inside that
-connection on `/`; there is no separate Credentials tab.
+connector with `auth: { type: "token" }`, which declares its own slot. Maintainers manage the slot on that
+connector's Connection tab (`/connectors/<id>`); there is no separate Credentials tab.
 
 In 0.25.0, this vault also seals downstream OAuth tokens on their first read.
 That is a one-way state migration for those tokens: rolling back to 0.24.x
 requires authorizing each OAuth connector again. See the
-[0.25.0 changelog](../../CHANGELOG.md#0250--2026-09-23) before upgrading a
+[0.25.0 changelog](https://github.com/zackbart/connecta/blob/main/CHANGELOG.md#0250--2026-09-23) before upgrading a
 deployment with existing OAuth connections.
 
 A saved replacement takes effect on the next call. Connecta tests credentials
@@ -220,7 +246,7 @@ Diagnostics are independent. Keep the default logger or provide your own;
 
 The UI displays connections and current permissions. Configuration still owns
 the connector set, tool definitions, and access rules. Access token management
-requires explicit Clerk operator permission. There is no team roster or policy editor.
+requires a signed-in Clerk maintainer. There is no team roster or policy editor.
 
 ## Deployment contract
 
@@ -249,10 +275,11 @@ from `CONNECTA_TOKEN`; it never accepts the secret as a command-line argument.
 Remote URLs must use HTTPS.
 
 A fully-wired deployment reports exactly the same line as a bare one —
-connector count, QuickJS executed, six tools, plus any catalog drift:
+connector count, the executor, the tool count, the negotiated MCP version, and
+the package version:
 
 ```text
-Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed six-tool surface.
+Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed 6-tool surface, MCP <version>, package <version>.
 ```
 
 `QuickJS` is this deployment's sandbox, reported by the deployment itself —
@@ -268,8 +295,9 @@ feature should not leave a tab behind.
 Upgrading from v0.23 does not require rotating managed `cta_…` tokens. Import
 `accessTokens` from `@zackbart/connecta/auth/access-tokens`, replace the old
 `accessTokens: true` with `accessTokens: accessTokens(storage)`, and keep the
-same persistent storage namespace and identity/tool/pool grant rules. Enable
-`identity.accessTokenManagement` only for the interactive operators who should
-manage tokens. New issuance needs storage with atomic `compareAndSet`; older
-storage adapters can still verify existing tokens. See the package's
+same persistent storage namespace. From 0.33 `maintainers` and pool `members`
+replace `identity.connectorAccess` and every `grant`, and maintainers replace
+the four `identity` management permissions; delete them and the `identity`
+section, and follow the package's `documentation/migration-0.33.md`. From 0.33 a stored token admits only once it is bound to a
+declared agent: follow "Tokens issued before agents" above. See the package's
 `documentation/auth.md` for the migration and storage requirements.

package/templates/node/docker-compose.yml

@@ -2,7 +2,7 @@
 #
 #   cp .env.example .env
 #   docker compose build
-#   docker compose run --rm --no-deps connecta npm run --silent provision-token -- "machine-name"
+#   docker compose run --rm --no-deps connecta npm run --silent rotate-token -- local-machine
 #   docker compose up -d --build
 #
 # Compose reads `.env` from this directory, so one file configures both the
@@ -16,7 +16,7 @@ services:
     ports:
       - "${PORT:-8787}:${PORT:-8787}"
     environment:
-      # accessTokens(storage) is always installed; an empty database is closed.
+      # accessTokens(storage) is always installed; an agent with no issued token is closed.
       # CONNECTA_TOKEN belongs to clients and is never configured on this server.
       PORT: ${PORT:-8787}
       # Downstream OAuth calls back to this origin. Unset is fine until this
@@ -28,6 +28,7 @@ services:
       # on when set and off when empty.
       CLERK_PUBLISHABLE_KEY: ${CLERK_PUBLISHABLE_KEY:-}
       CLERK_SECRET_KEY: ${CLERK_SECRET_KEY:-}
+      CONNECTA_MAINTAINERS: ${CONNECTA_MAINTAINERS:-}
       CONNECTA_CREDENTIAL_KEY: ${CONNECTA_CREDENTIAL_KEY:-}
       CONNECTA_ACTIVITY: ${CONNECTA_ACTIVITY:-}
     volumes:

package/templates/node/package.json

@@ -10,14 +10,15 @@
     "esbuild@0.28.2": true
   },
   "scripts": {
-    "doctor": "connecta doctor",
-    "provision-token": "tsx src/provision-token.ts",
+    "adopt-token": "tsx src/adopt-token.ts",
+    "doctor": "connecta doctor --pool local-machine",
+    "rotate-token": "tsx src/rotate-token.ts",
     "start": "tsx src/index.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.32.0",
+    "@zackbart/connecta": "0.34.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/adopt-token.ts

@@ -0,0 +1,23 @@
+/**
+ * Trusted one-time migration: bind a machine token issued before agents to a
+ * declared agent, so that machine's existing cta_ secret keeps working. Run
+ * with no arguments to list the tokens that can be adopted. A token binds
+ * once, only to an agent that has never been issued one; human-bound tokens
+ * are refused and stop admitting.
+ */
+import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
+import connectaConfig from "./connecta.config.js";
+
+const [tokenId, agent] = process.argv.slice(2);
+const { storage, agents } = connectaConfig(process.env);
+const manager = new AccessTokenManager(storage!, { agents: agents ?? [] });
+if (tokenId === undefined) {
+  for (const token of await manager.unboundTokens()) {
+    process.stdout.write(`${token.id}  ${token.createdAt}  ${token.name}\n`);
+  }
+} else if (!agent || process.argv.length !== 4) {
+  throw new Error("Usage: npm run adopt-token -- [<token-id> <agent>]");
+} else {
+  await manager.adopt(tokenId, agent);
+  process.stdout.write(`${agent} now uses token ${tokenId}\n`);
+}