@zackbart/connecta 0.24.3 → 0.24.4

package/examples/worker/AGENTS.md

@@ -37,7 +37,8 @@ This repository is deployment configuration, not a copy of Connecta itself.
   A configured Connecta bearer cannot cross the Access edge alone. Connecta-issued
   tokens are removed. UI, vault, and activity use explicit optional imports;
   auth changes require code-derived shared or personal management permissions.
-- Run the repository's `npm run check:examples` after configuration changes.
+- After configuration changes, typecheck: inside the connecta repository that
+  is `npm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and
   complete their browser authorization flows before calling setup complete.
 

package/examples/worker/README.md

@@ -8,7 +8,7 @@ Workers Paid plan.
 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
 owns only its connector configuration, auth policy, domain, bindings,
-migrations, and secrets. See [the Cloudflare guide](../../documentation/cloudflare.md).
+migrations, and secrets.
 
 ## Files
 
@@ -17,14 +17,15 @@ migrations, and secrets. See [the Cloudflare guide](../../documentation/cloudfla
 | `src/index.ts` | the Worker entrypoint — connector and auth configuration |
 | `src/cloudflare-kv.ts` | `KVStorage` over Workers KV (deployment-owned, not a package export) |
 | `src/d1-activity.ts` | `ActivityStore` over D1 (deployment-owned; see below) |
+| `src/d1-activity-row.ts` | the row ↔ event mapping `d1-activity.ts` uses, including friction derived from `error_code` for rows written before that column existed |
 | `wrangler.jsonc` | Worker name, vars, bindings, `compatibility_flags` |
 
 `cloudflare-kv.ts` and `d1-activity.ts` deliberately live here rather than in
 the package: storage backends are deployment-owned, so the package ships only
 the generic `KVStorage` and `ActivityStore` contracts. Workers KV is eventually
 consistent across locations; use a strongly consistent `KVStorage` adapter when
-OAuth disconnect, credential rotation, or access-token issuance/revocation must
-become globally visible immediately.
+OAuth disconnect or credential rotation must become globally visible
+immediately.
 
 ## Deploy
 
@@ -144,9 +145,12 @@ See [inbound identity](../../documentation/auth.md#principals-visibility-and-ope
 ### UI and encrypted credentials
 
 Import `operatorUi` from `@zackbart/connecta/ui` and set `ui: operatorUi()`.
-Branding belongs in `operatorUi({ branding })`. Omit the import and option to
-serve no UI routes; OAuth callbacks still work in core for authorized
-interactive MCP callers.
+Branding belongs in `operatorUi({ branding })`, including `branding.theme`:
+`accent`, `radius`, `fontFamily`, `monoFamily`, and `colorScheme`. Every other
+color is mixed from those, so one accent themes the whole page. A value that
+fails its gate falls back to the default, and the startup warning names it. Omit
+the import and option to serve no UI routes; OAuth callbacks still work in core
+for authorized interactive MCP callers.
 
 Import `encryptedCredentialVault` from `@zackbart/connecta/credentials` and set
 `vault: encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY)` when
@@ -172,8 +176,7 @@ does not create credentials or permissions by itself.
 Interactive MCP clients use Access Managed OAuth. Unattended clients use Access
 service tokens when needed. Connecta-issued `cta_` tokens and their management
 routes are removed; a configured Connecta bearer cannot cross the Access edge
-alone. See the [migration guide](../../documentation/upgrading.md#0240-optional-modules)
-if an older deployment still issues tokens.
+alone.
 
 Activity uses `activityHistory({ store: d1ActivityStore(env.ACTIVITY_DB) })`
 from `@zackbart/connecta/activity`. Enable the database and bindings described
@@ -295,8 +298,7 @@ To enable it:
    });
    ```
 
-Events carry no arguments, results, generated code, or raw error messages — see
-[activity history](../../documentation/operator-ui.md).
+Events carry no arguments, results, generated code, or raw error messages.
 The Worker entrypoint already forwards `ctx` to `connecta.fetch`, which lets
 async activity writes settle on `waitUntil`.
 

package/examples/worker/src/index.ts

@@ -11,9 +11,9 @@ import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
  * wrangler.jsonc backs the seven-tool surface.
  *
  * The operator surface is wired here except for activity history, which needs
- * a database this example does not create for you: sign-in, the credential
- * vault, and access-token issuance are on, and activity is three commented
- * lines below. README.md § "The operator surface" walks through all four.
+ * a database this example does not create for you: sign-in and the credential
+ * vault are on, and activity is three commented lines below. README.md
+ * § "Select optional modules" walks through all three.
  *
  * Setup (this example has no package.json of its own — it self-references the
  * installed `@zackbart/connecta` package):
