@zackbart/connecta 0.13.0 → 0.14.1

package/documentation/notion.md

@@ -0,0 +1,233 @@
+# Notion prebuilt connection
+
+Import `notion()` independently from `@zackbart/connecta/providers/notion`. It
+is a hand-written `api()` surface over Notion's public REST API — fifteen
+deliberate tools, lean projections of Notion's famously bloated payloads, typed
+failures, a rate budget matched to the documented limit, and a required usage
+guide. It adds no provider dependency, imports no `node:` builtin, and is not
+reachable from Connecta's root entry.
+
+```ts
+import { notion } from "@zackbart/connecta/providers/notion";
+
+const wiki = notion("engineering_wiki", {
+  title: "Engineering wiki",
+  purpose: "Runbooks, specs, and on-call notes for the platform team",
+  instructions: "Prefer the Runbooks database; specs live under Projects.",
+});
+```
+
+The `id` owns the ordinary connector namespaces; use a different id for every
+Notion workspace. `purpose` is required because an agent choosing between two
+instances needs to know which workspace answers the question. Workspace
+`instructions` are appended to the maintained guide and cannot change the
+connector's safety classification.
+
+## Why this one is `api()` and not `remoteMcp()`
+
+Notion publishes an MCP server, but the interesting problem here is not
+transport — it is shape. A single Notion page returns every property as a
+discriminated wrapper object, every string as an array of rich-text runs each
+carrying its own annotations block, and every user reference as a nested
+object. A twenty-five row database query is tens of kilobytes of structure
+around a few hundred bytes of meaning. Hand-writing the surface is what makes
+the projections possible, and the projections are the point.
+
+## Authentication
+
+One operator-managed credential: an internal integration token from
+[notion.so/profile/integrations](https://www.notion.so/profile/integrations).
+The deployment needs `credentials.encryptionKey` configured, or the token
+cannot be stored and every call fails `auth_required` at use.
+
+Two Notion-specific facts decide whether a working token is enough:
+
+- **Sharing is per object.** A token reaches only what has been explicitly
+  shared with its integration. An unshared page returns 404, not 403.
+- **Capabilities are per integration**, and the comment capabilities are off by
+  default. `list_comments` and `add_comment` fail with 403 until an operator
+  turns them on in Notion.
+
+`/credentials` offers a Test action, which calls `GET /v1/users/me` — the
+cheapest call that proves a token is live — and reports the workspace it
+authenticated into.
+
+## The pinned API version
+
+The connection pins `Notion-Version: 2026-03-11` and offers no override. That
+is deliberate rather than lazy. Notion's versions are date-named and old ones
+keep working indefinitely, so an override would look harmless; it is not.
+`2026-03-11` is the version in which databases split into data sources,
+`archived` became `in_trash`, and block append took a `position` object instead
+of an `after` string. Every projection and write body here assumes those
+shapes, so a deployment that pinned an older version would get quietly wrong
+results instead of a loud failure.
+
+Notion also ships *additive* changes to every version simultaneously, which is
+why the property and block projections fall back to unwrapping an unknown
+type's payload rather than switching exhaustively. A property type that ships
+after this release degrades to its raw value, and a block type that does keeps
+its payload under `raw`; neither vanishes.
+
+## Tools
+
+Ten reads, all annotated `readOnlyHint: true`:
+
+| Tool | What it is for |
+| --- | --- |
+| `search` | Find pages and data sources by **title**. Never searches content. |
+| `get_page` | One page's metadata and flattened property values. |
+| `get_page_content` | A page's body as flat blocks reduced to plain text. |
+| `get_page_property` | One property in full, past the 25-entry truncation. |
+| `get_database` | A database container and the data sources inside it. |
+| `get_data_source_schema` | Property ids, types, and select/status options. |
+| `query_data_source` | Filtered, sorted rows with properties already flattened. |
+| `list_users` | Workspace users and bots with their ids. |
+| `get_self` | Which integration and workspace this connector authenticates as. |
+| `list_comments` | Unresolved comments as plain text with discussion ids. |
+
+Five writes, none read-only, so all of them route through
+`call_destructive_tool`:
+
+| Tool | Classification |
+| --- | --- |
+| `create_page` | additive |
+| `append_blocks` | additive |
+| `add_comment` | additive |
+| `update_page_properties` | `destructiveHint: true` — replaces existing values |
+| `trash_page` | `destructiveHint: true` — removes a page from reads |
+
+The additive three leave `destructiveHint` unset: `readOnlyHint: false` already
+routes them through the approval path, and claiming a create destroys something
+only inflates the copy a host shows a human. `update_page_properties`
+deliberately has no `in_trash` argument, so an update can never trash a page by
+accident; trashing is its own named, reversible tool.
+
+## Lean projections, and the raw escape hatch
+
+Every read projects. A page becomes ids, plain text, and flattened values:
+`title` and `rich_text` collapse to strings, `select` and `status` to their
+option name, `multi_select` to an array of names, `relation` to an array of
+page ids, `people` to `{ id, name }`, `unique_id` to `"RL-12"`, and
+`formula`/`rollup` to their computed value. No `plain_text` runs, no
+`annotations` blocks, no property wrappers survive.
+
+Two projections are opinionated enough to call out:
+
+- **`search` returns identity fields only** — no properties at all. A
+  twenty-five result search across a populated database would otherwise drag
+  back several hundred flattened values for results the agent is about to
+  discard. `get_page` fetches properties for the one that matched.
+- **`get_page` reports what Notion hid.** Notion paginates four property types
+  — `title`, `rich_text`, `relation`, and `people` — cutting each off at 25
+  entries and signalling it only with a `has_more` flag on the property itself.
+  The projection surfaces those in `truncated_properties` as `{ name, id }`,
+  which is what stops an agent from confidently reasoning about 25 of 300
+  relations. The `id` is there because the handoff needs it: `get_page_property`
+  addresses a property by id, not by name.
+
+Where the dropped detail can matter — `search`, `get_page`, `get_page_content`,
+`get_page_property`, `get_data_source_schema`, `query_data_source`,
+`list_comments` — `raw: true` returns Notion's untouched response instead. It is
+much larger; it exists so a missing field is never a dead end. When the goal is
+*fewer* fields rather than more, `get_page` and `query_data_source` also take a
+`properties` array to project only the named ones.
+
+One caveat with `get_page_content`: `raw: true` returns the requested level
+exactly as Notion sent it and does not walk nested children, so `depth` is
+ignored alongside it. A raw read of a deep page yields one level, not three.
+Unmodelled *block* types are covered without it — a block whose type this
+projection does not know, and whose payload is not plain rich text, keeps that
+payload verbatim under `raw` on the block, so nothing collapses to an empty
+string.
+
+## Databases contain data sources
+
+This is the trap the guide is marked `required` for. A Notion database is a
+container; the rows and the schema live in a *data source* inside it, and the
+two ids are not interchangeable. The id in a database's URL is a **database
+id**, and passing it to `query_data_source` fails. The sequence is
+`get_database` → `get_data_source_schema` → `query_data_source`; `search`
+returns data sources directly and skips the first step.
+
+`create_page` needs the same distinction: a row is created under
+`parent_data_source_id`, never a database id. Its title also needs
+`title_property` from the schema, because a database's title column is rarely
+called "title".
+
+## Typed failures
+
+The mapping is deliberately not one-to-one with Notion's error codes. Notion's
+`code` says what its API thinks happened; Connecta's says what the caller
+should do next, and two of Notion's are easy to mistranslate.
+
+| Notion | Connecta | Why |
+| --- | --- | --- |
+| 400 (`validation_error`, `invalid_json`, `invalid_request`, `missing_version`, …) | `invalid_args` | every documented 400 is a malformed request |
+| 401 `unauthorized` | `auth_required` | the token is missing or invalid |
+| 403 `restricted_resource` | `connector_call_failed`, non-retryable | **not** `auth_required` |
+| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded; see below |
+| 409 `conflict_error` | `unavailable`, retryable | Notion says to retry |
+| 429 `rate_limited` | `rate_limited` + `retryAfterMs` | `Retry-After` seconds → ms |
+| 529 `service_overload` | `unavailable` + `retryAfterMs` | back off like a 429 |
+| 5xx | `unavailable`, retryable | upstream failure |
+
+The two that matter:
+
+**403 is not an authentication failure.** The token is fine; the integration
+lacks a capability or was never shared the object. Routing it to
+`auth_required` would send an agent to `authorize_connector`, which cannot
+grant a Notion capability or share a page. It is a non-retryable call failure
+whose message says an operator must change it in Notion.
+
+**404 does not prove absence.** Notion returns `object_not_found` both for an
+object that does not exist and for one that exists but has not been shared with
+the integration, and it will not say which. The message says both, because
+treating it as deletion is exactly how an agent concludes a page is gone when
+it was simply never shared.
+
+## Rate limiting
+
+Notion documents "an average of three requests per second, with some bursts
+beyond the average allowed" per connection, plus a separate per-workspace limit
+scaled to the plan. The connection declares a rolling budget of 180 calls per
+minute — the same average expressed over a window short bursts pass and a
+sustained loop does not — **paired with `maxConcurrency: 3`**.
+
+The concurrency cap is the load-bearing half. A budget alone is an average, and
+an averaged budget cannot stop a program from firing forty calls in the same
+tick; the cap keeps a burst shaped roughly like the one Notion documents.
+Neither half is a guarantee, because admission meters *tool calls* rather than
+requests — a single admitted `get_page_content` can spend twenty fetches, so
+180 calls per minute is a floor on the real request rate, not a ceiling.
+Declaring the cap is also what makes the queue settings legal — the admission
+controller refuses queue settings without a queue at construction.
+
+Like every connector budget this is per-runtime: N Worker isolates or Node
+processes serving one deployment each keep their own counter. It approximates
+the provider's limit; it does not enforce it.
+
+One tool can turn a single agent call into several downstream requests:
+`get_page_content` with `depth > 0` walks nested blocks, and call admission
+meters tool calls, not the fetches inside them. That walk stops at an internal
+ceiling of twenty requests and reports `truncated: true` rather than spending
+the whole budget invisibly.
+
+## Pagination
+
+List-shaped tools take `page_size` (1–100) and `start_cursor`, and return
+`has_more` with `next_cursor`. The default page size is 25 rather than Notion's
+100, because a first read should be cheap; `defaultPageSize` raises it for a
+deployment that pages a lot.
+
+Cursors are opaque. Notion's own versioning page is explicit that they may
+change in length, format, and structure at any time and must be passed back
+verbatim — never parsed, validated, or constructed.
+
+## What this connection does not do
+
+No file uploads, no database or data-source creation, no schema editing, no
+block updates or deletes, no page moves. Those are all real Notion endpoints
+and all deliberately absent: this is a deliberate tool surface, not a mirror of
+the API. Anything missing is reachable through a custom `api()` connector
+beside this one, which remains a first-class path.

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

@@ -70,6 +70,7 @@ proposing one without a new argument is not.
 | 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)) |
