@zackbart/connecta 0.16.1 → 0.18.0

package/dist/providers/mixpanel.js

@@ -79,14 +79,78 @@ const WRITE_TOOLS = new Map([
     ["Create-Feature-Flag", "additive"],
     ["Update-Feature-Flag", "destructive"],
 ]);
+/** Live US hosted-MCP schemas reviewed read-only on 2026-08-13 (#395). */
+const MIXPANEL_SCHEMA_DIGESTS = {
+    "Bulk-Edit-Events": "sha256:94512138df153de95436371f5a313e32b97faffebda3be6c0c69d09d1ff2b340",
+    "Bulk-Edit-Properties": "sha256:93481eb896ded45b623c678612e2156439efbaad5b4d660da1f2b087e7409ee3",
+    "Create-Cohort": "sha256:ea687f4bc607f8bfb5b1949e060239d6f7d629d3ec80fb0b72eae6cc6156ed03",
+    "Create-Custom-Property": "sha256:d22818b812f3fd0e785a5bbbee26cf099eaa911d5b6f383f94cf458a2ed26294",
+    "Create-Dashboard": "sha256:bd3b6e5134d27dafb04ccdf04d19e54dd23e6e2dc16989e418006e484268037b",
+    "Create-Experiment": "sha256:3307bd7202f5483adbc28a9ef1d562095d6942eb2c3a15308f458072c93e6888",
+    "Create-Feature-Flag": "sha256:3460d11d726727349cac62db5c19915ab589b7f1d8387042f0a3783356b252c4",
+    "Create-Lookup-Table": "sha256:c2fefa33a4f19fc65f394fecdc7126cab0ae874f7c97018cf003d8462a049e4c",
+    "Create-Metric": "sha256:315766d0c197d87bb44aedd16732f6e69fbfc93661d1fcfc177cadc1751f26ce",
+    "Create-Tag": "sha256:f99b6faad422aa6142d20d0aa4bdec1074e96a8ec45e35573e86d84b01df1d3b",
+    "Delete-Cohort": "sha256:e18c500459edd9c2b6a614a3f6c97b668786be9abf72929a0a50086bdadb1dae",
+    "Delete-Dashboard": "sha256:3a04594218b491743240e6970f677ed8ed132237d933efe30e97bdc41eb1ab6f",
+    "Delete-Tag": "sha256:5f6cc58ada5d2796f124e15883fe05061d03f9129414f4c8e10a0ec463f17807",
+    "Describe-Cohort-Schema": "sha256:775dbb8bb71ad3fa39ba35ca3a2683dfd88120f7af84a968531609c5a12de537",
+    "Dismiss-Duplicate-Group": "sha256:4e39c6f9bb83ed54020097f6cf34507a5288de2c1ce333456c84682bb5986bc4",
+    "Dismiss-Issues": "sha256:9c1f4901eca53f58d16feee126868d23c6ed1f5fad72344f86ea9965385b8644",
+    "Display-Query": "sha256:d0776167b8a20898c1ff580ca9517da8dea6b827c64e10b9fa01ae1a3c2db95f",
+    "Duplicate-Dashboard": "sha256:9738db7495d29034df966423df3c9d4b16ac3a8254c8473bf1e85a467fe9cf4e",
+    "Edit-Event": "sha256:28c47da0b56f57da0f11eb11435441a39ecd5175600f854442744c66a379ef93",
+    "Edit-Property": "sha256:11975587d2a566edc468db7cb24df70167d12068f30c1fe52c84f543cf4e2399",
+    "Explain-Experiment-Health-Check": "sha256:a50b1263247012dc78521bf6c1dd18584a7b08d46221a444b1ca49c81d3286e5",
+    "Find-Duplicate-Groups": "sha256:8f944cef9a147eab3c51bfcf1b873cef1409e5a6c21565d34e7ed20d23dcebb7",
+    "Get-Business-Context": "sha256:309f5ba864c90132061096b4f0ebc1e78544a6486bac3a45bd661d16bcab2b6c",
+    "Get-Cohort": "sha256:e18c500459edd9c2b6a614a3f6c97b668786be9abf72929a0a50086bdadb1dae",
+    "Get-Custom-Property": "sha256:d1cbce906cee66d422846c8ef1a745bbeac2c058ecad6b1ee8dcdd2120fa86be",
+    "Get-Dashboard": "sha256:56659fa3277723b75e24f3b4ca142ac9cd62120fb97e6c9252c221d00cdf8509",
+    "Get-Events": "sha256:d206fe30ab47d64bf6090bffdb4d119a80cfc2a35963bbe7fd52d56060090ded",
+    "Get-Experiment": "sha256:f9f04a2bb136809c754ea612963e1cdfb57c2c9ecc34a53ac6e1730f8758798f",
+    "Get-Experiment-Results-Interpretation-Guidance": "sha256:e517d9759f66f4a7ad15b0b67ffaabfb605e80949afcf41d007dfafd8f3e9574",
+    "Get-Experiment-Setup-Guidance": "sha256:e517d9759f66f4a7ad15b0b67ffaabfb605e80949afcf41d007dfafd8f3e9574",
+    "Get-Feature-Flag": "sha256:129de58b379ffba272bdbcee2b5759262e586dd415edc2067a69e9844d4d0877",
+    "Get-Feature-Flag-Lifecycle-Guidance": "sha256:e517d9759f66f4a7ad15b0b67ffaabfb605e80949afcf41d007dfafd8f3e9574",
+    "Get-Feature-Flag-Setup-Guidance": "sha256:e517d9759f66f4a7ad15b0b67ffaabfb605e80949afcf41d007dfafd8f3e9574",
+    "Get-Issues": "sha256:cf172ef18f37504a758c825c7bd4bc23fd98c3421655754dccd8e5ee2d700a10",
+    "Get-Lexicon-URL": "sha256:c6456d5c4a38ba069a2caa6cdac651be9d86d47bc6efb3316a893c7336d0e2bc",
+    "Get-Lookup-Table": "sha256:061602b283461f083bbd74348c264f802cb21c4fe6d961241c7090895a8334ac",
+    "Get-Metric": "sha256:eef10dd9ca25a63a63775565cbc4f2261b289dec526aa33df0f318eefbc96c46",
+    "Get-Projects": "sha256:d23d07a777441f04b128f08a2c30a6e8a1573d203f8a1ad7788bc1fd57a9cbbf",
+    "Get-Property-Values": "sha256:0cd487c9b92a187b21f456de3c785bb631aa30cba702785c9ff158608883a6bb",
+    "Get-Query-Schema": "sha256:8fea929d2ad4f8fed6c47116ff0eaa6f964b3ddd4685e482b68a8dac0231af73",
+    "Get-Report": "sha256:a99ba2af1ab57c1d5a606dbd7701968aa430ab23f5969f356a4c41f345dba041",
+    "Get-User-Replays-Data": "sha256:5df287735478a67489075b0c7c9d8c07097abe67408d06743c7fb9be43c6e024",
+    "List-Cohorts": "sha256:fd04778d60a027cfd777b40f36fbb037ba070661e149b2fce35a14865cada2db",
+    "List-Dashboards": "sha256:994c1c9fc87a4f1f00a677b856a44bad028252d283bd8e647ae157683fc89ea2",
+    "List-Experiments": "sha256:26a3f3e0b4e52135d74335dd769103303071fc48c15b1df40efd2dfa5a353848",
+    "List-Feature-Flags": "sha256:75fc1ff14f3d3faedb8e00c6563d151de397d584429764fd0c332f6a84f6993c",
+    "List-Metrics": "sha256:341710bebabb82112e80eb521d9d5cdb3bca024699b3aa795874d3549a315042",
+    "List-Organizations": "sha256:e4c23f123dde073e00038d92ebd53f45157c83a4d3a2ff686ab1b66c859f4a11",
+    "List-Properties": "sha256:52b38861df076119dfefe0128cf9819868336bf60e090f63c80da734877a69fe",
+    "Merge-Group": "sha256:a3b215a5be70305c2f02439513bee76ae3947da14e2a9e5b6ff0afb9ad3d4dcd",
+    "Rename-Tag": "sha256:a7e20e79ecd6ca7edca104fa1030e059ffae8962bf084d4a384c012ac9bbf087",
+    "Run-Experiment-Pre-Launch-Checks": "sha256:f6b5d85f75450b76fda9c7ef441f190fd45fcaeaff4cc3c30a6d1bee76e4c706",
+    "Run-Query": "sha256:0eb7d52343f6137275a02c2d7bb02dafdbfd25bd6f9067395eb689492d835466",
+    "Search-Entities": "sha256:86cfa1d3bf7f17a70ad07264d7b1d16c83480e40996e8d847911fe8bde13e35e",
+    "Search-Prior-Experiments": "sha256:847d1dcefaf6dc5e7ea967476f464a4d678a06b5e7d437dfb11ad4af2e56620f",
+    "Update-Business-Context": "sha256:0d21290053b6d532386c3c83d60cd78013a7109492c02ba2e7822716f2cde027",
+    "Update-Cohort": "sha256:ebe0d5afcc00e23eef55f079cd1816c851c2c647dff9565b7045f1f1615663f2",
+    "Update-Custom-Property": "sha256:781aaaab41c1ab5958062dc393d02b1df2ef2a09a28d3c4f21ae3177f4f53c86",
+    "Update-Dashboard": "sha256:2cc179ba75eda476ba7488f01503d947f023a4460aa98c4806ef0ab10c3b3ce8",
+    "Update-Experiment": "sha256:52ebf7595e48a40e218ff463ed72942a4818abc3ce93d8da6fafa8d358326437",
+    "Update-Feature-Flag": "sha256:9b34b19164168938d08a75d268c9becf8d189c85a1789a45061ae304041faf7c",
+    "Update-Lookup-Table": "sha256:ef28f1ec9c9484a7a53b5e2b6659e70f79a8e71e55bda17025aa4ab3c23b6a63",
+    "Update-Metric": "sha256:739bb6abdab19282afd4a6644a96183daabe9098a5322c44a77b840608a5ee9d",
+};
 /**
  * The manifest this release reviewed: both lists in one place, which is what
  * makes the classification the connector applies and the drift check that runs
- * beside it the same fact (P13). No schema digests yet — no release has read
- * Mixpanel's live schemas and written them down, and an invented digest would
- * report a change that never happened. `npm run drift:check -- --record` reads
- * them from a live project and prints the block to paste in
- * ([#351](https://github.com/zackbart/connecta/issues/351)).
+ * beside it the same fact (P13). The 2026-08-13 read-only audit recorded all
+ * 63 live US schemas, so a later change is named by the maintainer-run drift
+ * check rather than rediscovered in production (#395).
  *
  * Exported because the maintainer-run check compares against this manifest and
  * *names* what moved, which the runtime check deliberately cannot.
@@ -94,6 +158,7 @@ const WRITE_TOOLS = new Map([
 export const MIXPANEL_VETTED_CATALOG = vettedCatalog({
     reads: READ_ONLY_TOOLS,
     writes: WRITE_TOOLS,
+    schemaDigests: MIXPANEL_SCHEMA_DIGESTS,
 });
 const REGION_COPY = {
     us: "US",
@@ -116,6 +181,9 @@ Account purpose: ${purpose}
 - Start with \`Get-Projects\`, then use \`Get-Business-Context\` for the selected project before interpreting its events or metrics.
 - Resolve ids before acting; never guess one. \`Get-Projects\` yields the project id every other call is scoped by, and \`List-Dashboards\`, \`List-Cohorts\`, \`List-Metrics\`, \`List-Experiments\`, and \`List-Feature-Flags\` yield the ids their \`Get-\`, \`Update-\`, and \`Delete-\` counterparts expect.
 - Discover names with \`Get-Events\`, \`List-Properties\`, and \`Get-Property-Values\`; do not guess event or property spelling.
+- \`Get-Business-Context\` requires either \`project_id\` or \`organization_id\`. Its schema marks both optional, but the hosted tool rejects a call with neither.
+- \`Get-Property-Values\` requires \`properties\` or the deprecated \`property\` alias. Event property values also require \`event\`; prefer \`properties\` and never send both property forms with conflicting values.
+- \`List-Properties\` accepts \`names\` or \`query\`, never both. Use exact \`names\` for known properties and \`query\` for substring discovery.
 - For a new analysis, fetch \`Get-Query-Schema\` before \`Run-Query\`. Reduce query results inside \`execute_code\` before returning them.
 - Use \`Get-Report\` when the request names an existing saved report. Use \`Run-Query\` for a new question.
 - This account's tool list is not a fixed set. Mixpanel gates parts of its MCP catalog by plan and beta enrollment — experiments, feature flags, session replay, and issue triage are the usual absentees — so search this connector for what it actually exposes rather than assuming a documented tool is here.

package/dist/providers/stripe.d.ts

@@ -1,37 +1,37 @@
 import { type RemoteMcpAuth } from "../connectors/remote-mcp.js";
 import type { Connector } from "../types.js";
-/**
- * Which Stripe environment this instance speaks to. Required, and deliberately
- * undefaulted: there is no safe guess between an account that moves real money
- * and one that does not.
- */
+/** Which Stripe environment a static credential reaches. */
 export type StripeMode = "production" | "sandbox";