@@ -90,22 +90,19 @@ function build(env: Env) {
     //   activityAccess: ({ id }) => id === "ACCESS_USER_UUID",
     // },
     // Connectors that declare a `credential` slot become editable by every
-    // signed-in human who can see that connector at /credentials, encrypted
-    // with this key before anything reaches KV. A saved replacement takes
+    // signed-in human who can see that connector, inside its connection on /,
+    // encrypted with this key before anything reaches KV. A saved replacement takes
     // effect on the next call — no redeploy, and no liveness probe:
     // credentials fail at use.
     //
-    // The key is the vault, not the page: /credentials is a list of connector
-    // slots, so it stays hidden until a connector declares one. Neither
-    // connector below does — Notion here carries a deployment-owned static
-    // header and echo has no secret at all — so this example ships the vault
-    // ready and the page empty. Declare a slot (see the commented shape on
-    // `echo`, or use a provider connector like `notion()`, which declares its
-    // own) and the page appears on the next load.
+    // The key is the vault, not the form: a credential form appears only on a
+    // connector that declares a slot. Neither connector below does — Notion
+    // here carries a deployment-owned static header and echo has no secret at
+    // all — so this example ships the vault ready and nothing to fill in.
+    // Declare a slot (see the commented shape on `echo`, or use a provider
+    // connector like `notion()`, which declares its own) and the form appears
+    // on the next load.
     vault: encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY),
-    // Eligible human operators can create named, revocable MCP Bearer tokens
-    // at /tokens. Under Worker-level Access those tokens are a rollback tool,
-    // not standalone edge credentials: Access still runs before connecta.
     ui: operatorUi(),
     identity: { credentialAdministration: () => "all", personalConnection: () => "all" },
     // Payload-free activity at /activity, off until a database exists to hold

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.24.3",
+  "version": "0.24.4",
   "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 seven meta-tools.",
@@ -129,7 +129,6 @@
     "check:examples": "tsc -p tsconfig.template.node.json && tsc -p tsconfig.examples.worker.json",
     "check:security": "npm audit --omit=dev --audit-level=moderate",
     "check:package": "node scripts/check-package.mjs",
-    "load:admission": "npm run build && node eval/admission-load.mjs",
     "providers:check": "tsx scripts/drift-check.mjs --specs --docs",
     "drift:check": "tsx scripts/drift-check.mjs",
     "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run build && npm run check:examples",

package/templates/node/.env.example

@@ -23,14 +23,14 @@ CONNECTA_STATE_FILE=
 # Each of these is read only once the matching block in src/index.ts is
 # uncommented. Setting one on its own changes nothing.
 
-# Operator sign-in with Clerk. Only a signed-in operator may write a credential
-# or issue an access token; the bearer above is a client key, not an admin key.
+# Operator sign-in with Clerk. Only a signed-in operator may write a
+# credential; the bearer above is a client key, not an admin key.
 # Also run `npm install @clerk/backend` — it is an optional peer.
 CLERK_PUBLISHABLE_KEY=
 CLERK_SECRET_KEY=
 
 # Credential vault. Base64-encoded 32-byte AES key encrypting the values an
-# operator saves at /credentials. Generate one with:
+# operator saves inside a connection on /. Generate one with:
 #   node -e "console.log(crypto.randomBytes(32).toString('base64'))"
 # Keep it here or in a secret store — never in the state file it protects, and
 # never in source control. Losing it makes stored credentials unreadable.

package/templates/node/AGENTS.md

@@ -19,7 +19,6 @@ This repository is deployment configuration, not a copy of Connecta itself.
   alone never grants it. Configured bearer auth is a client option, not a human
   management identity. Connecta-issued access tokens are removed.
   `src/file-activity.ts` remains the deployment-owned history store.
-
 - Run `npm run typecheck` after configuration changes. With the server running,
   run `CONNECTA_TOKEN=... npm run doctor` before calling setup complete.
 - `Dockerfile` and `docker-compose.yml` containerize *this* source; they are
@@ -27,9 +26,11 @@ This repository is deployment configuration, not a copy of Connecta itself.
   `src/index.ts`, never in a divergent container entrypoint.
 - Moving this deployment to a newer Connecta is its own procedure, and it is
   not a re-`init` — `connecta init` refuses to merge into an existing path on