+| Guarded raw REST escape hatches in a prebuilt connection | accepted | a large, fast-moving provider cannot be honestly represented by a small frozen list: a GET-only tool may expose provider-relative reads, while JSON mutations and explicit-content uploads stay separate and always cross the destructive boundary; the connector owns authentication, rate limits, error mapping, URL confinement, and safe method classification, while the provider token remains the capability boundary — this is not schema ingestion, runtime connector registration, or permission widening |
 | 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)) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
@@ -65,9 +65,25 @@
       "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

@@ -834,13 +834,42 @@ export class CatalogService {
             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. Inspect catalogError for the typed reason and recovery detail.`
                 : scopedGuide?.required
@@ -848,7 +877,7 @@ export class CatalogService {
                   : `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.`
@@ -866,7 +895,7 @@ export class CatalogService {
       ...(matchMode === "partial" && matches.length > 0
         ? { matchMode }
         : {}),
-      ...(queryTerms.length > 0 && matchMode === "partial"
+      ...(reportsQueryAnalysis
         ? {
             queryAnalysis: {
               representedTerms,

package/src/connectors/api.ts

@@ -149,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/execute.ts

@@ -1351,7 +1351,7 @@ export function registerExecuteTool(
         code: z
           .string()
           .describe(
-            "One complete JavaScript async arrow function. Consume search/describe results and finish the task inside it; returning catalog data for a later call spends a round trip and buys nothing.",
+            "One complete JavaScript async arrow function. Consume search/describe results and finish the task inside it; returning catalog data for a later call spends a round trip and buys nothing. So does aborting on a missing tool match or result key — re-search, describe, or read the result's actual keys here instead.",
           ),
         diagnostics: z
           .boolean()