-/** Stripe publishes one hosted MCP endpoint; the credential selects the mode. */
+/** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export declare const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
-export interface StripeOptions {
-    /**
-     * Which Stripe environment this connector reaches. Shapes the title,
-     * description, guide, and admission budget, and is checked against a
-     * recognizable key prefix in `auth` headers.
-     */
-    mode: StripeMode;
-    /** Human-readable display name; defaults to "Stripe (<mode>)". */
+interface StripeCommonOptions {
+    /** Human-readable display name; defaults to "Stripe" for OAuth. */
     title?: string;
-    /** Which business this account bills for, and what it may be asked. */
+    /** Which business purpose and Stripe context this connector is for. */
     purpose: string;
-    /** OAuth by default; static headers support restricted API keys. */
-    auth?: RemoteMcpAuth;
-    /**
-     * Connect platform only: act as this connected account (`acct_...`) by
-     * sending Stripe's `Stripe-Account` header. Stripe does not support OAuth on
-     * connected-account calls, so this requires `headers` auth.
-     */
-    connectedAccount?: string;
-    /** Account-specific conventions appended to the maintained provider guide. */
+    /** Connector-specific conventions appended to the maintained provider guide. */
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
 }
+/** OAuth sessions discover account and mode together from Stripe's live tools. */
+export interface StripeOAuthOptions extends StripeCommonOptions {
+    auth?: {
+        type: "oauth";
+    };
+    mode?: never;
+    connectedAccount?: never;
+}
+/** Static credentials have one fixed mode, including Stripe Connect calls. */
+export interface StripeHeaderOptions extends StripeCommonOptions {
+    auth: Extract<RemoteMcpAuth, {
+        type: "headers";
+    }>;
+    mode: StripeMode;
+    /** Act as one Connect account by sending Stripe's `Stripe-Account` header. */
+    connectedAccount?: string;
+}
+export type StripeOptions = StripeOAuthOptions | StripeHeaderOptions;
 /**
  * The manifest this release reviewed: both lists in one place, which is what
  * makes the classification the connector applies and the drift check that runs
@@ -47,3 +47,4 @@ export interface StripeOptions {
 export declare const STRIPE_VETTED_CATALOG: import("../catalog-drift.js").VettedCatalog;
 /** A maintained Stripe hosted-MCP connection. */
 export declare function stripe(id: string, options: StripeOptions): Connector;
