@zackbart/connecta 0.33.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.
@@ -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.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,8 +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/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 +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/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.0",
     "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