@zackbart/connecta 0.17.0 → 0.18.1

package/documentation/stripe.md

@@ -1,27 +1,25 @@
 # Stripe prebuilt connection
 
 Import `stripe()` independently from `@zackbart/connecta/providers/stripe`. It
-wraps [Stripe's hosted MCP server](https://docs.stripe.com/mcp) with a required
-production/sandbox mode, OAuth by default, a mode-scaled admission policy, a
+wraps [Stripe's hosted MCP server](https://docs.stripe.com/mcp) with OAuth by
+default, account-scoped mode guidance, a conservative admission policy, a
 task-oriented usage guide, and a vetted safety classification. It adds no
 provider dependency and is not reachable from Connecta's root entry.
 
 ```ts
 import { stripe } from "@zackbart/connecta/providers/stripe";
 
-const billing = stripe("stripe_live", {
-  mode: "production",
-  title: "Stripe (production)",
-  purpose: "Revenue, disputes, and refunds for the real business",
+const billing = stripe("stripe", {
+  purpose: "Revenue, disputes, and refunds across our Stripe organization",
   instructions: "Never refund above $500 without a human in the loop.",
 });
 ```
 
 The `id` owns the ordinary connector namespaces. Choose a connector boundary
-for its credential or OAuth session, mode, and business purpose — not
-automatically for each Stripe account. One OAuth session may cover more than
-one account in the same Stripe organization. Use separate connectors when the
-credential, production/sandbox mode, or business purpose differs.
+for its credential or OAuth session and business purpose — not automatically
+for each Stripe account. One OAuth session may cover live and sandbox accounts
+in the same Stripe organization. Use separate connectors when the credential
+or business purpose differs.
 
 `purpose` is required because it tells an agent where the deployment intends
 to route a question. The connector id, title, and purpose are configuration,
@@ -29,49 +27,37 @@ not proof of which account the authenticated Stripe session will use. Account
 `instructions` are appended to the maintained guide and cannot change the
 connector's safety classification.
 
-## Mode is required, and it is the whole point
+## OAuth mode belongs to the selected account
 
-`mode` accepts `"production"` or `"sandbox"` and has **no default**. There is no
-safe guess between an account that moves real money and one that does not, so
-the deployment has to say which it configured.
+Do not pass `mode` for OAuth. Stripe's `list_available_accounts_or_orgs` returns
+each available account with its `stripe_context` and `livemode`. The same OAuth
+session can return both `livemode: true` and `livemode: false` results.
 
-Stripe publishes exactly one endpoint — `https://mcp.stripe.com/` — and the
-environment is selected by the credential, not the URL. Connecta therefore
-cannot *route* by mode; what it can do is make the mode impossible for an agent
-to miss, and refuse a deployment whose declaration and credential disagree.
+The served guide tells agents to call that tool before each account-scoped
+operation. They select the intended result and carry its exact `stripe_context`
+and `livemode` unchanged. Connector id, title, purpose, and OAuth identity are
+routing hints. They never prove the account or mode. Ambiguity stops the call.
 
-`mode` shows up in four places an agent actually reads:
+OAuth metadata therefore stays neutral:
 
-- the default `title` (`Stripe (production)` / `Stripe (sandbox)`);
-- the `description`, which is what `search_tools` ranks and returns — production
-  reads `Stripe payments (production — live money and real customers) — …`,
-  sandbox reads `Stripe payments (sandbox — test data, no real money) — …`;
-- the first two lines of the usage guide, which state the mode and then say
-  either "every write moves real money … a refund cannot be undone" or "never
-  answer a question about live revenue, payouts, or a named customer from this
-  connector";
-- the admission policy, below.
+- the default title is `Stripe`;
+- the description says `live and sandbox accounts`;
+- the guide warns that live writes move real money and sandbox writes change
+  test data;
+- admission uses the stricter sandbox ceiling, because Connecta cannot select
+  a different connector policy after the account-scoped call begins.
 
-And one place a deployment author reads: if `auth` is a `headers` credential
-carrying a recognizable Stripe key prefix (`sk_`, `rk_`, or `pk_` with `_live_`
-or `_test_`), construction throws when the key's mode contradicts the declared
-one. That check reads nothing it cannot classify — an OAuth connector, or a
-credential shape this release does not recognize, is left alone rather than
-guessed at — and the error names only the two modes, never the key.
+`mode` remains required for `headers` auth. A restricted key has one fixed live
+or sandbox scope. Its title, description, guide, and admission policy keep the
+fixed-mode behavior. Construction still throws when a recognizable key prefix
+contradicts its declared mode.
 
-Deploy production and sandbox side by side. Two instances are isolated exactly
-like two hand-written connectors with different ids: separate addresses,
-catalogs, credentials, storage, admission counters, and health.
+For OAuth, deploy one connector for the session:
 
 ```ts
 connectors: [
-  stripe("stripe_live", {
-    mode: "production",
-    purpose: "Revenue, disputes, and refunds for the real business",
-  }),
-  stripe("stripe_sandbox", {
-    mode: "sandbox",
-    purpose: "Rehearsing billing changes before they touch production",
+  stripe("stripe", {
+    purpose: "Live and sandbox billing for our Stripe organization",
   }),
 ]
 ```
@@ -86,12 +72,9 @@ says one OAuth session can be tied to more than one account in the same Stripe
 organization. It does not say every session has multiple accounts.
 
 That scope changes what an agent must prove before an account-scoped call. It
-must resolve the intended organization account, inspect the selected tool's
-live input schema, and carry only the exact account or context field that
-schema exposes. If more than one account fits, or the live schema exposes no
-clear selection mechanism, the agent stops and asks. It never guesses from the
-connector id, title, or purpose, and it never invents an MCP argument or
-request header.
+calls `list_available_accounts_or_orgs`, resolves the intended result, and
+carries its exact `stripe_context` and `livemode`. If more than one account
+fits, the agent stops and asks.
 
 Stripe also accepts a
 [restricted API key](https://docs.stripe.com/keys#create-restricted-api-key) as
@@ -131,10 +114,8 @@ stripe("merchant_42", {
 });
 ```
 
-Administrators must enable MCP access in the Stripe Dashboard. Stripe scopes
-OAuth session management and MCP access **separately for sandbox and live
-mode**. A connector that boots but cannot list tools is usually a dashboard
-toggle, not a bad key.
+Administrators must enable MCP access in the Stripe Dashboard. A connector that
+boots but cannot list tools is usually a dashboard toggle, not a bad key.
 
 ## The eleven tools, and what they are classified as
 
@@ -189,14 +170,23 @@ prefixes (`cus_`, `sub_`, `ch_`, `pi_`, `in_`, `acct_`), a plausible-looking one
 belongs to a different object or to nobody, and the id a write takes comes from
 `stripe_api_search` or a list read rather than from a guess.
 
-Account selection comes before that object-id rule. The served guide warns
-that the connector metadata states routing intent rather than authenticated
-identity. It tells the agent to use only selectors in the live tool schema and
-to stop when the account or selection mechanism is ambiguous. It also keeps
+Account selection comes before that object-id rule. The served guide names
+`list_available_accounts_or_orgs`, `stripe_context`, and `livemode`, and tells
+the agent to stop when the account, mode, or selector is ambiguous. It keeps
 organization-account selection separate from the restricted-key-only Connect
 path, so an agent cannot repair uncertainty by fabricating `Stripe-Account` as
 a tool argument.
 
+The guide also carries the reduction advice the generic schemas cannot (P7):
+a list or search read that returns full objects belongs inside `execute_code`,
+projected to the fields the question needs before `return`, because an
+unprojected list truncates and a projected one keeps customer PII out of the
+transcript. It names Stripe search's per-resource field set — charges search
+has no `payment_intent` field, so the path is the PaymentIntent's
+`latest_charge` — and the account → search → details → read sequence as one
+program rather than four turns, and it names `outcome`, `failure_code`, and
+`failure_message` on the charge as the answer to "why did this payment fail".
+
 Stripe publishes no stability or deprecation policy for this tool set and
 invites tool requests by email, so treat the list as unversioned. `get_balance_summary`
 is Treasury, which Stripe labels public preview and gates behind an access
@@ -210,9 +200,10 @@ Stripe documents no rate limit specific to the MCP server. The connection
 therefore transcribes the account limit that MCP traffic spends
 ([rate limits](https://docs.stripe.com/rate-limits)): **100 requests per second
 in live mode, 25 in a sandbox**, and any single endpoint is capped at 25 per
-second regardless of mode, so paging one list is the real constraint. The
-`maxConcurrency` beside it — 8 for
-production, 4 for sandbox — is Connecta's own conservative choice: Stripe
+second regardless of mode. OAuth uses 25 calls per second and concurrency 4,
+the safe bound for a session that can reach either mode. Fixed live credentials
+use 100 calls per second and concurrency 8. Fixed sandbox credentials use 25
+and concurrency 4. Stripe
 documents that per-account and per-endpoint concurrency limits exist, and
 surface as `429` with a `Stripe-Rate-Limited-Reason` of `global-concurrency` or
 `endpoint-concurrency`, but publishes no number.
@@ -226,14 +217,9 @@ admission and still needs restrained use.
 
 ## What is not verified
 
-Stripe's MCP documentation is silent on two things this connection had to reason
+Stripe's MCP documentation is silent on one thing this connection had to reason
 about rather than read:
 
-- **How an OAuth session resolves to live versus sandbox at call time.** Stripe
-  says sessions are "scoped to … the current environment (live mode or a
-  sandbox)" and that dashboard access is managed separately per environment, but
-  never states the mechanism. The key-prefix check covers `headers` auth only;
-  for OAuth, `mode` is a declaration Connecta surfaces and cannot verify.
 - **Whether pagination cursors and `Idempotency-Key` are passable through
   `stripe_api_read` / `stripe_api_write`.** The conventions in the usage guide
   are Stripe's documented API conventions; how they thread through the generic

package/documentation/upgrading.md

@@ -57,7 +57,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.17.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.18.1 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +106,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.17.0
+npm pkg set dependencies.@zackbart/connecta=0.18.1
 npm install
 ```
 
@@ -130,7 +130,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.17.0 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.18.1 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +186,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.17.0 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.18.1 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,6 +207,34 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
+### 0.18.0 → 0.18.1
+
+Nothing throws, no option moves, and every deployment crosses this on the
+version bump alone. The release adds one provider subpath,
+`@zackbart/connecta/providers/revenuecat`, and rewrites guide text inside the
+`mixpanel()` and `stripe()` connections; a deployment that constructs neither
+sees no change, and one that does gets better first-line advice for the same
+constructor calls. Clients that cache connector guides should refresh them
+after upgrading.
+
+### 0.17.0 → 0.18.0
+
+One floor moves and one always-loaded surface shrinks; neither changes a
+deployment's configuration.
+
+**Node 22 is the minimum supported release.** The published engine range and
+the Node template both declare `>=22.0.0`, matching the template's
+`node:22-slim` image. A Docker deployment already runs Node 22; a bare-metal
+deployment on Node 20 must upgrade its runtime before taking this version.
+Worker deployments are unaffected (#422).
+
+**Model-facing guidance is split by load cost.** MCP instructions and tool
+definitions now carry route selection, the fail-closed boundary, and minimum
+guest syntax. Detailed selection, repair, runtime, and example guidance moved
+to the existing `skills({ name: "usage" })` response. Clients that never fetch
+the skill keep the same routes and need no deployment change; clients that
+cache tool definitions should refresh them after upgrading (#418).
+
 ### 0.16.1 → 0.17.0
 
 Two construction rules need a deployment check.

package/ethos.md

@@ -71,6 +71,7 @@ proposing one without a new argument is not.
 | Runtime connector registration | refused | config-as-code is the security model |
 | Prebuilt connections as the preferred authoring path | accepted | an a-la-carte provider constructor, imported and constructed in the deployment file, encodes maintained defaults for providers connecta actually uses — preferred *when maintained*, with no promise of one per provider; it returns exactly one ordinary `Connector` with no extra privileges — never a bundle, a group, a preset, or a registry — its tools are hand-written or proxied from a downstream MCP catalog, never generated from a schema document; its vetted annotations classify what the downstream leaves unannotated and otherwise preserve explicit annotations, with one fail-closed exception: a release-reviewed destructive classification outranks a contradictory downstream `readOnlyHint: true`, because Connecta has independently established that the tool mutates existing state; `remoteMcp()` and `api()` stay first-class ([#297](https://github.com/zackbart/connecta/issues/297), [#315](https://github.com/zackbart/connecta/issues/315)) |
 | Guarded raw REST escape hatches in a prebuilt connection | accepted | a large, fast-moving provider cannot be honestly represented by a small frozen list: a GET-only tool may expose provider-relative reads, while JSON mutations and explicit-content uploads stay separate and always cross the destructive boundary; the connector owns authentication, rate limits, error mapping, URL confinement, and safe method classification, while the provider token remains the capability boundary — this is not schema ingestion, runtime connector registration, or permission widening |
+| Expanded Notion page create/update options | refused | the maintained writes own explicit parents, authored content, property replacement, and reversible trash; workspace-private creation, placement, richer media, coordination locks, asynchronous templates, and irreversible child erasure are different ownership, ordering, file, coordination, or deletion workflows, not missing fields — keep the approval names honest and use a custom `api()` connector when a deployment needs one ([#408](https://github.com/zackbart/connecta/issues/408), [#409](https://github.com/zackbart/connecta/issues/409)) |
 | Hosted-provider drift detection during catalog refreshes | accepted | a vetted classification is a claim about somebody else's catalog, and an allowlist nobody can tell is stale is an allowlist that is wrong — so each maintained hosted-MCP proxy ships the tool names, classifications, and (once a release records them) schemas it reviewed, and compares them against the live listing *inside* a catalog refresh the deployment already asked for; the boundary is the piggyback itself, which is what keeps this from being proactive credential liveness wearing a new hat ([#179](https://github.com/zackbart/connecta/issues/179)): no scheduled job, no background request, no credential probe, and not one byte of network traffic that would not have happened anyway; what it produces is four counts — unclassified additions, names no longer served, explicit annotation conflicts, schema changes — on connector status, `connecta doctor`, and one payload-free activity event with nowhere to put a tool name or a schema; the two read surfaces answer for the runtime that served the refresh, because the observation is isolate-local and only the activity event is durable, and unknown tools already fail closed, so drift costs approval round trips and stale guidance rather than capability ([#343](https://github.com/zackbart/connecta/issues/343)) |
 | Provider registry / integration marketplace | refused | prebuilt connections are imports, not listings; discovery happens in documentation, never at runtime ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Protocol sessions & server push | refused | stateless per request |
@@ -85,6 +86,7 @@ proposing one without a new argument is not.
 | Structured result surface | accepted | canonical `structuredContent` plus complete compact `content`; summary-only text is gated on host-forwarding evidence ([#191](https://github.com/zackbart/connecta/issues/191)) |
 | Code mode (`execute_code`) | accepted | the primary read, discovery, and composition surface: smaller serialized definitions, far smaller results once composition and projection happen before the model sees them, and a cold-start model that read the interface without help ([exploration](./documentation/code-first-exploration.md), [#224](https://github.com/zackbart/connecta/issues/224)) |
 | Code-first as the default; the eval gate retired | accepted | owner decision, 2026-07-30: one operator, no deploy-time flip; [`eval/code-first-gate`](https://github.com/zackbart/connecta/blob/main/eval/code-first-gate/README.md) survives as measurement, but nothing waits on its verdict ([#222](https://github.com/zackbart/connecta/issues/222), [#224](https://github.com/zackbart/connecta/issues/224)) |
+| Always-loaded routing, on-demand execution detail | accepted | every conversation pays for MCP instructions and seven serialized definitions, so they carry only route selection, the fail-closed boundary, and the minimum guest syntax; selection detail, examples, runtime differences, and repair live in the existing byte-identical `usage` skill, fetched at most once per task — no new skill surface or deployment option ([#418](https://github.com/zackbart/connecta/issues/418)) |
 | Surface consolidation to seven tools | accepted | `list_connectors`, `describe_tools`, and `batch_call` fold into the program surface, deleting the routing choice between direct calls, batches, discovery, and execution; `call_tool` stays because a simple call is not cheaper through code ([#224](https://github.com/zackbart/connecta/issues/224)) |
 | Classic (executor-free) surface | removed | supersedes its provisional retention under [#224](https://github.com/zackbart/connecta/issues/224) — an executor is mandatory, and a deployment without one refuses to boot rather than serving a fallback shape ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Connector shortcut namespaces in programs | accepted | sugar over canonical addressing, kept but frozen — every expansion invents a collision class `<connectorId>.<toolName>` already solved ([#223](https://github.com/zackbart/connecta/issues/223)) |
@@ -100,6 +102,7 @@ proposing one without a new argument is not.
 | Inbound-demand catalog stale-while-revalidate | accepted | an agent-facing catalog read may return a complete, fingerprint-verified entry inside its configured stale window and move the refresh that same read demanded onto the runtime's existing deferred-work channel; this originates no timer, schedule, warmup, or credential probe, and operator status remains blocking — one refresh per connector is shared across agent and operator requests, a deferred owner uses a fresh bounded signal and connector scope and closes that scope, and invalidation is rechecked before stale publication, so no request-bound capability survives and no partial or pre-invalidation catalog gains authority ([#396](https://github.com/zackbart/connecta/issues/396)) |
 | Rich program output (`connecta.emit`) | accepted | one host-collected emission channel: programs emit strictly validated text/image/audio blocks, delivered after the result envelope on success only; budgets fail loudly at the emit call ([design record](./documentation/rich-output-design.md), [#267](https://github.com/zackbart/connecta/issues/267)) |
 | Result-channel widening of the `Executor` contract | refused | `ExecuteResult` stays `{ result, error?, logs? }` — structural compatibility with `@cloudflare/codemode` is the parity guarantee; emission rides the provider bridge instead ([#267](https://github.com/zackbart/connecta/issues/267)) |
+| Erasable TypeScript in `execute_code` | refused | a location-preserving prototype accepted annotations, return types, assertions, aliases, interfaces, and erased generics at ~8.3 µs median transform cost, but `ts-blank-space` drags a 23.68 MB installed TypeScript dependency into the fetch-native core and no runnable agent arm established a first-run or repair benefit; the plain-JavaScript contract stands until new measured model evidence earns that package and parity cost ([evidence](https://github.com/zackbart/connecta/blob/main/eval/current-version/results/issue-419-evidence.md), [#419](https://github.com/zackbart/connecta/issues/419)) |
 | Guest-emitted `resource` / `resource_link` blocks | refused | a program can never mint a URI a client may dereference, and the carve-out this row waited on does not need one: `connecta.ui` takes HTML content, and the only `ui://` URI is connecta's build-time shell ([design record](./documentation/mcp-ui-design.md), [#266](https://github.com/zackbart/connecta/issues/266), [#267](https://github.com/zackbart/connecta/issues/267)) |
 | Provenance tracking for emitted content | refused | everything a program emits is program output; handles or attribution labels are capability-shaped machinery that changes no client's trust posture ([#267](https://github.com/zackbart/connecta/issues/267)) |
 | Program-generated UI (`connecta.ui` + the Apps shell) | accepted | one MCP Apps view per successful run: the program supplies HTML only, delivered in result `_meta`, which hosts keep out of model context, and rendered by connecta's static shell inside the host's sandboxed frame ([design record](./documentation/mcp-ui-design.md), [#266](https://github.com/zackbart/connecta/issues/266)) |
@@ -143,7 +146,4 @@ Breaking one is not a bug fix — it is a design change wearing a disguise.
   the wrong shape is worse than one that refuses to boot.
 
 ---
-
-Connecta began as a radical simplification of
-[executor](https://github.com/UsefulSoftwareCo/executor). The table above is
-the record of that simplification holding.
+Connecta began as a radical simplification of [executor](https://github.com/UsefulSoftwareCo/executor); the table above is the record of that simplification holding.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.17.0",
+  "version": "0.18.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 seven meta-tools.",
   "license": "MIT",
   "engines": {
-    "node": ">=20.9.0"
+    "node": ">=22.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -79,6 +79,10 @@
       "types": "./dist/providers/notion.d.ts",
       "import": "./dist/providers/notion.js"
     },
+    "./providers/revenuecat": {
+      "types": "./dist/providers/revenuecat.d.ts",
+      "import": "./dist/providers/revenuecat.js"
+    },
     "./providers/stripe": {
       "types": "./dist/providers/stripe.d.ts",
       "import": "./dist/providers/stripe.js"

package/templates/node/README.md

@@ -8,6 +8,13 @@ npm install
 CONNECTA_TOKEN=dev-token npm start
 ```
 
+The manifest approves only `esbuild@0.28.2` to run its install script. `tsx`
+uses esbuild to run this TypeScript source, so that script is part of the
+prescribed runtime path. npm 11 therefore installs without an unreviewed-script
+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.
+
 Then point an MCP client at `http://localhost:8787/mcp` with
 `Authorization: Bearer dev-token`.
 

package/templates/node/package.json

@@ -4,7 +4,10 @@
   "version": "0.0.0",
   "type": "module",
   "engines": {
-    "node": ">=20.9.0"
+    "node": ">=22.0.0"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true
   },
   "scripts": {
     "doctor": "connecta doctor",
@@ -12,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.17.0",
+    "@zackbart/connecta": "0.18.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {