@zackbart/connecta 0.12.2 → 0.14.0

package/documentation/stripe.md

@@ -0,0 +1,202 @@
+# 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
+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",
+  instructions: "Never refund above $500 without a human in the loop.",
+});
+```
+
+The `id` owns the ordinary connector namespaces; use a different id for every
+Stripe account. `purpose` is required because an agent choosing between two
+instances needs to know which account answers the question. 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
+
+`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.
+
+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.
+
+`mode` shows up in four places an agent actually reads:
+
+- 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.
+
+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.
+
+Deploy both 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.
+
+```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",
+  }),
+]
+```
+
+## Authentication
+
+OAuth is the default and the option Stripe recommends: it supports dynamic
+client registration and PKCE, and each connector instance keeps its own flow
+and tokens in connector-scoped storage. Stripe also accepts a
+[restricted API key](https://docs.stripe.com/keys#create-restricted-api-key) as
+a bearer token for headless agents:
+
+```ts
+stripe("stripe_sandbox", {
+  mode: "sandbox",
+  purpose: "Automated billing rehearsal",
+  auth: {
+    type: "headers",
+    headers: { Authorization: `Bearer ${env.STRIPE_RESTRICTED_KEY}` },
+  },
+});
+```
+
+Use a restricted key, not a secret key, and scope it to the operations the
+agent actually needs; Stripe's own guidance is to "limit your agent's access to
+exactly the functionality it requires". Keep it in the runtime's secret store.
+
+Connect platforms can act as a connected account with `connectedAccount`, which
+adds Stripe's `Stripe-Account` header. Stripe does not support OAuth for
+connected-account calls, so this requires `headers` auth and throws otherwise:
+
+```ts
+stripe("merchant_42", {
+  mode: "production",
+  purpose: "Billing questions for the merchant on account 42",
+  connectedAccount: "acct_1234567890",
+  auth: {
+    type: "headers",
+    headers: { Authorization: `Bearer ${env.STRIPE_PLATFORM_KEY}` },
+  },
+});
+```
+
+Administrators must enable MCP access in the Stripe Dashboard, and Stripe
+manages that setting **separately for sandbox and live mode**. 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
+
+Stripe documents eleven tools on the hosted server. Seven are reads:
+
+`stripe_api_search`, `stripe_api_details`, `stripe_api_read`,
+`get_stripe_account_info`, `get_balance_summary`,
+`search_stripe_documentation`, `stripe_implementation_planner`.
+
+Four are writes:
+
+`stripe_api_write` and `create_refund` are classified destructive;
+`stripe_report` and `send_stripe_mcp_feedback` are additive.
+
+Two of those deserve a sentence. `stripe_api_read` is a read because Stripe
+documents it as the `GET` half of a generic pair — the tool is the read
+boundary, not whichever endpoint an agent names inside it, and its sibling
+`stripe_api_write` carries every `POST`, `PATCH`, `PUT`, and `DELETE`.
+`create_refund` is filed destructive despite its name: it reverses a settled
+charge and moves money back out, which is a mutation of something that already
+exists rather than a fresh object appearing beside it. Additive writes
+(`stripe_report`, `send_stripe_mcp_feedback`) leave `destructiveHint` unset;
+`readOnlyHint: false` already routes them through `call_destructive_tool`, and
+asserting destruction only inflates the approval copy the host shows a human.
+
+That classification is **fill-in only**, and unconditionally so: it supplies
+the annotations Stripe leaves unset — Stripe documents no MCP annotations at
+all — and contradicts an explicit downstream annotation in neither direction. A
+tool on the read allowlist arriving with `destructiveHint: true` or
+`readOnlyHint: false` keeps exactly what the downstream said and stays behind
+`call_destructive_tool`. A tool on neither maintained list arriving with
+`readOnlyHint: true` keeps that too, and stays callable from `execute_code`.
+Both are the downstream telling you this release's allowlist is stale, and on a
+name no release has reviewed its word is the only evidence there is. The one
+classification that still outranks the downstream is a name this release
+reviewed and filed destructive: a `create_refund` claiming `readOnlyHint: true`
+is a downstream bug rather than news, and stays on the approval path.
+
+An unfamiliar tool that annotates nothing fails closed onto
+`call_destructive_tool` until a Connecta release reviews it. That is not
+hypothetical here: Stripe's own MCP page still carries a `create_customer`
+example that its tool table no longer lists. Whatever the server actually
+serves, an unclassified and unannotated `create_customer` lands on the approval
+path. Expect the undocumented Treasury tools Stripe alludes to to arrive
+unclassified as well — annotated ones will be taken at their word.
+
+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
+request — expect it to be absent unless the account is allowlisted, and expect
+the other Treasury tools Stripe alludes to but does not document to arrive
+unclassified.
+
+## Rate limits
+
+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
+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.
+
+As with every connector policy this is a **best-effort approximation** of the
+provider's limit, not an enforcement of it. Each runtime keeps its own counter,
+so N Worker isolates or Node processes serving one deployment can each admit up
+to the stated rate, and the same Stripe account may be spending its budget on
+traffic Connecta never sees. Discovery traffic is outside connector call
+admission and still needs restrained use.
+
+## What is not verified
+
+Stripe's MCP documentation is silent on two things 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
+  tools' arguments is not documented. The guide states them because an agent
+  that ignores them is wrong either way.

package/ethos.md

@@ -15,9 +15,12 @@ order, and amending it is a design decision, not a drive-by edit.
 - **A deployment is a small config-as-code file.** Changing what agents can
   reach is an edit and a redeploy. One deployment, one tenant, one audience —
   more audiences means more deployments.
-- **Two equal ways in.** `remoteMcp()` proxies a downstream MCP server;
-  `api()` hand-writes a deliberate tool surface over a plain HTTP API. Both
-  come out identical: same addresses, same catalog, same safety rules.
+- **Curated when available, open when not.** Prefer an explicitly imported
+  prebuilt connection when Connecta maintains one: it carries the provider's
+  known-good endpoint, authentication defaults, tool ergonomics, and concise
+  usage guidance. `remoteMcp()` and `api()` remain equal, first-class
+  primitives for custom and unsupported integrations. Every path produces the
+  same `Connector`: same addresses, same catalog, same safety rules.
 - **Seven tools, an executor required.** The primary surface is a program, so
   every deployment runs an executor — a Dynamic Worker on Cloudflare, QuickJS
   behind its optional-peer subpath on Node — and one without refuses to boot
@@ -66,6 +69,8 @@ proposing one without a new argument is not.
 | Multi-tenancy / account model | refused | one deployment per tenant; deploy again instead |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | 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 never overrule an explicit one; `remoteMcp()` and `api()` stay first-class ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| 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 |
 | Resources & prompts aggregation | refused | tools only; connecta's own Apps shell is the one `resources/read` carve-out ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Elicitation passthrough | refused | no route through a stateless aggregator |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
@@ -64,6 +64,26 @@
     "./auth/clerk": {
       "types": "./dist/auth/clerk.d.ts",
       "import": "./dist/auth/clerk.js"
+    },
+    "./providers/cloudflare": {
+      "types": "./dist/providers/cloudflare.d.ts",
+      "import": "./dist/providers/cloudflare.js"
+    },
+    "./providers/linear": {
+      "types": "./dist/providers/linear.d.ts",
+      "import": "./dist/providers/linear.js"
+    },
+    "./providers/mixpanel": {
+      "types": "./dist/providers/mixpanel.d.ts",
+      "import": "./dist/providers/mixpanel.js"
+    },
+    "./providers/notion": {
+      "types": "./dist/providers/notion.d.ts",
+      "import": "./dist/providers/notion.js"
+    },
+    "./providers/stripe": {
+      "types": "./dist/providers/stripe.d.ts",
+      "import": "./dist/providers/stripe.js"
     }
   },
   "scripts": {

package/src/catalog-service.ts

@@ -25,6 +25,8 @@ import type {
 } from "./registry.js";
 import {
   connectorGuide,
+  connectorGuideRequired,
+  connectorGuideSummary,
   connectorSkillName,
 } from "./skills.js";
 import {
@@ -196,6 +198,7 @@ export interface CatalogDescribeArgs {
 interface CatalogSearchEntry {
   connector: Connector;
   guide?: string;
+  guideSummary?: string;
   tool: {
     name: string;
     address: string;
@@ -208,9 +211,34 @@ interface CatalogSearchEntry {
     requiredInputKeys?: string[];
     outputKeys?: string[];
     annotations?: ToolDef["annotations"];
+    guideRequired?: true;
+    guideRequiredReasons?: GuideRequiredReason[];
   };
 }
 
+type GuideRequiredReason =
+  | "connector_required"
+  | "approval_required"
+  | "schema_truncated";
+
+/**
+ * Reasons discovery can determine without reading arguments or guessing at a
+ * task. Summary-only conventions remain an agent decision; hard requirements
+ * are explicit and machine-readable.
+ */
+function guideRequiredReasons(
+  connector: Connector,
+  tool: ToolDef,
+  schemaTruncated: boolean,
+): GuideRequiredReason[] | undefined {
+  if (!connectorGuide(connector)) return undefined;
+  const reasons: GuideRequiredReason[] = [];
+  if (connectorGuideRequired(connector)) reasons.push("connector_required");
+  if (!isExplicitlyReadOnly(tool)) reasons.push("approval_required");
+  if (schemaTruncated) reasons.push("schema_truncated");
+  return reasons.length > 0 ? reasons : undefined;
+}
+
 /**
  * Code-mode key metadata for one match. Each half is omitted when its schema
  * does not resolve to an object shape, so a program reads "no metadata, use the
@@ -237,6 +265,19 @@ function schemaKeyMetadata(
   };
 }
 
+/**
+ * The classified-failure subset a scoped search may echo: enough to tell a
+ * transient outage from one an operator must clear, and nothing more. Kept as
+ * its own type rather than `CallErrorDetails` so widening the call-path
+ * classifier cannot widen this discovery-surface field by accident.
+ */
+interface CatalogFailureDetail {
+  code: string;
+  message: string;
+  retryable: boolean;
+  retryAfterMs?: number;
+}
+
 export interface CatalogSearchPage {
   entries: CatalogSearchEntry[];
   total: number;
@@ -253,6 +294,12 @@ export interface CatalogSearchPage {
     connectorScope?: string;
     unknownConnector?: true;
     unavailableConnectorCount?: number;
+    /** Bounded typed failure for an explicitly scoped unavailable catalog. */
+    catalogError?: CatalogFailureDetail;
+    guide?: string;
+    guideSummary?: string;
+    guideRequired?: true;
+    guideRequiredReasons?: GuideRequiredReason[];
     guidance?: string;
   };
 }
@@ -262,6 +309,9 @@ export interface CatalogDescription {
   name?: string;
   description?: string;
   guide?: string;
+  guideSummary?: string;
+  guideRequired?: true;
+  guideRequiredReasons?: GuideRequiredReason[];
   inputSchema?: unknown;
   outputSchema?: unknown;
   annotations?: ToolDef["annotations"];
@@ -656,10 +706,19 @@ export class CatalogService {
         match.tool.description,
         args.fullDescriptions === true,
       );
+      const requiredReasons = guideRequiredReasons(
+        match.connector,
+        match.tool,
+        renderedInput?.truncated === true || renderedOutput?.truncated === true,
+      );
+      const guideSummary = connectorGuideSummary(match.connector);
       return {
         connector: match.connector,
         ...(connectorGuide(match.connector)
-          ? { guide: connectorSkillName(match.connector.id) }
+          ? {
+              guide: connectorSkillName(match.connector.id),
+              ...(guideSummary ? { guideSummary } : {}),
+            }
           : {}),
         tool: {
           name: match.tool.name,
@@ -697,6 +756,12 @@ export class CatalogService {
           ...(match.tool.annotations
             ? { annotations: match.tool.annotations }
             : {}),
+          ...(requiredReasons
+            ? {
+                guideRequired: true as const,
+                guideRequiredReasons: requiredReasons,
+              }
+            : {}),
         },
       };
     });
@@ -732,6 +797,27 @@ export class CatalogService {
     const unavailableCatalogs = catalogs.filter(
       (catalog) => catalog.status === "rejected",
     ).length;
+    // Named field by field rather than spread: `CallErrorDetails` also carries
+    // connector, operation, recovery, and nextAction, and a discovery read is
+    // not a call — widening the classifier must not silently widen what a
+    // catalog search hands back.
+    const scopedCatalogError = ((): CatalogFailureDetail | undefined => {
+      if (!scopedConnector || catalogs[0]?.status !== "rejected") {
+        return undefined;
+      }
+      const error = classifyCallError(
+        catalogs[0].reason,
+        "catalog_lookup_failed",
+      );
+      return {
+        code: error.code,
+        message: boundedEchoText(error.message),
+        retryable: error.retryable,
+        ...(error.retryAfterMs === undefined
+          ? {}
+          : { retryAfterMs: error.retryAfterMs }),
+      };
+    })();
     const safetyLabel =
       safety === "readOnly"
         ? "read-only "
@@ -740,19 +826,58 @@ export class CatalogService {
           : "";
     const filterRecovery =
       safety === "all" ? "" : " Change safety to inspect the other tools.";
+    const scopedGuide =
+      matches.length === 0 && scopedConnector && connectorGuide(scopedConnector)
+        ? {
+            guide: connectorSkillName(scopedConnector.id),
+            guideSummary: connectorGuideSummary(scopedConnector),
+            required: connectorGuideRequired(scopedConnector),
+          }
+        : undefined;
+    // A scope that resolved to nothing is the same silence one step earlier in
+    // the lookup: no connector resolved, so no catalog was even attempted, so
+    // no catalog failed and the unavailable path below never fires. Echo only
+    // the ID the caller already supplied — naming what else is configured
+    // would answer a question they did not ask, past a filter they may not
+    // pass.
+    const unknownConnectorGuidance =
+      args.connector && !scopedConnector
+        ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
+        : undefined;
+    // Term-bearing searches report analysis only when the scorer had to
+    // degrade; a browse has no terms to analyse and normally reports none at
+    // all. But neither "this catalog is unavailable" nor "there is no such
+    // connector" is a statement about terms, and answering either browse with
+    // an empty entry list alone is indistinguishable from a connector that
+    // simply exposes no tools. The term partitions stay empty on those paths
+    // because there were no terms — the scope fields carry the whole message.
+    const reportsQueryAnalysis =
+      queryTerms.length > 0
+        ? matchMode === "partial"
+        : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0;
     const guidance =
       queryTerms.length === 0
-        ? undefined
-        : matches.length === 0
-          ? args.connector && !scopedConnector
-            ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
+        ? // A browse has no terms to advise about, so it stays silent unless
+          // the scope itself failed: the guidance on a scoped miss recommends
+          // browsing with an empty query, and that advice must not lead into a
+          // dead end that looks like a connector with no tools.
+          (unknownConnectorGuidance ??
+          (unavailableCatalogs === 0
+            ? undefined
             : scopedConnector
+              ? `Connector "${scopedConnector.id}" could not be browsed because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+              : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Scope by connector to see the typed reason.`))
+        : matches.length === 0
+          ? (unknownConnectorGuidance ??
+            (scopedConnector
               ? unavailableCatalogs > 0
-                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Retry later.`
-                : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
+                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+                : scopedGuide?.required
+                  ? `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Fetch queryAnalysis.guide before calling, then refine terms or browse with an empty query.${filterRecovery}`
+                  : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
               : unavailableCatalogs === 0
                 ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
-                : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+                : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`))
           : matchMode === "partial"
             ? scopedConnector
               ? `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`
@@ -770,7 +895,7 @@ export class CatalogService {
       ...(matchMode === "partial" && matches.length > 0
         ? { matchMode }
         : {}),
-      ...(queryTerms.length > 0 && matchMode === "partial"
+      ...(reportsQueryAnalysis
         ? {
             queryAnalysis: {
               representedTerms,
@@ -789,6 +914,23 @@ export class CatalogService {
               ...(unavailableCatalogs > 0
                 ? { unavailableConnectorCount: unavailableCatalogs }
                 : {}),
+              ...(scopedCatalogError ? { catalogError: scopedCatalogError } : {}),
+              ...(scopedGuide
+                ? {
+                    guide: scopedGuide.guide,
+                    ...(scopedGuide.guideSummary
+                      ? { guideSummary: scopedGuide.guideSummary }
+                      : {}),
+                    ...(scopedGuide.required
+                      ? {
+                          guideRequired: true as const,
+                          guideRequiredReasons: [
+                            "connector_required" as const,
+                          ],
+                        }
+                      : {}),
+                  }
+                : {}),
               ...(guidance ? { guidance } : {}),
             },
           }
@@ -853,12 +995,27 @@ export class CatalogService {
         tool.description,
         args.fullDescriptions === true,
       );
+      const requiredReasons = guideRequiredReasons(
+        addressResolution.connector,
+        tool,
+        false,
+      );
+      const guideSummary = connectorGuideSummary(addressResolution.connector);
       return {
         address,
         name: tool.name,
         ...(description !== undefined ? { description } : {}),
         ...(connectorGuide(addressResolution.connector)
-          ? { guide: connectorSkillName(addressResolution.connector.id) }
+          ? {
+              guide: connectorSkillName(addressResolution.connector.id),
+              ...(guideSummary ? { guideSummary } : {}),
+            }
+          : {}),
+        ...(requiredReasons
+          ? {
+              guideRequired: true as const,
+              guideRequiredReasons: requiredReasons,
+            }
           : {}),
         inputSchema: renderSchema(input, format),
         ...(tool.outputSchema
@@ -877,6 +1034,7 @@ export function groupedSearchResult(page: CatalogSearchPage) {
     id: string;
     title?: string;
     guide?: string;
+    guideSummary?: string;
     tools: CatalogSearchEntry["tool"][];
   }> = [];
   const byConnector = new Map<string, (typeof groups)[number]>();
@@ -889,6 +1047,9 @@ export function groupedSearchResult(page: CatalogSearchPage) {
         id: entry.connector.id,
         ...(entry.connector.title ? { title: entry.connector.title } : {}),
         ...(entry.guide ? { guide: entry.guide } : {}),
+        ...(entry.guideSummary
+          ? { guideSummary: entry.guideSummary }
+          : {}),
         tools: [],
       };
       byConnector.set(entry.connector.id, group);
@@ -913,6 +1074,9 @@ export function flatSearchResult(page: CatalogSearchPage) {
     tools: page.entries.map((entry) => ({
       ...entry.tool,
       ...(entry.guide ? { guide: entry.guide } : {}),
+      ...(entry.guideSummary
+        ? { guideSummary: entry.guideSummary }
+        : {}),
     })),
     total: page.total,
     offset: page.offset,

package/src/connectors/api.ts

@@ -5,6 +5,7 @@ import type {
   ConnectorCredentialConfig,
   ConnectorCredentialValues,
   ConnectorContext,
+  ConnectorUsageGuide,
   CredentialTestResult,
   JsonSchema,
   ToolAnnotations,
@@ -41,10 +42,11 @@ export interface ApiOptions {
   /** Optional per-runtime downstream call-admission policy. */
   callAdmission?: ConnectorCallAdmissionPolicy;
   /**
-   * Optional agent-facing usage guide (markdown) served by the `skills`
-   * meta-tool as `connector:<id>`. See `Connector.usageGuide`.
+   * Optional agent-facing usage guide served by `skills` as
+   * `connector:<id>`. A string is markdown; the structured form adds bounded
+   * discovery metadata. See `Connector.usageGuide`.
    */
-  usageGuide?: string;
+  usageGuide?: string | ConnectorUsageGuide;
   /** Optional operator-managed credential exposed through ctx.credential and /credentials. */
   credential?: ConnectorCredentialConfig;
   /** Optional validation behind /credentials' Test action. */
@@ -147,7 +149,11 @@ export function api(id: string, opts: ApiOptions): Connector {
         });
         if (invalid) throw invalid;
       }
-      return tool.handler(input, ctx);
+      // `await` (not a bare promise return) so a handler that throws before
+      // its first await never sits handler-less for the thenable-adoption
+      // microtask — workerd and vitest both report that gap as an unhandled
+      // rejection even though the caller catches the failure.
+      return await tool.handler(input, ctx);
     },
   };
 }

package/src/connectors/remote-mcp.ts

@@ -21,6 +21,7 @@ import type {
   ConnectorCallAdmissionPolicy,
   ConnectorContext,
   ConnectorStatus,
+  ConnectorUsageGuide,
   Logger,
   ToolDef,
 } from "../types.js";
@@ -47,10 +48,11 @@ export interface RemoteMcpOptions {
   /** Optional per-runtime downstream call-admission policy. */
   callAdmission?: ConnectorCallAdmissionPolicy;
   /**
-   * Optional agent-facing usage guide (markdown) served by the `skills`
-   * meta-tool as `connector:<id>`. See `Connector.usageGuide`.
+   * Optional agent-facing usage guide served by `skills` as
+   * `connector:<id>`. A string is markdown; the structured form adds bounded
+   * discovery metadata. See `Connector.usageGuide`.
    */
-  usageGuide?: string;
+  usageGuide?: string | ConnectorUsageGuide;
   auth?: RemoteMcpAuth;
   /**
    * Downstream HTTP redirect policy. Defaults to `"none"`: every redirect is