@zackbart/connecta 0.16.0 → 0.17.0

package/AGENTS.md

@@ -83,11 +83,18 @@ Two boundaries CI enforces that are not obvious from reading a file:
   and fails otherwise. Need a Node API? It goes behind an explicit Node-only
   subpath (`/node` or `/quickjs`), never the root.
 - **The published surface.** Platform-specific storage adapters live in
-  `examples/`, not the package. `@clerk/backend` and `quickjs-emscripten` are
-  optional peers behind the `./auth/clerk` and `./quickjs` subpaths and must
-  never become dependencies or install with core. Enforced by
-  `test/package-surface.test.ts` and `scripts/check-package.mjs`. Anything
-  heavyweight or platform-bound gets a subpath and an optional peer.
+  `examples/worker/`, never in `src/` and never in the `exports` map. That
+  example does ship in the tarball, Cloudflare KV and D1 adapters included —
+  it is the Workers starting template a consumer copies, and copying it is the
+  point — but every `exports` target resolves into `dist/`, so those adapters
+  are readable reference source and not an importable subpath. What is
+  forbidden is a platform-bound adapter becoming importable from the package,
+  not a file appearing in the artifact. `@clerk/backend` and
+  `quickjs-emscripten` are optional peers behind the `./auth/clerk` and
+  `./quickjs` subpaths and must never become dependencies or install with
+  core. Enforced by `test/package-surface.test.ts` and
+  `scripts/check-package.mjs`. Anything heavyweight or platform-bound gets a
+  subpath and an optional peer.
 
 ## Where new tests go
 

package/CHANGELOG.md

@@ -2,6 +2,295 @@
 
 All notable changes to this package are documented here.
 
+## 0.17.0 — 2026-08-13
+
+This minor release makes catalog discovery faster and its answers more exact.
+Agent reads can use a verified stale catalog while one bounded refresh runs,
+guide summaries now read Markdown as prose, compact schemas retain more declared
+constraints, array projection distinguishes misses from genuine nulls, and
+Mixpanel carries the conditional rules its live tools enforce. One construction
+contract tightens: an explicit `usageGuide.summary` over 120 characters now
+refuses to boot. Deployments whose summaries fit, or which let Connecta derive
+them, need no configuration change. Operator catalog reads retain their blocking
+freshness behavior. This release also makes the two code sandboxes' runtime
+differences explicit. The shipped
+Worker example is already loader-only; deployments that added executor
+`bindings`, `modules`, or `globalOutbound` must remove them. Existing portable
+`execute_code` programs keep their behavior. Programs can now classify a caught
+Connecta failure without parsing its message.
+
+### Changed
+
+- An explicit `usageGuide.summary` longer than 120 characters after whitespace
+  normalization now throws during registry construction. Exactly 120 remains
+  valid, and a blank explicit summary still falls back to derivation (#392).
+
+- **Agent catalog reads now serve a verified stale entry while they refresh it.**
+  Search, describe, and code-mode calls no longer await a downstream listing
+  when the runtime already holds a complete catalog inside its stale window.
+  The inbound request still causes the refresh; there is no timer, warmup, or
+  credential probe. One bounded refresh per connector owns and closes a fresh
+  scope, while operator status stays blocking and shows whether the last agent
+  read in this runtime was fresh or stale (#396).
+
+### Fixed
+
+- **Caught `execute_code` failures now keep their machine-readable type.**
+  Calls, connector shortcuts, discovery, emitted-output and UI validation,
+  batch validation, and host-call budgets still throw with the same human
+  message, but now expose `code`, `retryable`, and full `details`. Batch entries
+  use the same codes. A per-run authenticated frame prevents connector prose or
+  guest code from forging the host transport on either executor (#393).
+
+- **`execute_code` now tells the truth about each shipped sandbox.** QuickJS
+  has no `fetch`, `process`, timers, `crypto`, or `WebSocket`, and blocks
+  imports. Loader-only Dynamic Workers deny outbound fetch, WebSocket,
+  `node:net`, and `node:tls`; leave DNS unresolved; expose no environment
+  bindings or filesystem/HTTP builtins; but retain local `data:` fetch,
+  runtime globals, and a non-contract builtin set that can drift. The example
+  pins the required loader-only construction, and agent guidance tells portable
+  programs to use none of that Dynamic-only authority (#390).
+
+- **Clerk-authenticated operator pages now wait for ClerkJS before booting.**
+  The loader runs before the later inline operator bundle instead of deferring
+  until after parsing, so a fresh page no longer mistakes normal script order
+  for a network failure. Clerk's major-to-pinned version redirect remains
+  supported, and a real loader failure keeps the existing clear error (#403).
+
+- **Stripe's guide now treats connector identity as routing intent, not account
+  proof.** One OAuth session may cover several accounts in one organization,
+  so agents resolve the intended account through the live tool schema and stop
+  when the target or selector is ambiguous. The guide also keeps organization
+  accounts separate from the restricted-key-only Stripe Connect path (#404).
+
+- **The no-account-model constitution now matches provider-owned sessions.**
+  Connecta still has no account dimension: credentials, storage, admission,
+  and health remain connector-scoped. A provider may expose its own account
+  scope only through its live schema; metadata never proves identity, and an
+  ambiguous target or selector stops instead of becoming a guess (#410).
+
+- **The reviewed Notion page contracts are current again.** Notion added
+  create-page template and placement options plus update-page locking,
+  template, and erase options. The existing parent, properties, Markdown,
+  children, emoji, and trash request subsets remain valid, so this release
+  records the two changed endpoint digests without adding the new capabilities.
+  Their product decisions remain in #408 and #409.
+
+- **Array field misses now report what happened.** A path that misses every
+  element appears in `unmatchedFields` instead of returning a clean array of
+  false nulls. A heterogeneous array keeps its positional result and names the
+  path in `partialFields`, so genuine downstream nulls remain distinguishable.
+  Schema-backed misses keep the same bounded guidance through nested arrays;
+  schema-free projections still report their observed misses (#394).
+- Derived guide summaries now join a hard-wrapped opening paragraph before
+  selecting a complete sentence or shortening at a clause or word boundary.
+  Frontmatter, fences, headings, rules, tables, and description fallbacks keep
+  their prior roles; multi-line HTML comments are now skipped whole (#392).
+
+- **Compact schemas now carry declared numeric and string constraints.** Search
+  and compact describe show numeric bounds, multiples, string length bounds,
+  patterns, and formats beside the affected type. Search keeps its 1,024-byte
+  schema ceiling and 256-byte node budget: a constraint that does not fit is
+  dropped whole, and the existing truncation flag sends the caller to describe
+  for the complete shape (#391).
+
+- **Carry Mixpanel's three enforced conditional-input rules in its maintained
+  guide.** A live read-only audit confirmed that `Get-Business-Context`,
+  `Get-Property-Values`, and `List-Properties` accept shapes in their advertised
+  schemas that their implementations reject. Connecta still preserves the
+  hosted schemas unchanged; the guide now prevents those rejected calls, the
+  vetted manifest records schema digests for all 63 tools, and the provider
+  defect is tracked upstream. The maintainer drift check also frames
+  Mixpanel's service account as its documented `Bearer Basic` value instead of
+  ordinary HTTP Basic (#395).
+
+## 0.16.1 — 2026-08-13
+
+This is the cleanup that follows 0.16.0 out the door: the packaging housekeeping
+the pre-release smoke gauntlet turned up, one provider tool Cloudflare
+deprecated out from under us, a discovery answer that told a plain lie, and the
+upgrade runbook an existing deployment never had. Two things break, both on
+Cloudflare and both named here rather than left to the section below:
+`list_zone_settings` is gone from the `cloudflare()` named surface, and
+Cloudflare's 404 arrives as `not_found` instead of `connector_call_failed`.
+Nothing else does — no wire shape changes, no construction contract moves, no
+other code reclassified, and the per-setting operations `list_zone_settings`
+sat beside are the supported ones and are untouched. A deployment that writes
+no `api()` connectors, branches on no error code, and never asked an agent for
+a whole zone's settings in one call upgrades without reading further.
+
+Three things are additions rather than repairs, and they are the reason this
+release is worth reading rather than just installing: a new
+`ConnectorCallErrorCode` member, `not_found`, with a rule for when a connector
+may mint it; a `"./package.json"` entry in the `exports` map, so the installed
+manifest resolves; and `@cloudflare/codemode` declared as an optional peer at
+`^0.4.4 || ^0.5.0`. Strict semver would read those three as a minor, and would
+read the two Cloudflare changes above as more than that. This ships as a patch
+deliberately: every addition is opt-in at the point a deployment chooses to
+read it, and the tool removal and the 404 reclassification ride along in the
+same patch on purpose — both are scoped to one provider, both have a stated
+replacement, and both carry a version boundary in
+[`documentation/upgrading.md`](./documentation/upgrading.md). Holding them for
+a minor would mean shipping a release that keeps calling an endpoint its
+provider deprecated. The one install-time consequence is spelled out next.
+
+One thing to check before upgrading a Worker: `@cloudflare/codemode` is now a
+declared peer, so if your `package.json` holds it at a version outside
+`^0.4.4 || ^0.5.0` — a `0.3.x`, or a `0.4` below `0.4.4` — npm stops the
+upgrade with an `ERESOLVE` conflict rather than installing. Move it into the
+range this release is tested against, or pass `--legacy-peer-deps` if you have
+a reason to run outside it. A version already inside the range, and a range
+loose enough for npm to pick one that is, both resolve exactly as before.
+
+Alongside it, the upgrade path an existing deployment takes gets written down.
+`connecta init` was the golden path for a new deployment and the whole story
+for an old one, which is a gap with a shape: `init` refuses to merge into an
+existing path — the guard that keeps an initializer from eating a connector
+set — so an agent pointed at a deployment two releases behind had to
+reconstruct the procedure from release prose written for the maintainer. Both
+interesting failures there were silent too. It overwrites the configuration the
+deployment exists for, or it "fixes" a construction throw by weakening a
+fail-closed default and ships something quieter and wrong.
+
+### Added
+
+- **`not_found`, for a downstream that answered and had nothing to give.** A
+  hand-written connector meeting a 404 had exactly one honest code,
+  `connector_call_failed`, which also means "the call blew up" — so a program
+  inside `execute_code` could not tell a clean absence from a broken connector,
+  and a loop over ids had to abort where it should have skipped one. The new
+  code earns its place the way every code has to: it changes what the caller
+  does next. You do not wait, you do not go to `authorize_connector`, you do
+  not repair the arguments — you re-address. It is non-retryable, carries no
+  recovery envelope, derives no activity friction class, and is exported from
+  the root entry as part of `ConnectorCallErrorCode`.
+
+  The qualifier is the interesting half, and it is now written down in
+  [H11](./documentation/provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next):
+  map a status to `not_found` only where the provider tells absence apart from
+  a permission gap. Cloudflare does — a token that may not touch a resource is
+  refused with 401 or 403 — so its 404 is now `not_found` instead of
+  `connector_call_failed`. Notion does not: `object_not_found` means both "it
+  is gone" and "it was never shared with this integration", so it deliberately
+  stays generic with a message that says so. The hosted-MCP proxy path mints
+  the code never, because `P1` forbids re-shaping downstream framing and
+  provider prose is never parsed to invent a classification (#373).
+
+- **An upgrade runbook for existing deployments.**
+  [`documentation/upgrading.md`](./documentation/upgrading.md) is written for
+  the agent sitting inside a generated deployment it did not create: read the
+  exact pin and the template generation it implies, regenerate that generation
+  with `npx @zackbart/connecta@<pin> init` to get a real merge base, three-way
+  reconcile the scaffolding against the current template while `src/index.ts`
+  stays the deployment's own, cross the version boundaries that break
+  construction, and finish where `init` finishes — typecheck, start,
+  `connecta doctor`, then a program that exercises the deployment's *own*
+  connectors, which doctor deliberately knows nothing about. The migration
+  notes are per boundary and derived from this file: the 0.16.0 `api()`
+  construction contract (with the one safe answer for an unannotated tool
+  written down — `readOnlyHint: false`, which is the routing it already had),
+  the `linear()`, `mixpanel()`, and Cloudflare provider changes, redirect
+  refusal and the response ceilings, and the fail-closed shipped defaults; then
+  0.14's annotation-precedence change, 0.13's rewritten guide summaries, the
+  0.11.0 executor requirement, 0.7.0's `verifyState` requirement and
+  core-owned routes for the pre-template deployments that still have to cross
+  them, and every removed option that throws with its migration. It closes with five refusals, because each is somebody's plausible
+  shortcut: no re-init over the top, no weakening a fail-closed default to get
+  green, no pinning back, no vendored internals, no second project shape.
+  Reachable from the README, from `operations.md`, and — absolutely, because
+  that reader has no copy of this repository — from the template's `AGENTS.md`
+  (#380).
+- **A suite that keeps the guide honest.** `test/upgrade-guide.test.ts` pins
+  every claim its reader cannot check: the generated file inventory against
+  `templates/node/`, the seven tool names against the CLI's own list, each
+  named version boundary against a release that shipped, each removed option
+  against the release section that names its issue, the bump target against
+  this package's version, and the three places the guide is linked from. A template that gains a file now fails `npm run check` rather than
+  leaving an agent to guess which of the two is wrong (#380).
+- **`@cloudflare/codemode` is a declared optional peer.** Every Workers
+  deployment installs the executor behind `execute_code` by hand, and until now
+  the only version range anywhere was a devDependency no consumer can read — a
+  fresh install resolved a minor ahead of what this repository tests, silently.
+  The manifest now publishes `^0.4.4 || ^0.5.0` for it, optional like
+  `@clerk/backend` and `quickjs-emscripten`, so a supported version installs in
+  silence and an unsupported one stops the install with something to act on
+  instead of becoming skew a Worker discovers in production. It still installs
+  with nothing: a default `npm install @zackbart/connecta` pulls no executor,
+  and the package smoke proves that, both halves of the range behavior, and
+  that the version this repository develops against stays inside the range it
+  publishes (#376).
+
+### Changed
+
+- **Cloudflare's 404 is `not_found`.** A deployment branching on
+  `connector_call_failed` to detect an unknown zone or account id should read
+  `not_found` instead; retryability, the message, and its pointer to
+  `list_zones` / `list_accounts` are unchanged (#373).
+- `cloudflare()` no longer names a bulk zone-settings read.
+  `GET /zones/{zoneId}/settings` and its `PATCH` sibling are published as
+  `deprecated: true`, Cloudflare offers no bulk replacement, and the tool that
+  wrapped the read projected nothing — it took a zone id and grew the payload
+  by wrapping an unpaginated array in a page object. Read one setting with
+  `get_zone_setting` and write one with `update_zone_setting`, both on the
+  supported `/zones/{zoneId}/settings/{settingId}` operations. An operator who
+  still wants the whole set can name the deprecated path explicitly through
+  `cloudflare_api_get`. The named surface is 47 tools plus the three escape
+  hatches ([#361](https://github.com/zackbart/connecta/issues/361)).
+- The Cloudflare touched-endpoint manifest drops the deprecated row with the
+  tool, so `npm run drift:check -- --specs` is quiet about zone settings
+  because nothing calls the endpoint, not because a maintainer signed off on
+  calling it anyway.
+
+### Fixed
+
+- **A search for a connector's own name stops claiming the deployment has no
+  such capability.** A connector's `id` — the address prefix an agent already
+  holds — and its `title` are displayed, never indexed, so `search_tools({
+  query: "inventory" })` against a connector called `inventory` matched no tool
+  and was answered with "No matching capability is configured in this
+  deployment", which was plainly false. Connector identity stays out of the
+  lexical index, because putting it in would move ranking for every query that
+  already matches tools; instead an unscoped miss whose terms name configured
+  connectors says so, names up to three of them by ID, and sends the caller to
+  a scoped browse. A term that matches nothing in the deployment still gets the
+  original sentence, unchanged. One `queryAnalysis.guidance` string differs; no
+  ranking, result, or field changed (#372).
+- **Every relative link in the shipped Markdown resolves for the reader who
+  installed the package.** Ten of them pointed at `eval/`, `test/`, `scripts/`,
+  and the README hero — repository paths the tarball has never carried and, per
+  #346, should not start carrying. The link gate could not see any of them: it
+  read only `documentation/` targets, so the whole class was invisible and grew
+  with every trim. The policy is now stated once in the operations guide and
+  enforced over *every* relative link in packed Markdown: it either resolves
+  inside the tarball or it is cited as an absolute
+  `https://github.com/zackbart/connecta/blob/main/...` URL, which an outside
+  reader can follow and which `check:docs` resolves back to the checkout, so a
+  citation still fails when the file it names moves. The ten links were
+  rewritten that way, the README hero now loads from
+  `raw.githubusercontent.com` and still renders on npmjs.com, and the
+  repository reader loses no citation (#378).
+- **`@zackbart/connecta/package.json` resolves.** The `exports` map listed
+  every code subpath and nothing else, so a bundler plugin, framework build
+  step, or version probe reaching for the installed manifest — a thing the
+  ecosystem broadly expects to work — got `ERR_PACKAGE_PATH_NOT_EXPORTED`
+  instead of the file. The manifest is now exported. It is a data file, so this
+  widens the published surface by exactly zero code paths: the root entry's
+  Workers purity boundary and the optional-peer subpaths are untouched. The
+  package-surface gate now asserts the whole subpath set, manifest included, so
+  neither this entry nor an unwanted one can arrive unnoticed (#374).
+- **The published-surface rule says what it actually forbids.** `AGENTS.md`
+  claimed platform-specific storage adapters live in `examples/`, "not the
+  package", while the tarball has always carried `examples/worker` — Cloudflare
+  KV and D1 adapters included — because that example is the Workers starting
+  template a consumer copies. The invariant was never in danger: nothing under
+  `examples/` appears in the `exports` map, so those adapters are reference
+  source and not an importable subpath. The wording now draws the line where
+  the gates draw it — a platform-bound adapter must not reach `src/` or the
+  `exports` map — and says why the example ships, in `AGENTS.md`, the
+  operations guide, and the `scripts/check-package.mjs` comment. A new
+  assertion in `test/package-surface.test.ts` holds the instruction file and
+  the exports map to the same story (#377).
+
 ## 0.16.0 — 2026-08-12
 
 This is the agent-efficiency refocus. One release, sixteen merges, and a single

package/README.md

@@ -1,6 +1,6 @@
 # connecta
 
-![A monochrome clay Connecta hub joining many tools](./assets/connecta-clay-hero.png)
+![A monochrome clay Connecta hub joining many tools](https://raw.githubusercontent.com/zackbart/connecta/main/assets/connecta-clay-hero.png)
 
 One place for AI agents to connect to the tools you choose.
 
@@ -98,6 +98,11 @@ activity ship as commented configuration, each one a variable and an
 uncommented block away. The generated `README.md` walks through all four, and
 the [Worker example](./examples/worker/) does the same for KV and D1.
 
+Already have a deployment on an older version? `init` deliberately refuses to
+merge into it, so bringing one current is its own procedure:
+[Upgrading an existing deployment](./documentation/upgrading.md) is the
+runbook, written for the agent working inside that project.
+
 The template refuses to merge into an existing directory, so initialization
 cannot overwrite another project. Its generated programs have no filesystem,
 environment, arbitrary network, imports, or timers; only explicitly read-only

package/dist/catalog-service.d.ts

@@ -1,5 +1,6 @@
 import type { CallErrorDetails } from "./errors.js";
 import type { ConnectorOperationOptions, RegistryView } from "./registry.js";
+import type { DeferredWork } from "./connector-scope.js";
 import type { Connector, ToolDef } from "./types.js";
 export declare const DEFAULT_SEARCH_LIMIT = 8;
 export declare const MAX_SEARCH_LIMIT = 100;
@@ -138,6 +139,7 @@ export declare class CatalogService {
     private readonly probeTimeoutMs;
     private readonly concurrency;
     private readonly searchRoute;
+    private readonly readOptions;
     private readonly loaded;
     private readonly loading;
     constructor(registry: RegistryView, baseUrl: string, options?: {
@@ -146,6 +148,8 @@ export declare class CatalogService {
         concurrency?: number;
         /** The discovery route recovery records name. Default `search_tools`. */
         searchRoute?: SearchRoute;
+        /** Runtime-owned tail for stale-while-revalidate catalog reads. */
+        defer?: DeferredWork;
     });
     /**
      * Send a caller back to discovery through the surface it can actually reach.

package/dist/catalog-service.js

@@ -1,4 +1,4 @@
-import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
+import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
@@ -10,6 +10,12 @@ export const MAX_DESCRIBE_ADDRESSES = 100;
 export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
 const MAX_QUERY_TERMS = 8;
 const MAX_QUERY_TERM_LENGTH = 64;
+/**
+ * Connector IDs a no-match search will name back. Three is enough to point at
+ * the connector the query already named without turning a miss into a listing
+ * of the deployment.
+ */
+const MAX_IDENTITY_CONNECTORS = 3;
 const encoder = new TextEncoder();
 /** Clip one echoed query term without splitting a non-BMP code point. */
 function boundedQueryTerm(term) {
@@ -161,6 +167,7 @@ export class CatalogService {
     probeTimeoutMs;
     concurrency;
     searchRoute;
+    readOptions;
     loaded = new Map();
     loading = new Map();
     constructor(registry, baseUrl, options = {}) {
@@ -171,6 +178,12 @@ export class CatalogService {
             normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
         this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
         this.searchRoute = options.searchRoute ?? "search_tools";
+        this.readOptions = options.defer
+            ? {
+                defer: options.defer,
+                refreshTimeoutMs: this.probeTimeoutMs,
+            }
+            : undefined;
     }
     /**
      * Send a caller back to discovery through the surface it can actually reach.
@@ -201,7 +214,7 @@ export class CatalogService {
         if (inFlight)
             return inFlight;
         const loading = this.registry
-            .getTools(id, this.baseUrl, this.requestScope, callOptions)
+            .getTools(id, this.baseUrl, this.requestScope, callOptions, this.readOptions)
             .then((tools) => {
             this.loaded.set(id, tools);
             return tools;
@@ -561,6 +574,36 @@ export class CatalogService {
                 required: connectorGuideRequired(scopedConnector),
             }
             : undefined;
+        // A connector's own id — the address prefix the caller already has — and
+        // the title it is displayed under are the most natural first query terms,
+        // and neither is a document in the lexical index. Indexing them would move
+        // ranking for every query that already matches tools, so instead a search
+        // that matched nothing asks the same lexical question of connector
+        // identity and corrects its own sentence: the deployment plainly has this
+        // capability, and one scoped browse away are its tools. Unscoped only —
+        // guidance for an explicit scope already names that connector rather than
+        // claiming the deployment has nothing.
+        const identityConnectorIds = matches.length === 0 && !isBrowse && !unsearchableQuery && !scopedConnector
+            ? connectors
+                // The full query, not `analyzedTerms`: that cap exists to bound
+                // the serialized term fields, and ranking already reads every
+                // term. A ninth term is a real search term, and a search that
+                // ranked against it must not deny the connector it names.
+                .filter((connector) => queryTerms.some((term) => matchesLexicalTerm(connector.id, term) ||
+                (connector.title !== undefined &&
+                    matchesLexicalTerm(connector.title, term))))
+                .map((connector) => connector.id)
+            : [];
+        const namedIdentityConnectors = identityConnectorIds
+            .slice(0, MAX_IDENTITY_CONNECTORS)
+            .map((id) => `"${id}"`)
+            .join(", ");
+        const unnamedIdentityConnectors = identityConnectorIds.length - MAX_IDENTITY_CONNECTORS;
+        const identityGuidance = identityConnectorIds.length === 0
+            ? undefined
+            : `No matching ${safetyLabel}capability was found${unavailableCatalogs === 0 ? "" : " in the catalogs that answered"}, but the query names configured connector${identityConnectorIds.length === 1 ? "" : "s"} ${namedIdentityConnectors}${unnamedIdentityConnectors > 0
+                ? ` and ${unnamedIdentityConnectors} more`
+                : ""}. Scope by connector and browse with an empty query to list the tools there.${filterRecovery}`;
         // 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
@@ -604,9 +647,10 @@ export class CatalogService {
                                 : 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}`))
+                            : (identityGuidance ??
+                                (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}`))))
                     : matchMode === "partial"
                         ? scopedConnector
                             ? `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`

package/dist/catalog.d.ts

@@ -18,6 +18,17 @@ export interface RankedTool {
     exactName: boolean;
     matchedTermCount: number;
 }
+/**
+ * Whether one query term matches a whole token of arbitrary text, under the
+ * same inflection rules the tool index uses.
+ *
+ * Connector identity — an `id` or a `title` — is deliberately not a document in
+ * that index: making it one would move ranking for every query that already
+ * matches tools. This lets a caller ask the index's question of a string that
+ * never became a document, which is what the no-match analysis needs to tell
+ * "nothing like this exists here" from "that word is a connector".
+ */
+export declare function matchesLexicalTerm(text: string, term: string): boolean;
 export interface LexicalCorpusStatistics {
     documentCount: number;
     documentFrequency: ReadonlyMap<string, number>;