+export {};

package/dist/providers/stripe.js

@@ -1,6 +1,6 @@
 import { remoteMcp, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
-/** Stripe publishes one hosted MCP endpoint; the credential selects the mode. */
+/** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
 /**
  * Stripe documents no MCP-specific rate limit, so this transcribes the account
@@ -89,9 +89,9 @@ const TEST_KEY = /\b(?:sk|rk|pk)_test_/;
  * Refuse a deployment whose declared mode and supplied key disagree.
  *
  * This is the one half of production/sandbox routing connecta can actually
- * enforce. Nothing here reads or reports key material: an unrecognizable
- * credential (OAuth, or a key shape this release does not know) is left alone
- * rather than guessed at, and a mismatch names only the two modes.
+ * enforce. Nothing here reads or reports key material: an unrecognizable key
+ * shape is left alone rather than guessed at, and a mismatch names only the
+ * two modes.
  */
 function assertModeMatchesKey(id, mode, auth) {
     if (auth.type !== "headers")
@@ -125,43 +125,64 @@ function resolveAuth(id, options) {
         headers: { ...auth.headers, "Stripe-Account": connectedAccount },
     };
 }
+const OAUTH_ADMISSION = STRIPE_ADMISSION.sandbox;
+function oauthUsageGuide(purpose, instructions) {
+    const accountInstructions = instructions?.trim();
+    return `# Stripe usage
+
+Scope: live and sandbox accounts. Connector purpose: ${purpose}
+
+This OAuth session may expose both live and sandbox Stripe accounts. Call \`list_available_accounts_or_orgs\`, then carry its exact \`stripe_context\` and \`livemode\` into every account-scoped call. A live-mode write moves real money; a sandbox write changes test data. Never infer the account or mode from connector metadata.
+
+- Call \`list_available_accounts_or_orgs\` before every account-scoped read or write. Select the intended result, then carry its \`stripe_context\` and \`livemode\` unchanged. If the account, mode, or supported selector is ambiguous, stop and ask; never guess.
+- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a separate connector with a deployment-configured restricted key plus Stripe's documented \`Stripe-Account\` header; OAuth does not support that path.
+${sharedUsageGuide("100 requests per second in live mode and 25 in sandbox mode")}
+${accountInstructions
+        ? `\n## Account instructions\n\n${accountInstructions}\n`
+        : ""}`;
+}
 const MODE_COPY = {
     production: {
         title: "Stripe (production)",
         blurb: "production — live money and real customers",
-        warning: "This is a PRODUCTION account. Every write moves real money against real customers, and a refund cannot be undone. If a request could plausibly be a rehearsal, route it to a sandbox connector instead.",
+        warning: "This is a PRODUCTION Stripe connection. Every write moves real money against real customers, and a refund cannot be undone. If a request could plausibly be a rehearsal, route it to a sandbox connector instead.",
     },
     sandbox: {
         title: "Stripe (sandbox)",
         blurb: "sandbox — test data, no real money",
-        warning: "This is a SANDBOX account. Nothing here is real money and none of these objects exist in production, so never answer a question about live revenue, payouts, or a named customer from this connector.",
+        warning: "This is a SANDBOX Stripe connection. Nothing here is real money and none of these objects exist in production, so never answer a question about live revenue, payouts, or a named customer from this connector.",
     },
 };
-function usageGuide(mode, purpose, instructions) {
+function fixedModeUsageGuide(mode, purpose, instructions) {
     const copy = MODE_COPY[mode];
     const accountInstructions = instructions?.trim();
-    const rate = mode === "production" ? "100" : "25";
     return `# Stripe usage
 
-Mode: ${mode}. Account purpose: ${purpose}
+Mode: ${mode}. Connector purpose: ${purpose}
 
 ${copy.warning}
 
+- Organization accounts are not Stripe Connect connected accounts. A Connect call requires a deployment-configured restricted key plus Stripe's documented \`Stripe-Account\` header; OAuth does not support that path. Do not try to turn an organization-account call into a Connect call inside tool arguments.
+${sharedUsageGuide(`${mode === "production" ? "100" : "25"} requests per second`)}
+${accountInstructions
+        ? `\n## Account instructions\n\n${accountInstructions}\n`
+        : ""}`;
+}
+function sharedUsageGuide(rate) {
+    return `
 - Four generic tools reach any Stripe API method. Find the method with \`stripe_api_search\`, read its parameters with \`stripe_api_details\`, then call \`stripe_api_read\` (GET) or \`stripe_api_write\` (POST/PATCH/PUT/DELETE). Never guess a path or a parameter name — \`stripe_api_details\` is cheaper than a rejected write.
-- Prefer a dedicated tool when one covers the task: \`get_stripe_account_info\` for which account this is, \`get_balance_summary\` for balances, \`create_refund\` for refunds, \`stripe_report\` for reports. One call instead of three, and a refund named \`create_refund\` reads far more clearly in the approval a human sees than the same refund buried in \`stripe_api_write\` arguments.
+- Prefer a dedicated tool when one covers the task: \`get_stripe_account_info\` for account information, \`get_balance_summary\` for balances, \`create_refund\` for refunds, \`stripe_report\` for reports. One call instead of three, and a refund named \`create_refund\` reads far more clearly in the approval a human sees than the same refund buried in \`stripe_api_write\` arguments.
 - \`stripe_api_write\` carries the blast radius of the entire write API — every POST, PATCH, PUT, and DELETE, from a customer edit to a subscription cancellation. State the method and path explicitly; expect approval on every call.
 - Lists are cursor-paginated: \`limit\` defaults to 10 and caps at 100, \`starting_after\` and \`ending_before\` take an object id and are mutually exclusive, and \`has_more\` says whether to continue. Page inside \`execute_code\` and reduce before returning.
 - Resolve ids before acting; never guess one. Stripe ids are typed prefixes — \`cus_\` customer, \`sub_\` subscription, \`ch_\` charge, \`pi_\` payment intent, \`in_\` invoice, \`acct_\` account — and a plausible-looking id belongs to a different object or to nobody. Find the object with \`stripe_api_search\` (or a list endpoint through \`stripe_api_read\`) and carry the \`id\` it returned into the write.
-- This account's tool list is not a fixed set. Stripe gates parts of its MCP catalog by account, integration, and beta enrollment, so search this connector for what it actually exposes rather than assuming a documented tool is here.
+- This connection's tool list is not a fixed set. Stripe gates parts of its MCP catalog by account, integration, and beta enrollment, so search this connector for what it actually exposes rather than assuming a documented tool is here.
 - Amounts are integers in the currency's minor unit: \`1099\` is 10.99 USD, and zero-decimal currencies like JPY take \`10\` for 10 JPY. Never send a decimal.
 - Send an \`Idempotency-Key\` on every write you might retry, if the tool accepts it, and reuse the same key for the retry. A retry with a fresh key is a second charge, not a second attempt.
-- Stripe answers a rate limit with \`429\` and a \`Stripe-Rate-Limited-Reason\` header; back off on that rather than retrying immediately. This account's documented ceiling is ${rate} requests per second, and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.
+- Stripe answers a rate limit with \`429\` and a \`Stripe-Rate-Limited-Reason\` header; back off on that rather than retrying immediately. Stripe documents an account ceiling of ${rate}, and any single endpoint is capped at 25 per second regardless of mode, so paging one list is the real constraint.
 - Use \`search_stripe_documentation\` when the shape of an object or a flow is unclear; it is a read and costs nothing but a call.
 - Treat every create, update, delete, refund, and report run as a write. Connecta routes the maintained write catalog through \`call_destructive_tool\`; newly added tools also fail closed until classified.
 - An \`auth_required\` failure means this connector's Stripe authorization is missing or expired: run \`authorize_connector\` for this connector id, then retry the same call unchanged. A rejected argument or a plan restriction comes back in Stripe's own words instead — read it rather than re-authorizing.
-${accountInstructions
-        ? `\n## Account instructions\n\n${accountInstructions}\n`
-        : ""}`;
+`;
 }
 /** A maintained Stripe hosted-MCP connection. */
 export function stripe(id, options) {
@@ -169,32 +190,40 @@ export function stripe(id, options) {
     if (!purpose) {
         throw new Error("stripe() requires a non-empty account purpose.");
     }
-    const mode = options.mode;
-    if (mode !== "production" && mode !== "sandbox") {
-        throw new Error(`stripe("${id}") requires mode "production" or "sandbox".`);
-    }
     const auth = resolveAuth(id, options);
-    assertModeMatchesKey(id, mode, auth);
-    const copy = MODE_COPY[mode];
+    const mode = "mode" in options ? options.mode : undefined;
+    if (auth.type === "oauth" && mode !== undefined) {
+        throw new Error(`stripe("${id}") cannot declare a connector-wide mode for OAuth; Stripe returns mode with each account.`);
+    }
+    if (auth.type === "headers" && mode !== "production" && mode !== "sandbox") {
+        throw new Error(`stripe("${id}") with headers auth requires mode "production" or "sandbox".`);
+    }
+    if (auth.type === "headers") {
+        assertModeMatchesKey(id, mode, auth);
+    }
+    const copy = mode === undefined ? undefined : MODE_COPY[mode];
     const connector = remoteMcp(id, {
         url: STRIPE_MCP_ENDPOINT,
-        title: options.title ?? copy.title,
-        description: `Stripe payments (${copy.blurb}) — ${purpose}`,
+        title: options.title ?? copy?.title ?? "Stripe",
+        description: mode === undefined
+            ? `Stripe payments (live and sandbox accounts) — ${purpose}`
+            : `Stripe payments (${copy?.blurb}) — ${purpose}`,
         auth,
         requireHttps: true,
-        callAdmission: STRIPE_ADMISSION[mode],
+        callAdmission: mode === undefined ? OAUTH_ADMISSION : STRIPE_ADMISSION[mode],
         usageGuide: {
-            content: usageGuide(mode, purpose, options.instructions),
-            // Explicit rather than derived: production versus sandbox is the fact an
-            // agent must not get wrong, and the derived summary would be the
-            // "Mode: … Account purpose: …" line with the operator's prose eating the
-            // budget ([#342](https://github.com/zackbart/connecta/issues/342)).
-            summary: mode === "production"
-                ? "PRODUCTION: writes move real money. Generic api tools, id prefixes, minor units, idempotency."
-                : "Sandbox: test data only, never live figures. Generic api tools, id prefixes, minor units.",
-            // Not `required`. The four generic tools are the routing decision, and
-            // the mode warning already rides the title and description; a guide
-            // forced into every call would pay for the same paragraph repeatedly.
+            content: mode === undefined
+                ? oauthUsageGuide(purpose, options.instructions)
+                : fixedModeUsageGuide(mode, purpose, options.instructions),
+            // Explicit rather than derived: fixed credentials must lead with mode,
+            // while OAuth must lead with its account-scoped selector pair.
+            summary: mode === undefined
+                ? "Live and sandbox Stripe accounts. List accounts; carry the returned stripe_context and livemode before acting."
+                : mode === "production"
+                    ? "PRODUCTION: real money. This static credential has one fixed live-mode scope."
+                    : "Sandbox: test data only. This static credential has one fixed sandbox scope.",
+            // Not `required`. The four generic tools are the routing decision; a
+            // guide forced into every call would pay for the same prose repeatedly.
         },
         ...(options.maxResultBytes !== undefined
             ? { maxResultBytes: options.maxResultBytes }

package/dist/registry.d.ts

@@ -1,4 +1,5 @@
 import type { CatalogDriftReport, Connector, ConnectorContext, ConnectorStatus, KVStorage, Logger, ToolDef } from "./types.js";
+import { type DeferredWork } from "./connector-scope.js";
 import { type CatalogDriftActivityContext } from "./activity.js";
 import { type CredentialVault } from "./credentials.js";
 import { type CallAdmissionPermit, type ConnectorCallAdmissionSnapshot } from "./call-admission.js";
@@ -70,6 +71,12 @@ export interface RegistryOptions {
     catalogDriftActivity?: Omit<CatalogDriftActivityContext, "logger">;
 }
 export type ConnectorOperationOptions = Pick<ConnectorContext, "signal" | "timeoutMs">;
+/** Agent-only catalog behavior. This never enters a ConnectorContext. */
+export interface CatalogReadOptions {
+    defer?: DeferredWork;
+    /** Fresh deadline for a deferred refresh; never an inbound signal. */
+    refreshTimeoutMs: number;
+}
 /**
  * The registry surface a per-connection MCP server consumes: every meta-tool
  * (`src/meta-tools.ts`) and the `execute_code` sandbox bridge (`src/execute.ts`)
@@ -88,7 +95,7 @@ export interface RegistryView {
         connector: Connector;
         toolName: string;
     } | null;
-    getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
+    getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, readOptions?: CatalogReadOptions): Promise<ToolDef[]>;
     refreshTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
     peekTools(id: string): ToolDef[] | undefined;
     contextFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): ConnectorContext;
@@ -126,6 +133,10 @@ export declare class Registry implements RegistryView {
     private readonly catalogMutations;
     /** Same-request cold loads share one promise without retaining the request. */
     private readonly requestCatalogLoads;
+    /** One live refresh per connector across agent and operator requests. */
+    private readonly catalogRefreshes;
+    /** Last payload-free agent catalog access in this runtime. */
+    private readonly catalogAccess;
     /** Deployment-wide observations — every call, whatever view made it. */
     private readonly health;
     /** Last drift counts reported to activity, per connector, in this runtime. */
@@ -215,21 +226,33 @@ export declare class Registry implements RegistryView {
      * the catalog and resurrect the pre-change listing.
      */
     private enqueueCatalogMutation;
+    private refreshToolsWithContext;
+    /**
+     * Publish one shared refresh promise before starting its connector work.
+     * The first caller owns the scope and deadline; every later caller joins the
+     * result without gaining access to that context.
+     */
+    private startCatalogRefresh;
     /** Force a live listTools refresh and replace both catalog cache layers. */
     refreshTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
+    private observeCatalogAccess;
+    /**
+     * Start or join one shared refresh. A newly deferred task owns its scope,
+     * deadline, and teardown; no inbound signal or request scope crosses into it.
+     */
+    private deferCatalogRefresh;
     /** Cached listTools with in-memory + persisted serializable catalog layers. */
     private loadTools;
     /**
-     * Coalesce one connector's cold load inside one inbound request. The WeakMap
-     * neither roots the request scope nor lets its connector context escape into
-     * another request; settled entries are also removed eagerly.
+     * Coalesce one connector's catalog traversal inside one inbound request. The
+     * WeakMap neither roots the request scope nor lets its connector context
+     * escape into another request; settled entries are also removed eagerly.
      *
-     * The first caller's `callOptions` govern the shared load: a later caller's
-     * signal or timeout neither cancels nor extends it, and an abort by the
-     * first caller rejects every coalesced caller. Within one request that is
-     * the deal being made — one fetch, one deadline.
+     * The deployment-wide flight below this layer coalesces the actual live
+     * refresh across requests. Its first caller's context and deadline govern;
+     * later callers join only its result, never its request scope.
      */
-    getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
+    getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, readOptions?: CatalogReadOptions): Promise<ToolDef[]>;
     /** Return a cached catalog without performing storage or network I/O. */
     peekTools(id: string): ToolDef[] | undefined;
     recordSuccess(id: string, latencyMs: number): void;