-  purpose. Follow
-  [the upgrade guide](https://github.com/zackbart/connecta/blob/main/documentation/upgrading.md),
-  which also ships at `node_modules/@zackbart/connecta/documentation/upgrading.md`.
+  purpose. Bump the exact `@zackbart/connecta` pin in `package.json`, then read
+  the [changelog](https://github.com/zackbart/connecta/blob/main/CHANGELOG.md)
+  for every release in between — it also ships at
+  `node_modules/@zackbart/connecta/CHANGELOG.md`. Each release opens with what
+  breaks and what a deployment can ignore.
 
 Do not add alternate entrypoints, policy layers, generated connector catalogs,
 or runtime connector registration. Keep the deployment small enough to review

package/templates/node/README.md

@@ -74,7 +74,8 @@ connector where each person should connect their own downstream account.
 ### Credential vault
 
 Import `encryptedCredentialVault` from `@zackbart/connecta/credentials`, then
-set `vault: encryptedCredentialVault(storage, credentialKey)`. Set
+set `vault: encryptedCredentialVault(storage, credentialKey)` — `storage` is
+the `fileStorage` binding `src/index.ts` already passes to `createConnecta`. Set
 `CONNECTA_CREDENTIAL_KEY` to a base64 32-byte AES key:
 
 ```sh

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.24.3",
+    "@zackbart/connecta": "0.24.4",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/index.ts

@@ -9,10 +9,10 @@ import { operatorUi } from "@zackbart/connecta/ui";
  * storage, and public origin. Add application logic only inside deliberate
  * api() connector handlers.
  *
- * The operator surface — sign-in, credential vault, access tokens, activity —
- * ships here as commented configuration, because each half needs a secret or a
- * retention decision this file cannot make for you. Uncomment the block you
- * want; README.md § "Turn on the operator surface" walks through all four.
+ * The optional modules — operator sign-in, credential vault, activity — ship
+ * here as commented configuration, because each needs a secret or a retention
+ * decision this file cannot make for you. Uncomment the block you want;
+ * README.md § "Select optional modules" walks through all three.
  *
  * Environment (see .env.example):
  *   CONNECTA_TOKEN           required inbound bearer token
@@ -44,12 +44,12 @@ const port = Number(process.env.PORT ?? 8787);
 // empty state path or public origin is worse than the local default.
 const stateFile = process.env.CONNECTA_STATE_FILE || "./.connecta-state.json";
 const publicUrl = process.env.PUBLIC_URL || `http://localhost:${port}`;
+const storage = fileStorage(stateFile);
 
 // Operator sign-in. A bearer token is a client key: it may call tools and read
 // connector status, but only a Clerk-authenticated human may write a visible
-// connector's credential, and only an operator may issue an access token.
-// Without this block the operator pages still render — an operator pastes the
-// bearer to read them — and Credentials and Tokens stay read-only.
+// connector's credential. Without this block the operator UI still renders —
+// an operator pastes the bearer to read it — and connections stay read-only.
 // const clerkPublishableKey = process.env.CLERK_PUBLISHABLE_KEY;
 // const clerkSecretKey = process.env.CLERK_SECRET_KEY;
 // if (!clerkPublishableKey || !clerkSecretKey) {
@@ -59,7 +59,7 @@ const publicUrl = process.env.PUBLIC_URL || `http://localhost:${port}`;
 // }
 
 const connecta = createConnecta({
-  storage: fileStorage(stateFile),
+  storage,
   auth: [
     bearerToken(token, { subjectId: "operator" }),
     // clerkAuth({
@@ -71,20 +71,24 @@ const connecta = createConnecta({
     //   // allowedDomains: ["acme.com"],
     // }),
   ],
-  // Optional member/operator split for Clerk-backed Docker deployments.
-  // Connector access is derived from the authenticated identity and cannot be
-  // selected by an MCP argument. Omit this block for the legacy all-visible,
-  // all-interactive-users-are-operators behavior.
-  // identity: {
-  //   connectorAccess: ({ principal }) =>
-  //     principal?.id === "user_admin" ? "all" : ["time"],
-  //   activityAccess: ({ id }) => id === "user_admin",
-  // },
+  // Code-owned identity resolvers. The two management permissions default to
+  // none, so the template grants them. The commented pair is the optional
+  // member/operator split for Clerk-backed deployments: connector access is
+  // derived from the authenticated identity and cannot be selected by an MCP
+  // argument. Leave them commented for the all-visible,
+  // all-interactive-users-read-activity behavior.
+  identity: {
+    credentialAdministration: () => "all",
+    personalConnection: () => "all",
+    // connectorAccess: ({ principal }) =>
+    //   principal?.id === "user_admin" ? "all" : ["time"],
+    // activityAccess: ({ id }) => id === "user_admin",
+  },
   publicUrl,
   // Required: model-written programs run in a bounded QuickJS child.
   executor: quickJsExecutor(),
   // Credential vault. A connector that declares a `credential` slot becomes
-  // editable at /credentials, and its value is encrypted in the state file
+  // editable inside its connection on /, and its value is encrypted in the state file
   // with this key — so keep the key out of that file and out of source:
   //   node -e "console.log(crypto.randomBytes(32).toString('base64'))"
   // Rotating a credential takes effect on the next call; no restart.
@@ -100,13 +104,10 @@ const connecta = createConnecta({
   //   deploymentId: "production",
   // }),
   ui: operatorUi(),
-  identity: { credentialAdministration: () => "all", personalConnection: () => "all" },
   connectors: [
     api("time", {
       description: "Time — current timestamp",
-      // /credentials lists connectors, not deployments: the page stays hidden
-      // until at least one connector declares a slot, vault or no vault. A
-      // connector that needs an operator-managed secret adds one here —
+      // A connector that needs an operator-managed secret declares a slot —
       //   credential: { label: "API token" },
       // — and reads it inside a handler with `await ctx.credential?.get()`.
       // Telling the time needs no secret, so this one declares nothing.

package/documentation/call-admission.md

@@ -1,158 +0,0 @@
-# Downstream call admission
-
-One admitted MCP request can fan out into many downstream calls. A program
-calls tools from loops, from parallel `connecta.call` calls, and from branches the caller
-never saw. The deployment-wide request pool
-([request admission](./request-admission.md)) bounds the envelope; it cannot
-see anything inside it. A provider that publishes "60 requests per minute"
-needs a bound that counts calls, not requests.
-
-So a connector may declare `callAdmission`: an optional per-runtime policy
-around its own `Connector.callTool` attempts.
-
-```ts
-const projects = api("projects", {
-  description: "Projects — issues and reports",
-  callAdmission: {
-    // Plural-ready public shape; this release requires exactly one rule.
-    rules: [{
-      maxConcurrency: 5,
-      maxQueueSize: 10,       // default 32
-      queueTimeoutMs: 2_000,  // default 5_000
-      retryAfterMs: 1_000,    // concurrency-overload hint
-      budget: { kind: "rolling-window", maxCalls: 60, windowMs: 60 * 60_000 },
-      partitionKey({ toolName, args }) {
-        return projectIdFor(toolName, args);
-      },
-    }],
-    maxPartitions: 1_024,     // default
-  },
-  tools: [/* … */],
-});
-```
-
-`api()`, `remoteMcp()`, and a hand-written `Connector` all accept it. Maintained
-prebuilt connections set it themselves — but only when the provider documents a
-number, which is convention
-[P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number).
-An invented budget is a throttle with no source.
-
-## Policy contract
-
-`maxConcurrency` and `budget` are independently optional, but a rule must
-declare at least one — a rule that bounds nothing is a typo, not a policy.
-Queue settings require `maxConcurrency`, because there is nothing to queue
-behind without it, and `maxQueueSize: 0` is the fail-fast shape. Numeric bounds
-are finite whole numbers: concurrency, timeouts, budget values, and
-`maxPartitions` are positive; queue size and `retryAfterMs` may be zero.
-`budget.kind` must be `"rolling-window"`. Everything invalid throws during
-registry construction.
-
-The container is an array so a later release can add atomic rules over
-different partition dimensions, but **exactly one rule** is accepted today.
-Zero or several throw rather than imply semantics the runtime does not have.
-Multiple rules cannot be faked as sequential leases: consuming one rolling
-token before a later rule refuses would charge a call that never reached the
-provider — the exact accounting error a budget exists to prevent.
-
-Omitting `partitionKey` gives one connector-wide partition. A callback runs
-synchronously on model-supplied arguments and must return a non-secret string
-of at most 128 UTF-8 bytes. A throw or an invalid return is a typed local
-`connector_call_failed`; neither the callback text nor the arguments are
-surfaced. The callback is operator code and may abort the caller synchronously,
-so cancellation is rechecked after it returns — otherwise a cancelled call
-could still consume a budget entry.
-
-State retains the returned key, bounded timestamps, counters, signals, and
-promise continuations. Nothing copies arguments into the limiter; the queued
-waiter closure deliberately captures the `AbortSignal` rather than the input
-object, because closing over the input would retain its `args`. At most
-`maxPartitions` states are live, and an idle state is evicted only once its
-active calls, queue, and rolling-window history are all empty — eviction must
-not be a way to reset a live budget. Exhausted partition capacity is
-`rate_limited` with the configured retry hint, not a silent unbounded map.
-
-## Attempt semantics
-
-The registry owns the limiter, and `InvocationService.invoke` acquires a permit
-immediately before `Connector.callTool` and releases it in `finally`. Both call
-paths, top-level `call_tool` and program calls through `connecta.call`,
-reach that same seam, so a program cannot buy itself a
-second limit by taking the other route.
-
-- **A caller retry is another call.** It reacquires and can consume another
-  budget entry. Connecta returns retry hints without waiting or retrying.
-- **A proactive short-window `rate_limited` refusal** returns its retry hint
-  without waiting or dispatching. Activity records one failed admission attempt;
-  a caller may reissue after the window.
-- **A queued cancellation consumes nothing.** It is removed from the queue with
-  no rolling-window entry charged.
-- **Caller cancellation is terminal.** It is non-retryable, releases its
-  permit, records a `cancelled` activity outcome, and is not connector-health
-  evidence.
-- **Budget exhaustion fails immediately** as `rate_limited`, `retryable: true`,
-  with the exact `retryAfterMs` to the next free slot. Concurrency overflow
-  uses the configured hint instead, because there is no exact answer.
-- **Local refusals are not connector health failures.** They are activity
-  errors, but no provider call happened, so poisoning the connector's health
-  with them would report the limiter's success as the downstream's failure.
-  `isCallAdmissionError` is what keeps `recordFailure` out of that path.
-
-Only tool execution is covered. Catalog `listTools`, status probes, credential
-checks, and authorization operations stay outside the budget: they are not the
-calls a provider is rate-limiting, and charging discovery for them would make
-a program's first search cost it capacity to act.
-
-`queueTimeoutMs` bounds only the wait for a permit. The per-call `timeoutMs`
-is one deadline over catalog resolution, the permit wait, and the connector
-call together, so a saturated call can never take longer than `timeoutMs`;
-the queue timeout may only end it sooner. With
-`diagnostics: true`, `admissionMs` reports the permit wait and `connectorMs`
-the admitted attempt — which is the only way to tell "the provider is slow"
-from "we are throttling ourselves".
-
-## Enforcement scope
-
-Shared connectors use the root registry's controller. Personal connectors use
-the owning principal's registry, so two accounts each receive their own budget;
-all requests and call paths for one principal still share it. `close()` rejects
-queued and future admissions on both kinds of controller, including a personal
-registry constructed after shutdown.
-
-The principal cache is bounded at 1,024 registries. Eviction closes an idle
-registry so an older request view cannot use an orphaned controller. A registry
-with active calls, queued calls, or unexpired rolling entries is never evicted.
-If all 1,024 are occupied, a new principal view fails closed with HTTP 403 until
-one drains. Cache churn cannot reset a live account's quota.
-
-This is deliberately **per-runtime**. It completely contains fan-out inside one
-request, including parallel `connecta.call` calls in one Worker isolate. A rolling
-budget is exact inside one Node process or Worker isolate, and best-effort
-across isolates, replicas, and restarts.
-
-KV cannot coordinate the invariant without atomic operations, and this release
-adds no Durable Object or other distributed coordinator. The async typed permit
-is the seam a coordinator would slot into later; until then the guide says what
-the bound actually is rather than implying a global one.
-
-## Observations
-
-`/health` exposes one payload-free aggregate at
-`admission.downstreamCalls.aggregate`, summed across root and retained personal
-controllers: rule and retained partition counts, current
-active and queued gauges, cumulative admitted/queued/rejected/rate-limited/
-cancelled counts, and queue-wait count, total, and maximum. The open endpoint
-never exposes connector ids, principal ids, partition keys, tool arguments, or results — a partition key can
-be a customer identifier, which is precisely why it stays out of an unauthenticated
-payload. Queue-wait maxima take the maximum, other counters sum, and `closed`
-means every included controller is closed. Evicted idle controllers no longer
-contribute to these runtime snapshots. Ordinary payload-free activity records the final call outcome and its
-typed error code.
-
-## Tests that enforce this
-
-| Invariant | Suite |
-| --- | --- |
-| Independent partitions, exact rolling-window reset and retry, queued cancellation charging no budget, synchronous cancel during partition derivation, validated values snapshotted rather than read from mutable config, bounded partition state and contained `partitionKey` failures, empty and multi-rule policies refused | `test/call-admission.test.ts` (controller) |
-| Shared and personal limiters shared by direct and program calls, independent principal budgets, shutdown covering both, eviction preserving live budgets, promise concurrency with input order preserved, cancellation threading, no dispatch or retry or health poisoning after cancellation, retry hints returned without waiting or poisoning health, payload-free `/health` aggregates | `test/call-admission.test.ts` (integration, Node + Workers) |
-| Where provider budgets are allowed to come from at all | [provider conventions P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number), [provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md) |