@zackbart/connecta 0.33.0 → 0.34.1

package/examples/worker/README.md

@@ -11,7 +11,8 @@ A deployable Worker that aggregates a downstream remote MCP and an in-code HTTP
 API connector, guarded by Cloudflare Access. It uses three Cloudflare resources
 and nothing else: one D1 database (`CONNECTA_DB`) for every piece of state, the
 Worker Loader binding (`LOADER`) behind the six-tool surface, which requires
-the Workers Paid plan, and one secret (`CREDENTIAL_ENCRYPTION_KEY`).
+the Workers Paid plan, and two secrets: `DOWNSTREAM_TOKEN` (the example remote
+MCP connector's token) and `CREDENTIAL_ENCRYPTION_KEY` (the credential vault).
 
 This is also the **starting template for a deployment**: a real deployment
 should be its own repository that pins an exact `@zackbart/connecta` version and
@@ -46,9 +47,11 @@ This example has no `package.json` of its own — it resolves the installed
 package from the repository root.
 
 ```sh
-npm install                                    # from the package root
+pnpm install                                   # from the repository root
 
 wrangler d1 create connecta                    # paste the id into wrangler.jsonc
+# In wrangler.jsonc also set PUBLIC_URL to this Worker's URL and
+# CONNECTA_MAINTAINERS to your Access user ids (user_uuid, else email).
 
 cd examples/worker
 wrangler secret put DOWNSTREAM_TOKEN
@@ -140,7 +143,8 @@ auth. [Deploying Connecta](https://github.com/zackbart/connecta/blob/main/docume
 records the untested cases and the propagation details.
 
 The checked-in `access.dev` block gives `wrangler dev` a local operator
-identity. Remove the block to test the missing-Access refusal. It has no effect
+identity; it requires Wrangler 4.123.0 or later, and earlier versions ignore it
+with an unexpected-field warning. Remove the block to test the missing-Access refusal. It has no effect
 on a deployed Worker's production identity.
 
 ### Optional resource management with Alchemy
@@ -228,12 +232,34 @@ Access adoption or preserve production identity.
 
 ### Copied into its own repository
 
-The `npm install` above is the connecta repository's, which already has every
+The `pnpm install` above is the connecta repository's, which already has every
 dependency this file imports. A copy with its own `package.json` installs
 Connecta and the separately installed `@cloudflare/codemode` peer:
 
 ```sh
-npm install @zackbart/connecta @cloudflare/codemode
+npm install --save-exact @zackbart/connecta@<version>
+npm install @cloudflare/codemode
+npm install --save-dev wrangler @cloudflare/workers-types typescript @types/node
+```
+
+A `tsconfig.json` like the following lets `tsc --noEmit` resolve `D1Database`,
+`WorkerLoader`, and `ExecutionContext`. `wrangler` also serves
+`scripts/copy-kv-to-d1.mjs`.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types", "node"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}
 ```
 
 `@cloudflare/codemode` is the optional peer behind `execute_code`, declared in
@@ -250,12 +276,12 @@ Then list the maintainers' Access user ids (`user_uuid`, else email) in the
 `CONNECTA_MAINTAINERS` var and point a maintainer's MCP client at
 `<PUBLIC_URL>/mcp`. Other people use `<PUBLIC_URL>/mcp/<pool>`, and agents
 `<PUBLIC_URL>/agent/<pool>`, for a pool that lists them in `members`. The example explicitly enables
-`ui: operatorUi()`; open `<PUBLIC_URL>/` for Connections and each connection's
-authentication controls. The page labels tool safety, offers fixed repair
+`ui: operatorUi()`; open `<PUBLIC_URL>/` for endpoints, and each connector's Connection tab
+(`/connectors/<id>`) for its authentication controls. The page labels tool safety, offers fixed repair
 prompts for classified failures, and shows client setup commands for endpoints
 the signed-in person may use. Those commands contain no token. There is no
-separate Credentials tab. The Access tokens page, listing one token slot per
-declared agent, is available to permitted interactive operators.
+separate Credentials tab. The Tokens page, listing one token slot per
+declared agent, is available to signed-in maintainers.
 
 ## Select optional modules
 
@@ -281,9 +307,9 @@ See [inbound identity](../../documentation/auth.md#principals-visibility-and-ope
 Machine clients are agents declared by name in `agents` in
 `src/connecta.config.ts`; this example declares `ci`. Each agent has one
 `cta_` token held by `accessTokens(storage)` over `CONNECTA_DB`, with no new
-binding. An agent with no issued token admits nothing. A human authenticated
-through Access can still sign in and issue the first token. Open
-`<PUBLIC_URL>/`, select Access tokens, and issue the agent's token. Save the
+binding. An agent with no issued token admits nothing. A maintainer (an Access
+identity listed in `CONNECTA_MAINTAINERS`) signs in and issues the first token.
+Open `<PUBLIC_URL>/`, select Tokens, and issue the agent's token. Save the
 returned `cta_` secret privately; it is returned once. Rotating replaces it
 immediately: the old secret stops on its next request. An agent has no human
 principal, so personal connectors are absent for it; connector and pool rules
@@ -380,7 +406,7 @@ with the `cta_` token alone:
 CF_ACCESS_CLIENT_ID='REPLACE_WITH_ACCESS_CLIENT_ID' \
 CF_ACCESS_CLIENT_SECRET='REPLACE_WITH_ACCESS_CLIENT_SECRET' \
 CONNECTA_TOKEN='cta_REPLACE_WITH_STORED_SECRET' \
-connecta doctor --url "$PUBLIC_URL" --pool ci
+npx connecta doctor --url https://connecta.example.workers.dev --pool ci
 ```
 
 Doctor reports the configured `DynamicWorkerExecutor`, not a presumed Node
@@ -439,7 +465,8 @@ CREATE TABLE IF NOT EXISTS connecta_kv (
 );
 CREATE INDEX IF NOT EXISTS connecta_kv_expiry ON connecta_kv (expires_at_ms);
 -- tool_call_activity: one row per completed call, keyset-paged on
--- (occurred_at_ms, id); see src/storage/sql.ts in the package.
+-- (occurred_at_ms, id); see
+-- https://github.com/zackbart/connecta/blob/main/src/storage/sql.ts
 ```
 
 ### Upgrading from 0.28

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.
@@ -90,7 +91,7 @@ export default defineConfig((env: Env) => {
     // alone is refused everywhere.
     auth: [cloudflareAccessAuth()],
     // Machine clients are agents declared here by name, each with one cta_
-    // token. An Access-authenticated operator issues, rotates, and revokes it
+    // 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

package/examples/worker/wrangler.jsonc

@@ -18,7 +18,7 @@
     "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.33.0",
+  "version": "0.34.1",
   "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"
   },
@@ -113,6 +114,10 @@
       "types": "./dist/providers/infisical/index.d.ts",
       "import": "./dist/providers/infisical/index.js"
     },
+    "./providers/intercom": {
+      "types": "./dist/providers/intercom/index.d.ts",
+      "import": "./dist/providers/intercom/index.js"
+    },
     "./providers/linear": {
       "types": "./dist/providers/linear/index.d.ts",
       "import": "./dist/providers/linear/index.js"
@@ -187,20 +192,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 +216,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,8 +268,8 @@
     "@cloudflare/codemode": "^0.5.0",
     "@cloudflare/vitest-pool-workers": "^0.18.8",
     "@cloudflare/workers-types": "^4.20250101.0 || ^5.0.0",
-    "@fontsource-variable/geist": "^5.3.0",
-    "@fontsource-variable/geist-mono": "^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",
@@ -273,7 +278,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/AGENTS.md

@@ -42,13 +42,19 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
 - 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 client picks the pool per
-  turn: base pool `<agent>` (shared connectors, no `owner`) outside a
-  one-on-one, and `<agent>-<user>` (the base plus that user's own connector
-  ids, `owner` set to their Workspace address) only with that user. Never list
-  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.
+  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/README.md

@@ -55,6 +55,8 @@ 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. A
 rotation cannot recover an old secret; only the hash persists. An agent has no
@@ -118,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.
@@ -139,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
-declared agent's 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
@@ -215,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
@@ -273,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 —

package/templates/node/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.33.0",
+    "@zackbart/connecta": "0.34.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/connecta.config.ts

@@ -92,8 +92,8 @@ export default defineConfig((env: Env) => {
     // /mcp/<name>, and "agent:<name>" for a declared agent at /agent/<name>.
     // A member connects their own account on the pool's personal connectors.
     // `npm run doctor` checks /agent/local-machine with its token. The starter
-    // pool is the agent's base pool (shared connectors, no owner), named after
-    // the agent as the agent pool layout requires.
+    // pool is the agent's base pool, its lowest tier (shared connectors, no
+    // owner), named after the agent as the agent pool layout requires.
     pools: { "local-machine": { tools: ["time"], members: ["agent:local-machine"] } },
     // Machine clients are agents declared here by name, each with one cta_
     // token. Issue or rotate one locally with