@zackbart/connecta 0.38.0 → 0.40.0

package/dist/catalog-service.js

@@ -1,4 +1,5 @@
 import { registerAuthMethod } from "./auth/native.js";
+import { META_ROUTES, routeToolInPlace } from "./agent-routes.js";
 import { withAuthorizationHandoffEffect } from "./authorization-handoff.js";
 import { carryCatalogFreshness, catalogIsFresh } from "./catalog-freshness.js";
 import { retainedCatalogIdentity } from "./catalog-cache.js";
@@ -13,9 +14,24 @@ import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { registryProgram } from "./runtime/registry.js";
 import { SharedRead } from "./runtime/shared-read.js";
 import { duringViewEffect } from "./runtime/call.js";
-import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs } from "./timeout.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, UNSCOPED_DISCOVERY_BUDGET_MS, UNSCOPED_PROBE_TIMEOUT_MS, } from "./timeout.js";
+import { claimDiscoveryProbe, readDiscoveryHealth, settleDiscoveryHealth, } from "./discovery-health.js";
 import { keepErrorName } from "./redaction-identity.js";
-import { operationVocabularyMatches } from "./operation-vocabulary.js";
+import { operationVocabularyMatches, searchSynonyms } from "./operation-vocabulary.js";
+/** The slice of an unscoped search's budget kept for recording what its probes saw. */
+const SETTLE_RESERVE_MS = 500;
+/** How long a probe claim outlives its request's discovery budget, for settlement and clock skew. */
+const CLAIM_MARGIN_MS = 2_000;
+/** A connector unscoped search skipped because its discovery failed recently. */
+class DiscoverySkipped extends Error {
+    code;
+    retryAfterMs;
+    constructor(code, retryAfterMs) {
+        super("Connector discovery skipped after a recent failure");
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
@@ -31,6 +47,8 @@ const MAX_IDENTITY_CONNECTORS = 3;
 const MAX_DESCRIBE_SUGGESTIONS = 3;
 const MAX_API_SEARCH_POINTERS = 3;
 const MAX_API_SEARCH_ADDRESS_BYTES = 256;
+/** Fully determined operation reads one search page offers: one per connector, three connectors. */
+const MAX_READY_CALLS = 3;
 /** Recognize the visible standard family without importing provider implementations or indexes. */
 function apiSearchTools(tools) {
     const names = new Set(tools.map((tool) => tool.name));
@@ -70,6 +88,13 @@ const SERVICE_NAMES = [
     "Google Slides",
     "Gmail",
 ];
+/**
+ * Leading verbs that ask to read. A query led by one ranks read rows above
+ * write rows within each relevance tier; writes stay on the page.
+ */
+const READ_INTENT = /^(?:list|get|find|search|show|read|fetch|count)$/;
+/** Name words that state an action, never a resource. */
+const ACTION_WORD = /^(?:list|get|find|search|show|read|fetch|count|create|update|delete)$/;
 function normalizedPhrase(text) {
     return lexicalQueryTerms(text.toLowerCase()).join(" ");
 }
@@ -238,15 +263,13 @@ function schemaKeyMetadata(input, output) {
     };
 }
 const stringListSchema = { type: "array", items: { type: "string" } };
-const guideProperties = {
-    guide: { type: "string" },
-    guideSummary: { type: "string" },
+const STRING = { type: "string" };
+// The reasons enum is stated once under `$defs` and referenced from each field.
+const guideRequiredProperties = {
     guideRequired: { const: true },
-    guideRequiredReasons: {
-        type: "array",
-        items: { enum: ["connector_required", "approval_required", "schema_truncated"] },
-    },
+    guideRequiredReasons: { $ref: "#/$defs/reasons" },
 };
+const guideProperties = { guide: STRING, guideSummary: STRING, ...guideRequiredProperties };
 const catalogFailureProperties = {
     code: { type: "string" },
     message: { type: "string" },
@@ -292,26 +315,31 @@ const catalogFailureProperties = {
         },
     },
 };
+/** The one typed failure (and auth handoff) both failure fields reference. */
+const FAILURE_REF = { $ref: "#/$defs/failure" };
 /**
  * The outputSchema contract for either search adapter. Guest API registration
  * can reuse this value instead of maintaining a second page definition.
+ * Every failure field references one local `$defs` entry, so the typed auth
+ * handoff is advertised once instead of once per field.
  */
 export const CATALOG_SEARCH_RESULT_SCHEMA = {
     type: "object",
     required: ["catalogErrors", "tools", "total", "offset", "limit", "hasMore"],
     additionalProperties: false,
-    properties: {
-        catalogErrors: {
-            type: "array",
-            items: {
-                type: "object",
-                required: ["connector", "code", "message", "retryable"],
-                additionalProperties: false,
-                properties: {
-                    ...catalogFailureProperties,
-                },
-            },
+    $defs: {
+        reasons: { type: "array", items: { enum: ["connector_required", "approval_required", "schema_truncated"] } },
+        failure: {
+            type: "object",
+            required: ["code", "message", "retryable"],
+            additionalProperties: false,
+            properties: catalogFailureProperties,
         },
+    },
+    properties: {
+        // `allOf` rather than a `$ref` sibling keeps `required` enforced by
+        // validators that predate 2020-12 sibling semantics.
+        catalogErrors: { type: "array", items: { allOf: [FAILURE_REF], required: ["connector"] } },
         absence: {
             type: "object",
             required: ["service", "message", "configuredConnectors"],
@@ -331,7 +359,6 @@ export const CATALOG_SEARCH_RESULT_SCHEMA = {
                 properties: {
                     name: { type: "string" },
                     address: { type: "string" },
-                    connectorTitle: { type: "string" },
                     description: { type: "string" },
                     inputSchema: {},
                     outputSchema: {},
@@ -345,10 +372,33 @@ export const CATALOG_SEARCH_RESULT_SCHEMA = {
                     outputKeys: stringListSchema,
                     annotations: { type: "object" },
                     classification: { enum: ["read", "write"] },
-                    ...guideProperties,
+                    ...guideRequiredProperties,
                 },
             },
         },
+        readyCalls: {
+            type: "array",
+            maxItems: MAX_READY_CALLS,
+            items: {
+                type: "object",
+                required: ["address", "args", "classification", "summary"],
+                properties: {
+                    address: STRING,
+                    args: { type: "object", required: ["path"], additionalProperties: false, properties: { path: STRING } },
+                    classification: { const: "read" },
+                    summary: STRING,
+                    ...guideRequiredProperties,
+                },
+            },
+        },
+        connectors: {
+            type: "object",
+            additionalProperties: {
+                type: "object",
+                additionalProperties: false,
+                properties: { title: STRING, guide: STRING, guideSummary: STRING },
+            },
+        },
         total: { type: "integer", minimum: 0 },
         offset: { type: "integer", minimum: 0 },
         limit: { type: "integer", minimum: 1, maximum: MAX_SEARCH_LIMIT },
@@ -368,12 +418,7 @@ export const CATALOG_SEARCH_RESULT_SCHEMA = {
                 unknownConnector: { const: true },
                 configuredConnectors: stringListSchema,
                 unavailableConnectorCount: { type: "integer", minimum: 0 },
-                catalogError: {
-                    type: "object",
-                    required: ["code", "message", "retryable"],
-                    additionalProperties: false,
-                    properties: catalogFailureProperties,
-                },
+                catalogError: FAILURE_REF,
                 ...guideProperties,
                 guidance: { type: "string" },
             },
@@ -397,6 +442,7 @@ export class CatalogService {
     requestScope;
     defer;
     probeTimeoutMs;
+    discoveryBudgetMs;
     concurrency;
     searchRoute;
     requestSignal;
@@ -421,12 +467,18 @@ export class CatalogService {
     // gets new views and indexes. Each service belongs to one request and one
     // registry visibility view (caller/pool, hidden tools and classification).
     searchViews = new WeakMap();
+    // This request's discovery-health verdicts, read once per connector and kept
+    // current by its own probes, so repeated searches read no storage.
+    health = new Map();
+    routes;
     constructor(registry, baseUrl, options = {}) {
         this.registry = registry;
         this.baseUrl = baseUrl;
         void CatalogService.nativePrograms;
+        this.routes = options.routes ?? META_ROUTES;
         this.requestScope = options.requestScope ?? {};
         this.probeTimeoutMs = normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
+        this.discoveryBudgetMs = normalizeTimeoutMs(options.discoveryBudgetMs) ?? UNSCOPED_DISCOVERY_BUDGET_MS;
         this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
         this.searchRoute = options.searchRoute ?? "search_tools";
         this.requestSignal = options.requestSignal;
@@ -480,7 +532,16 @@ export class CatalogService {
                     signal,
                     timeoutMs: this.probeTimeoutMs,
                     ...(this.defer ? { defer: this.defer } : {}),
-                }).pipe(Effect.map((tools) => carryCatalogFreshness(tools, tools.map(cloneTool)))), (succeeded) => {
+                }).pipe(Effect.map((tools) => {
+                    // An authored catalog lists its declared descriptions for this request's surface.
+                    const connector = this.registry.getConnector(id);
+                    return carryCatalogFreshness(tools, tools.map((tool) => {
+                        // The request's own copy, which keeps the source classification.
+                        const copy = cloneTool(tool);
+                        routeToolInPlace(connector, copy, this.routes);
+                        return copy;
+                    }));
+                })), (succeeded) => {
                     // Evicted before the read resumes anyone, so an asker that
                     // retries on hearing of the failure starts a fresh read.
                     if (!succeeded && this.catalogs.get(id)?.read === started) {
@@ -515,11 +576,117 @@ export class CatalogService {
     // that asked for it. On a read-only endpoint a write is absent from search
     // and describe, as if the connector never had it. Guides are not filtered.
     discoveryCatalogs(ids, route, includeWrites = false) {
-        return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => Effect.map(this.catalog(id, { signal }), (tools) => this.searchView(id, tools, includeWrites, "all")), {
-            ...(this.requestSignal ? { signal: this.requestSignal } : {}),
-            timeoutMs: this.probeTimeoutMs,
-            timeoutError: new ConnectorCallError("timeout", `${route} probe of "${id}" timed out after ${this.probeTimeoutMs}ms`),
-        })), { concurrency: this.concurrency });
+        return Effect.forEach(ids, (id) => Effect.result(this.probe(id, includeWrites, this.probeTimeoutMs, new ConnectorCallError("timeout", `${route} probe of "${id}" timed out after ${this.probeTimeoutMs}ms`))), { concurrency: this.concurrency });
+    }
+    // Search's catalogs. A scoped search probes its connector under the full
+    // probe deadline, reads its health record beside the probe, and settles it
+    // after. An unscoped search reads health first, skips a connector whose
+    // discovery failed recently, probes the rest under a shorter deadline, and
+    // settles each record as its probe ends. One discovery budget bounds all of
+    // it, health storage included: a probe that starts late gets only what
+    // remains less a slice kept for settling, and health I/O starts only within
+    // it, then runs to its end. A lapsed record is claimed as its probe is
+    // dispatched, leased to the end of this budget plus a margin.
+    // Caller cancellation and a probe the budget cut short leave health as it was.
+    searchCatalogs(ids, scoped) {
+        return Effect.gen({ self: this }, function* () {
+            const deadline = scoped ? this.probeTimeoutMs : Math.min(this.probeTimeoutMs, UNSCOPED_PROBE_TIMEOUT_MS);
+            const budgetEnd = scoped ? Infinity : Date.now() + this.discoveryBudgetMs;
+            const settleReserve = scoped ? 0 : Math.min(SETTLE_RESERVE_MS, Math.floor(this.discoveryBudgetMs / 10));
+            // Health storage starts only while budget remains and the caller is
+            // here; running out is not a failure, health is then unknown. Once
+            // started, an operation is awaited to its end, never raced or detached:
+            // a storage write cannot be withdrawn once sent (INV-7). The budget
+            // bounds when health work may start, not when it finishes.
+            const withinBudget = (io, unknown) => Effect.suspend(() => Date.now() >= budgetEnd || this.requestSignal?.aborted ? Effect.succeed(unknown) : Effect.uninterruptible(io));
+            // A skip that has lapsed is read again, so this request can claim the probe.
+            const unread = ids.filter((id) => {
+                const known = this.health.get(id);
+                return !known || (!scoped && known.skip !== undefined && known.skip.retryAt <= Date.now());
+            });
+            const readHealth = Effect.map(withinBudget(readDiscoveryHealth(this.registry, unread, this.baseUrl, this.requestScope, { skip: !scoped }), unread.map(() => ({}))), (read) => unread.forEach((id, index) => this.health.set(id, read[index])));
+            // Record what one probe saw, unless the caller left.
+            const settleOne = (outcome) => {
+                const slot = this.health.get(outcome.id)?.slot;
+                const { result, settle } = outcome;
+                if (!settle || !slot || this.requestSignal?.aborted)
+                    return Effect.void;
+                return Effect.map(withinBudget(settleDiscoveryHealth(slot, Result.isSuccess(result)
+                    ? { ok: true }
+                    : {
+                        ok: false,
+                        failure: result.failure,
+                        timedOut: result.failure === settle.timeoutError,
+                        elapsedMs: settle.elapsedMs,
+                    }), undefined), (settled) => {
+                    if (settled)
+                        this.health.set(outcome.id, settled);
+                });
+            };
+            const probeOne = (id) => Effect.gen({ self: this }, function* () {
+                const verdict = scoped ? undefined : this.health.get(id);
+                const skip = verdict?.skip;
+                if (skip && skip.retryAt > Date.now())
+                    return {
+                        id,
+                        result: Result.fail(new DiscoverySkipped(skip.code, Math.ceil(skip.retryAt - Date.now()))),
+                    };
+                const timeoutFor = (remaining) => {
+                    const budgetCut = remaining < deadline;
+                    return {
+                        budgetCut,
+                        timeoutMs: budgetCut ? remaining : deadline,
+                        timeoutError: budgetCut
+                            ? new ConnectorCallError("timeout", `${this.searchRoute} stopped probing "${id}" at the ${this.discoveryBudgetMs}ms discovery budget`)
+                            : new ConnectorCallError("timeout", `${this.searchRoute} probe of "${id}" timed out after ${deadline}ms`),
+                    };
+                };
+                let plan = timeoutFor(Math.ceil(budgetEnd - settleReserve - Date.now()));
+                if (plan.timeoutMs <= 0)
+                    return { id, result: Result.fail(plan.timeoutError) };
+                // A lapsed record: claim this probe now, as it is dispatched. The
+                // lease runs to an absolute time, the end of this request's
+                // discovery budget plus a margin, so however long the claim write
+                // takes, the probe the budget still allows ends inside it.
+                if (skip && verdict?.slot) {
+                    const leaseUntil = budgetEnd + CLAIM_MARGIN_MS;
+                    const claimed = yield* withinBudget(claimDiscoveryProbe(verdict.slot, leaseUntil), false);
+                    if (!claimed) {
+                        this.health.set(id, { slot: verdict.slot, skip: { code: skip.code, retryAt: leaseUntil } });
+                        return {
+                            id,
+                            result: Result.fail(new DiscoverySkipped(skip.code, Math.max(1, Math.ceil(leaseUntil - Date.now())))),
+                        };
+                    }
+                    this.health.set(id, { slot: verdict.slot });
+                    plan = timeoutFor(Math.ceil(budgetEnd - settleReserve - Date.now()));
+                    if (plan.timeoutMs <= 0)
+                        return { id, result: Result.fail(plan.timeoutError) };
+                }
+                const started = Date.now();
+                const result = yield* Effect.result(this.probe(id, false, plan.timeoutMs, plan.timeoutError));
+                // Elapsed time is this probe's own, measured as it settles.
+                const elapsedMs = Date.now() - started;
+                const outcome = plan.budgetCut && Result.isFailure(result) && result.failure === plan.timeoutError
+                    ? { id, result }
+                    : { id, result, settle: { timeoutError: plan.timeoutError, elapsedMs } };
+                if (scoped)
+                    return outcome;
+                yield* settleOne(outcome);
+                return { id, result };
+            });
+            if (!scoped) {
+                yield* readHealth;
+                const probed = yield* Effect.forEach(ids, probeOne, { concurrency: this.concurrency });
+                return probed.map((outcome) => outcome.result);
+            }
+            const [, probed] = yield* Effect.all([readHealth, Effect.forEach(ids, probeOne, { concurrency: this.concurrency })], { concurrency: 2 });
+            yield* Effect.forEach(probed, settleOne, { concurrency: "unbounded" });
+            return probed.map((outcome) => outcome.result);
+        });
+    }
+    probe(id, includeWrites, timeoutMs, timeoutError) {
+        return withDeadlineEffect((signal) => Effect.map(this.catalog(id, { signal }), (tools) => this.searchView(id, tools, includeWrites, "all")), { ...(this.requestSignal ? { signal: this.requestSignal } : {}), timeoutMs, timeoutError });
     }
     /**
      * Every visible catalog as discovery shows it, for a native `tools/list`:
@@ -619,6 +786,15 @@ export class CatalogService {
     }
     catalogFailure(connector, failure) {
         return Effect.gen({ self: this }, function* () {
+            if (failure instanceof DiscoverySkipped) {
+                return {
+                    connector: connector.id,
+                    code: failure.code,
+                    message: `Connector "${connector.id}" was skipped because its catalog lookup failed recently (${failure.code}). Search with connector "${connector.id}" to try it now.`,
+                    retryable: true,
+                    retryAfterMs: failure.retryAfterMs,
+                };
+            }
             const classified = classifyCallError(failure, "catalog_lookup_failed");
             const error = {
                 connector: connector.id,
@@ -700,11 +876,16 @@ export class CatalogService {
                 : undefined;
             const connectors = absence ? [] : args.connector ? (scopedConnector ? [scopedConnector] : []) : visibleConnectors;
             // Timeout messages name the route the caller used.
-            const catalogs = yield* this.discoveryCatalogs(connectors.map((connector) => connector.id), this.searchRoute);
+            const catalogs = yield* this.searchCatalogs(connectors.map((connector) => connector.id), args.connector !== undefined);
             const searchableCatalogs = catalogs.map((catalog, index) => Result.map(catalog, (tools) => this.searchView(connectors[index].id, tools, true, safety)));
             const matches = [];
             let matchMode = "all";
-            const statistics = lexicalCorpusStatistics(searchableCatalogs.flatMap((catalog) => (Result.isSuccess(catalog) ? [catalog.success] : [])), retrievalQuery);
+            // Provider-declared synonyms widen term matching within their own catalog only.
+            const synonymsFor = (tools) => {
+                const index = searchableCatalogs.findIndex((catalog) => Result.isSuccess(catalog) && catalog.success === tools);
+                return index < 0 ? undefined : searchSynonyms(connectors[index]);
+            };
+            const statistics = lexicalCorpusStatistics(searchableCatalogs.flatMap((catalog) => (Result.isSuccess(catalog) ? [catalog.success] : [])), retrievalQuery, synonymsFor);
             const trimmedQuery = query.trim();
             const isBrowse = trimmedQuery.length === 0;
             const queryTerms = lexicalQueryTerms(retrievalQuery);
@@ -716,8 +897,10 @@ export class CatalogService {
             const displayTerm = (term) => boundedQueryTerm(term).text;
             const queryMetadataTruncated = analysisTerms.length > analyzedTerms.length || analyzedTerms.some((term) => boundedQueryTerm(term).truncated);
             const vocabularyTools = new Set();
+            const readyFound = [];
             const collectMatches = (mode) => {
                 const collected = [];
+                readyFound.length = 0;
                 let orderBase = 0;
                 searchableCatalogs.forEach((catalog, connectorIndex) => {
                     const connector = connectors[connectorIndex];
@@ -734,7 +917,7 @@ export class CatalogService {
                                 : []),
                         ]);
                         const localStatistics = exactConnector
-                            ? lexicalCorpusStatistics([catalog.success], retrievalQuery)
+                            ? lexicalCorpusStatistics([catalog.success], retrievalQuery, synonymsFor)
                             : undefined;
                         // An exact identity is a browse even when one tool repeats that
                         // identity in its name or description. Action queries still keep
@@ -754,7 +937,12 @@ export class CatalogService {
                         const rankedTools = rankTools(catalog.success, toolQuery, mode, statistics, query);
                         const original = catalogs[connectorIndex];
                         if (!isBrowse && query.length <= 200 && queryTerms.length <= 8 && Result.isSuccess(original)) {
-                            for (const tool of operationVocabularyMatches(connector, original.success, toolTerms.filter((term) => !connectorTerms.has(term)).join(" "), safety, this.readOnly)) {
+                            const vocabulary = operationVocabularyMatches(connector, original.success, toolTerms.filter((term) => !connectorTerms.has(term)).join(" "), safety, this.readOnly);
+                            // At most one ready call per connector: its first hatch's top operation.
+                            const ready = vocabulary.ready[0];
+                            if (ready && !readyFound.some((found) => found.connector === connector))
+                                readyFound.push({ connector, ...ready });
+                            for (const tool of vocabulary.tools) {
                                 vocabularyTools.add(tool);
                                 if (!rankedTools.some((match) => match.tool === tool))
                                     rankedTools.push({
@@ -798,9 +986,14 @@ export class CatalogService {
             if (!isBrowse && !unsearchableQuery && completeMatchCount === 0) {
                 matchMode = "partial";
             }
+            // A read-intent verb leads the query once connector names are set aside.
+            const identityTerms = new Set(connectors.flatMap(connectorNames).flatMap(lexicalQueryTerms));
+            const readIntent = READ_INTENT.test(lexicalQueryTerms(query).find((term) => !identityTerms.has(term)) ?? "");
+            const readFirst = (match) => Number(readIntent && match.tool.classification === "read");
             // Exact tool names precede connector identity and lexical scoring. A
             // longer name such as get_issue_status cannot beat an exact get_issue
-            // merely because its description repeats rare query terms.
+            // merely because its description repeats rare query terms. Within a
+            // tier, a read-intent query puts reads before writes.
             matches.sort((a, b) => {
                 const aFirstTier = a.complete || a.exactName;
                 const bFirstTier = b.complete || b.exactName;
@@ -808,6 +1001,7 @@ export class CatalogService {
                     Number(b.exactName) - Number(a.exactName) ||
                     b.connectorRank - a.connectorRank ||
                     Number(bFirstTier) - Number(aFirstTier) ||
+                    readFirst(b) - readFirst(a) ||
                     b.score - a.score ||
                     a.order - b.order);
             });
@@ -883,6 +1077,40 @@ export class CatalogService {
                     },
                 };
             });
+            // An exact name already answers the query, and so does a complete match
+            // on an authored tool (not the hatch's own) whose name adds nothing to
+            // the query: each name word is an action, or a query word up to
+            // plural/singular and declared synonyms. `list_teams` answers "list
+            // teams"; `list_project_env_vars` does not answer "list projects".
+            const top = matches[0];
+            const synonymsOfTop = top && searchSynonyms(top.connector);
+            const asked = queryTerms.flatMap((term) => [term, ...(synonymsOfTop?.(term) ?? [])]);
+            const answered = top !== undefined &&
+                (top.exactLookup ||
+                    top.exactName ||
+                    (top.complete &&
+                        !vocabularyTools.has(top.tool) &&
+                        !readyFound.some((ready) => ready.tool === top.tool) &&
+                        lexicalQueryTerms(top.tool.name).every((word) => ACTION_WORD.test(word) || asked.some((term) => matchesLexicalTerm(word, term)))));
+            const readyCalls = offset === 0 && !answered
+                ? readyFound.slice(0, MAX_READY_CALLS).map(({ connector, tool, path, summary }) => {
+                    const reasons = guideRequiredReasons(connector, tool, false);
+                    const guideSummary = connectorGuideSummary(connector);
+                    return {
+                        connector,
+                        call: {
+                            address: `${connector.id}.${tool.name}`,
+                            args: { path },
+                            classification: "read",
+                            summary,
+                            ...(reasons ? { guideRequired: true, guideRequiredReasons: reasons } : {}),
+                        },
+                        ...(connectorGuide(connector)
+                            ? { guide: connectorSkillName(connector.id), ...(guideSummary ? { guideSummary } : {}) }
+                            : {}),
+                    };
+                })
+                : [];
             const nextOffset = offset + entries.length < matches.length ? offset + entries.length : undefined;
             const pageTools = new Set(pageMatches.map((match) => match.tool));
             const matchingTools = (term) => new Set([
@@ -1058,6 +1286,8 @@ export class CatalogService {
                 onCatalogReference?.(connector.id);
             for (const entry of entries)
                 onCatalogReference?.(entry.connector.id, entry.tool.name);
+            for (const { connector, call } of readyCalls)
+                onCatalogReference?.(connector.id, call.address.slice(connector.id.length + 1));
             for (const pointer of apiSearchPointers)
                 onCatalogReference?.(pointer.connector, pointer.tool);
             for (const connector of absence?.configuredConnectors ?? [])
@@ -1070,6 +1300,7 @@ export class CatalogService {
                 catalogErrors,
                 ...(absence ? { absence } : {}),
                 entries,
+                ...(readyCalls.length ? { readyCalls } : {}),
                 total: matches.length,
                 offset,
                 limit,
@@ -1264,17 +1495,23 @@ function pageTail(page) {
     };
 }
 export function flatSearchResult(page) {
+    // fromEntries keeps an id such as "__proto__" an own key.
+    const connectors = new Map();
+    for (const { connector, guide, guideSummary } of [...page.entries, ...(page.readyCalls ?? [])]) {
+        const title = connector.title && boundedEchoText(connector.title.replace(/\s+/g, " ").trim(), 117);
+        if (title || guide)
+            connectors.set(connector.id, {
+                ...(title ? { title } : {}),
+                ...(guide ? { guide } : {}),
+                ...(guideSummary ? { guideSummary } : {}),
+            });
+    }
     return {
         catalogErrors: page.catalogErrors,
         ...(page.absence ? { absence: page.absence } : {}),
-        tools: page.entries.map((entry) => ({
-            ...entry.tool,
-            ...(entry.connector.title
-                ? { connectorTitle: boundedEchoText(entry.connector.title.replace(/\s+/g, " ").trim(), 117) }
-                : {}),
-            ...(entry.guide ? { guide: entry.guide } : {}),
-            ...(entry.guideSummary ? { guideSummary: entry.guideSummary } : {}),
-        })),
+        tools: page.entries.map((entry) => entry.tool),
+        ...(page.readyCalls ? { readyCalls: page.readyCalls.map((ready) => ready.call) } : {}),
+        ...(connectors.size ? { connectors: Object.fromEntries(connectors) } : {}),
         ...pageTail(page),
     };
 }

package/dist/catalog.js

@@ -255,7 +255,23 @@ export function matchesLexicalTerm(text, term) {
  * connector rank, so ubiquitous words contribute less than discriminative
  * ones without making any action word a stopword.
  */
-export function lexicalCorpusStatistics(toolSets, query) {
+/** Whole-token candidates for one term, widened by a catalog's lexical synonyms. */
+function synonymCandidates(term, synonyms) {
+    const own = matchingTokenCandidates(term);
+    if (!synonyms)
+        return own;
+    const candidates = new Set(own);
+    for (const candidate of own)
+        for (const synonym of synonyms(candidate))
+            for (const variant of matchingTokenCandidates(synonym))
+                candidates.add(variant);
+    return candidates;
+}
+/**
+ * `synonymsFor` gives a catalog's lexical synonyms, word to equivalent words:
+ * a term then matches a tool through any of them, as plain whole tokens.
+ */
+export function lexicalCorpusStatistics(toolSets, query, synonymsFor) {
     const terms = lexicalQueryTerms(query);
     if (terms.length === 0) {
         return {
@@ -272,7 +288,7 @@ export function lexicalCorpusStatistics(toolSets, query) {
         const termDescriptionMatches = new Set();
         for (const tools of toolSets) {
             const index = indexFor(tools);
-            for (const candidate of matchingTokenCandidates(term)) {
+            for (const candidate of synonymCandidates(term, synonymsFor?.(tools))) {
                 for (const tool of index.nameTokenDocuments.get(candidate) ?? []) {
                     termNameMatches.add(tool);
                 }

package/dist/config.d.ts

@@ -18,8 +18,10 @@ declare const discovery: {
     /**
      * Deadline (ms) for each downstream probe/catalog call fanned out by
      * `search_tools` and by `connecta.search`/`connecta.describe` inside
-     * `execute_code`. Defaults to 30_000. A timed-out connector degrades
-     * independently; this does not apply to tool calls. Catalog walks receive the
+     * `execute_code`. Defaults to 30_000. An unscoped search caps each probe at
+     * 5_000 and its whole fan-out at 9_000, and skips a connector whose
+     * discovery recently timed out for up to 60 seconds. A timed-out connector
+     * degrades independently; this does not apply to tool calls. Catalog walks receive the
      * same cancellation signal, which aborts an in-flight page where supported and
      * prevents another from starting.
      */
@@ -191,8 +193,9 @@ declare const pool: {
     /**
      * Who may open `/mcp/<name>`: principal ids in the namespace of the one
      * interactive auth provider, `{ namespace, id }`, or `"agent:<name>"` for a
-     * declared agent. Required and non-empty; the pool serves exactly its
-     * `tools` to these members and the same 404 to everyone else.
+     * declared agent. All members must be people or all must be agents. Required
+     * and non-empty; the pool serves exactly its `tools` to these members and
+     * the same 404 to everyone else.
      */
     members: import("./config-schema.js").Field<readonly MemberRef[], readonly MemberRef[], false>;
     /**
@@ -200,8 +203,8 @@ declare const pool: {
      * connector whose `subject` is a mapping function. Humans always act as
      * themselves through that mapping, and a fixed `subject` address applies to
      * everyone. Without an owner, a mapping-subject Workspace connector is
-     * absent for this pool's agents, as a personal connector is; people in the
-     * pool still see it.
+     * absent for this pool's agents, as a personal connector is. People use a
+     * separate pool and always act as themselves.
      */
     owner: import("./config-schema.js").Field<string, string | undefined, true>;
     /**
@@ -218,7 +221,7 @@ declare const pool: {
      * `<connector>__<tool>` and annotated from its classification, for clients
      * that run their own tool search; calls take the same invocation path.
      */
-    surface: import("./config-schema.js").Field<"native" | "meta", "native" | "meta" | undefined, true>;
+    surface: import("./config-schema.js").Field<"meta" | "native", "meta" | "native" | undefined, true>;
     /**
      * `false` drops `execute_code` from a native pool and lists `read_result`
      * for paging instead. Only valid with `surface: "native"`: the meta surface
@@ -254,7 +257,7 @@ declare const connectaConfig: {
         readOnly?: boolean | undefined;
         owner?: string | undefined;
         description?: string | undefined;
-        surface?: "native" | "meta" | undefined;
+        surface?: "meta" | "native" | undefined;
         executeCode?: boolean | undefined;
         tools: readonly string[];
         members: readonly MemberRef[];
@@ -264,7 +267,7 @@ declare const connectaConfig: {
         readonly members: readonly MemberRef[];
         readonly owner: string | undefined;
         readonly description: string | undefined;
-        readonly surface: "native" | "meta" | undefined;
+        readonly surface: "meta" | "native" | undefined;
         readonly executeCode: boolean | undefined;
     }>> | undefined, true>;
     /** Exact connector id -> tool name -> verdict. Hidden tools cannot be discovered or called.
@@ -326,8 +329,10 @@ declare const connectaConfig: {
             /**
              * Deadline (ms) for each downstream probe/catalog call fanned out by
              * `search_tools` and by `connecta.search`/`connecta.describe` inside
-             * `execute_code`. Defaults to 30_000. A timed-out connector degrades
-             * independently; this does not apply to tool calls. Catalog walks receive the
+             * `execute_code`. Defaults to 30_000. An unscoped search caps each probe at
+             * 5_000 and its whole fan-out at 9_000, and skips a connector whose
+             * discovery recently timed out for up to 60 seconds. A timed-out connector
+             * degrades independently; this does not apply to tool calls. Catalog walks receive the
              * same cancellation signal, which aborts an in-flight page where supported and
              * prevents another from starting.
              */