@zackbart/connecta 0.16.1 → 0.17.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

@@ -17,7 +17,7 @@ export interface StripeOptions {
     mode: StripeMode;
     /** Human-readable display name; defaults to "Stripe (<mode>)". */
     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;
@@ -27,7 +27,7 @@ export interface StripeOptions {
      * 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;

package/dist/providers/stripe.js

@@ -129,12 +129,12 @@ 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) {
@@ -143,19 +143,22 @@ function usageGuide(mode, purpose, instructions) {
     const rate = mode === "production" ? "100" : "25";
     return `# Stripe usage
 
-Mode: ${mode}. Account purpose: ${purpose}
+Mode: ${mode}. Connector purpose: ${purpose}
 
 ${copy.warning}
 
+- One OAuth session may cover more than one account in the same Stripe organization. The connector id, title, and purpose state routing intent; they do not prove which account a call will use.
+- Before every account-scoped read or write, resolve the intended organization account. Inspect the chosen tool's live input schema and carry the exact account or context field it exposes. If the account or its supported selection mechanism is ambiguous, stop and ask; never guess from the connector metadata, invent an MCP argument, or add a request header the live contract does not expose.
+- 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.
 - 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} requests per second, 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.
@@ -186,12 +189,11 @@ export function stripe(id, options) {
         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)).
+            // agent must not get wrong. Multi-account OAuth also has to reach browse
+            // before connector metadata can be mistaken for authenticated identity.
             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.",
+                ? "PRODUCTION: real money. OAuth may span organization accounts; resolve the account from live schemas before acting."
+                : "Sandbox: test data only. OAuth may span organization accounts; resolve the account from live schemas before acting.",
             // 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.

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;

package/dist/registry.js

@@ -1,3 +1,4 @@
+import { closeConnectorScope, } from "./connector-scope.js";
 import { recordCatalogDriftActivity, } from "./activity.js";
 import { storedCredentialShape, } from "./credentials.js";
 import { ConnectorCallError } from "./errors.js";
@@ -6,6 +7,8 @@ import { boundedCatalogDrift } from "./catalog-drift.js";
 import { fingerprintSerializedCatalog, snapshotCatalog, } from "./catalog-fingerprint.js";
 import { MAX_CATALOG_CHUNK_BYTES, MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES, } from "./catalog-limits.js";
 import { mapSettledWithConcurrency } from "./concurrency.js";
+import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, } from "./skills.js";
+import { withAbortableTimeout } from "./timeout.js";
 const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
@@ -122,6 +125,10 @@ export class Registry {
     catalogMutations = new Map();
     /** Same-request cold loads share one promise without retaining the request. */
     requestCatalogLoads = new WeakMap();
+    /** One live refresh per connector across agent and operator requests. */
+    catalogRefreshes = new Map();
+    /** Last payload-free agent catalog access in this runtime. */
+    catalogAccess = new Map();
     /** Deployment-wide observations — every call, whatever view made it. */
     health = new HealthLog();
     /** Last drift counts reported to activity, per connector, in this runtime. */
@@ -146,6 +153,16 @@ export class Registry {
             if (this.connectors.has(c.id)) {
                 throw new Error(`Duplicate connector id "${c.id}"`);
             }
+            const configuredGuideSummary = typeof c.usageGuide === "object"
+                ? normalizeGuideSummary(c.usageGuide.summary ?? "")
+                : undefined;
+            if (configuredGuideSummary !== undefined &&
+                configuredGuideSummary.length > GUIDE_SUMMARY_LENGTH) {
+                throw new Error(`Connector "${c.id}" usageGuide.summary is ` +
+                    `${configuredGuideSummary.length} characters after whitespace ` +
+                    `normalization; the discovery bound is ${GUIDE_SUMMARY_LENGTH}. ` +
+                    "Shorten it or omit it to derive one.");
+            }
             this.connectors.set(c.id, c);
             if (c.callAdmission) {
                 this.callAdmission.set(c.id, new ConnectorCallAdmissionController(c.id, c.callAdmission));
@@ -592,19 +609,20 @@ export class Registry {
             .catch(() => { });
         return next;
     }
-    /** Force a live listTools refresh and replace both catalog cache layers. */
-    async refreshTools(id, baseUrl, requestScope, callOptions = {}) {
-        const connector = this.connectors.get(id);
-        if (!connector)
-            throw new Error(`Unknown connector "${id}"`);
-        if (connector.staticTools)
-            return connector.staticTools;
+    async refreshToolsWithContext(id, connector, ctx, skipPublicationWhenAborted = false) {
         const generation = this.catalogGeneration(id);
-        const tools = await connector.listTools(this.contextFor(id, baseUrl, requestScope, callOptions));
+        const tools = await connector.listTools(ctx);
         // The listing a maintained proxy just served is also the only catalog
         // comparison connecta ever makes. It rides this refresh whether or not the
         // result reaches a cache, because what drifted drifted.
         this.observeCatalogDrift(connector);
+        // A deferred deadline may close the owned scope while a connector that
+        // ignores abort is still listing. The completed list remains a valid drift
+        // observation, but must not overwrite a newer same-generation refresh.
+        // Blocking callers do not set this flag and retain their prior publication
+        // behavior when an inbound abort races a completed listing.
+        if (skipPublicationWhenAborted && ctx.signal?.aborted)
+            return tools;
         // The caller that began this refresh may still use its result, but a
         // credential/OAuth change that landed while listTools was in flight means
         // the listing must not enter either shared cache layer.
@@ -618,8 +636,10 @@ export class Registry {
         }
         const previous = this.cache.get(id);
         const snapshot = await snapshotCatalog(tools);
-        if (generation !== this.catalogGeneration(id))
+        if (generation !== this.catalogGeneration(id) ||
+            (skipPublicationWhenAborted && ctx.signal?.aborted)) {
             return tools;
+        }
         if (snapshot.serializedBytes.byteLength > MAX_SERIALIZED_CATALOG_BYTES) {
             const message = `Connector "${id}" returned a ${snapshot.serializedBytes.byteLength}-byte ` +
                 `serialized catalog, over the ${MAX_SERIALIZED_CATALOG_BYTES}-byte ceiling; ` +
@@ -653,8 +673,106 @@ export class Registry {
         }
         return tools;
     }
+    /**
+     * 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.
+     */
+    startCatalogRefresh(id, generation, start, finish) {
+        const existing = this.catalogRefreshes.get(id);
+        if (existing?.generation === generation)
+            return existing;
+        let resolveWork;
+        let rejectWork;
+        const work = new Promise((resolve, reject) => {
+            resolveWork = resolve;
+            rejectWork = reject;
+        });
+        let flight;
+        const promise = work
+            .finally(async () => {
+            if (finish)
+                await finish();
+        })
+            .finally(() => {
+            if (this.catalogRefreshes.get(id) === flight) {
+                this.catalogRefreshes.delete(id);
+            }
+        });
+        flight = { generation, promise };
+        this.catalogRefreshes.set(id, flight);
+        try {
+            Promise.resolve(start()).then(resolveWork, rejectWork);
+        }
+        catch (err) {
+            rejectWork(err);
+        }
+        return flight;
+    }
+    /** Force a live listTools refresh and replace both catalog cache layers. */
+    async refreshTools(id, baseUrl, requestScope, callOptions = {}) {
+        const connector = this.connectors.get(id);
+        if (!connector)
+            throw new Error(`Unknown connector "${id}"`);
+        if (connector.staticTools)
+            return connector.staticTools;
+        const ctx = this.contextFor(id, baseUrl, requestScope, callOptions);
+        return this.startCatalogRefresh(id, this.catalogGeneration(id), () => this.refreshToolsWithContext(id, connector, ctx)).promise;
+    }
+    observeCatalogAccess(id, state) {
+        this.catalogAccess.set(id, {
+            state,
+            observedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * 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.
+     */
+    deferCatalogRefresh(id, baseUrl, expectedGeneration, options) {
+        const connector = this.connectors.get(id);
+        if (!connector || connector.staticTools || !options.defer)
+            return;
+        let flight = this.catalogRefreshes.get(id);
+        if (flight?.generation !== expectedGeneration)
+            flight = undefined;
+        if (!flight) {
+            const requestScope = {};
+            let ctx;
+            flight = this.startCatalogRefresh(id, expectedGeneration, () => withAbortableTimeout((signal) => {
+                const current = this.cache.get(id);
+                if (current && current.exp > Date.now()) {
+                    return Promise.resolve(current.tools);
+                }
+                if (expectedGeneration !== this.catalogGeneration(id) ||
+                    this.invalidated.has(id)) {
+                    return Promise.reject(new Error(`Deferred catalog refresh of "${id}" was invalidated before it started.`));
+                }
+                ctx = this.contextFor(id, baseUrl, requestScope, {
+                    signal,
+                    timeoutMs: options.refreshTimeoutMs,
+                });
+                return this.refreshToolsWithContext(id, connector, ctx, true);
+            }, options.refreshTimeoutMs, `deferred catalog refresh of "${id}"`), async () => {
+                if (ctx)
+                    await closeConnectorScope(connector, ctx, options.defer);
+            });
+        }
+        if (!flight.deferredTail) {
+            // Attach the rejection handler before handing the tail to waitUntil.
+            flight.deferredTail = flight.promise.then(() => { }, (err) => {
+                this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh failed: ${msg(err)}`);
+            });
+        }
+        try {
+            options.defer(flight.deferredTail);
+        }
+        catch (err) {
+            this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh could not attach to the runtime: ${msg(err)}`);
+        }
+    }
     /** Cached listTools with in-memory + persisted serializable catalog layers. */
-    async loadTools(id, baseUrl, requestScope, callOptions = {}) {
+    async loadTools(id, baseUrl, requestScope, callOptions = {}, readOptions) {
         const connector = this.connectors.get(id);
         if (!connector)
             throw new Error(`Unknown connector "${id}"`);
@@ -663,9 +781,14 @@ export class Registry {
         const now = Date.now();
         const requestGeneration = this.catalogGeneration(id);
         const hit = this.cache.get(id);
-        if (hit && hit.exp > now)
+        if (hit && hit.exp > now) {
+            if (readOptions?.defer)
+                this.observeCatalogAccess(id, "fresh");
             return hit.tools;
-        let stale = hit && hit.staleUntil > now ? hit.tools : undefined;
+        }
+        let stale = hit && hit.staleUntil > now
+            ? { tools: hit.tools, staleUntil: hit.staleUntil }
+            : undefined;
         if (this.persistToolCatalog && !this.invalidated.has(id)) {
             const generation = this.catalogGeneration(id);
             let persisted = null;
@@ -679,49 +802,95 @@ export class Registry {
                 persisted = null;
                 stale = undefined;
             }
-            if (persisted && persisted.staleUntil > now) {
+            // Storage can yield while another request finishes a live refresh. Read
+            // the shared cache again before an older manifest gets any authority.
+            // The candidate with the later fresh deadline wins; both candidates have
+            // already passed their own fingerprint and completeness checks.
+            const reconciledAt = Date.now();
+            const current = this.cache.get(id);
+            const usableCurrent = current && current.staleUntil > reconciledAt ? current : undefined;
+            if (usableCurrent) {
+                stale = {
+                    tools: usableCurrent.tools,
+                    staleUntil: usableCurrent.staleUntil,
+                };
+                if (usableCurrent.exp > reconciledAt) {
+                    if (readOptions?.defer)
+                        this.observeCatalogAccess(id, "fresh");
+                    return usableCurrent.tools;
+                }
+            }
+            if (persisted &&
+                persisted.staleUntil > reconciledAt &&
+                (!usableCurrent || persisted.expiresAt > usableCurrent.exp)) {
                 this.cache.set(id, {
                     tools: persisted.tools,
                     fingerprint: persisted.fingerprint,
                     exp: persisted.expiresAt,
                     staleUntil: persisted.staleUntil,
                 });
-                if (persisted.expiresAt > now)
+                if (persisted.expiresAt > reconciledAt) {
+                    if (readOptions?.defer)
+                        this.observeCatalogAccess(id, "fresh");
                     return persisted.tools;
-                stale = persisted.tools;
+                }
+                stale = {
+                    tools: persisted.tools,
+                    staleUntil: persisted.staleUntil,
+                };
+            }
+        }
+        if (stale &&
+            stale.staleUntil > Date.now() &&
+            readOptions?.defer &&
+            requestGeneration === this.catalogGeneration(id) &&
+            !this.invalidated.has(id)) {
+            this.deferCatalogRefresh(id, baseUrl, requestGeneration, readOptions);
+            // Invalidation can land synchronously while the refresh is attached.
+            // Repeat the authority check at the exact stale publication point.
+            if (stale.staleUntil > Date.now() &&
+                requestGeneration === this.catalogGeneration(id) &&
+                !this.invalidated.has(id)) {
+                this.observeCatalogAccess(id, "stale");
+                return stale.tools;
             }
         }
         try {
-            return await this.refreshTools(id, baseUrl, requestScope, callOptions);
+            const tools = await this.refreshTools(id, baseUrl, requestScope, callOptions);
+            if (readOptions?.defer)
+                this.observeCatalogAccess(id, "fresh");
+            return tools;
         }
         catch (err) {
             if (stale &&
+                stale.staleUntil > Date.now() &&
                 requestGeneration === this.catalogGeneration(id) &&
                 !this.invalidated.has(id)) {
+                if (readOptions?.defer)
+                    this.observeCatalogAccess(id, "stale");
                 this.opts.logger.warn(`[connecta] connector "${id}" catalog refresh failed; serving stale catalog: ${msg(err)}`);
-                return stale;
+                return stale.tools;
             }
             throw err;
         }
     }
     /**
-     * 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.
      */
-    async getTools(id, baseUrl, requestScope, callOptions = {}) {
+    async getTools(id, baseUrl, requestScope, callOptions = {}, readOptions) {
         const connector = this.connectors.get(id);
         if (!connector)
             throw new Error(`Unknown connector "${id}"`);
         if (connector.staticTools)
             return connector.staticTools;
         if (!requestScope) {
-            return this.loadTools(id, baseUrl, requestScope, callOptions);
+            return this.loadTools(id, baseUrl, requestScope, callOptions, readOptions);
         }
         let loads = this.requestCatalogLoads.get(requestScope);
         if (!loads) {
@@ -731,7 +900,7 @@ export class Registry {
         const existing = loads.get(id);
         if (existing)
             return existing;
-        const loading = this.loadTools(id, baseUrl, requestScope, callOptions);
+        const loading = this.loadTools(id, baseUrl, requestScope, callOptions, readOptions);
         loads.set(id, loading);
         try {
             return await loading;
@@ -796,24 +965,39 @@ export class Registry {
         // The report is rebuilt rather than spread through: what the seam returned
         // is third-party output, and status is read by the operator UI and copied
         // into responses.
-        const withDrift = (status) => {
+        const withObservations = (status) => {
             const report = boundedCatalogDrift(connector.catalogDrift?.());
-            return report ? { ...status, catalogDrift: report } : status;
+            const access = this.catalogAccess.get(id);
+            // Connector.status is an open plugin seam. Rebuild its public fields so
+            // a connector cannot smuggle payload through either registry-owned
+            // observation when this runtime has not made one.
+            const boundedStatus = {
+                state: status.state,
+                ...(status.authorizationUrl !== undefined
+                    ? { authorizationUrl: status.authorizationUrl }
+                    : {}),
+                ...(status.message !== undefined ? { message: status.message } : {}),
+            };
+            return {
+                ...boundedStatus,
+                ...(report ? { catalogDrift: report } : {}),
+                ...(access ? { catalogAccess: { ...access } } : {}),
+            };
         };
         if (connector.status) {
             try {
-                return withDrift(await connector.status(ctx));
+                return withObservations(await connector.status(ctx));
             }
             catch (err) {
-                return withDrift({ state: "error", message: msg(err) });
+                return withObservations({ state: "error", message: msg(err) });
             }
         }
         try {
             await this.getTools(id, baseUrl, requestScope, callOptions);
-            return withDrift({ state: "ok" });
+            return withObservations({ state: "ok" });
         }
         catch (err) {
-            return withDrift({ state: "error", message: msg(err) });
+            return withObservations({ state: "error", message: msg(err) });
         }
     }
     markCatalogInvalid(id) {