@zackbart/connecta 0.28.1 → 0.30.0

package/dist/catalog-service.js

@@ -1,12 +1,14 @@
+import { withAuthorizationHandoff } from "./authorization-handoff.js";
+import { carryCatalogFreshness, catalogIsFresh } from "./catalog-freshness.js";
+import { hasControlCharacters } from "./tool-name.js";
 import { Effect, Result } from "effect";
 import { compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, typescriptSignature, } from "./catalog.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
-import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
-import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
+import { boundedEchoText, classifyCallError, ConnectorCallError, framingError } from "./errors.js";
+import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName } from "./skills.js";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { SharedRead } from "./runtime/shared-read.js";
-import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, } from "./timeout.js";
-import { isApprovalExempt, isExplicitlyReadOnly, NO_EXEMPTIONS, } from "./tool-safety.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs } from "./timeout.js";
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
@@ -20,6 +22,49 @@ const MAX_QUERY_TERM_LENGTH = 64;
  */
 const MAX_IDENTITY_CONNECTORS = 3;
 const MAX_DESCRIBE_SUGGESTIONS = 3;
+// Recognized service names are query vocabulary, never a deployment inventory.
+// Unknown/custom services use the explicit connector scope. Keep this independent
+// of provider implementations so discovery cannot pull them into root imports.
+const SERVICE_NAMES = [
+    "GitHub",
+    "GitLab",
+    "Supabase",
+    "PostHog",
+    "Linear",
+    "Mixpanel",
+    "RevenueCat",
+    "Stripe",
+    "Notion",
+    "Slack",
+    "Vercel",
+    "Cloudflare",
+    "Basecamp",
+    "Breeze",
+    "Tithely",
+    "Planning Center",
+    "Google Drive",
+    "Google Docs",
+    "Google Sheets",
+    "Google Slides",
+    "Gmail",
+];
+function normalizedPhrase(text) {
+    return lexicalQueryTerms(text.toLowerCase()).join(" ");
+}
+function containsPhrase(query, phrase) {
+    const normalized = normalizedPhrase(phrase);
+    return normalized.length > 0 && ` ${normalizedPhrase(query)} `.includes(` ${normalized} `);
+}
+function connectorNames(connector) {
+    return [connector.id, ...(connector.title ? [connector.title] : [])];
+}
+function connectorMatchRank(query, connector) {
+    if (connectorNames(connector).some((name) => containsPhrase(query, name)))
+        return 2;
+    return SERVICE_NAMES.some((service) => containsPhrase(query, service) && connectorNames(connector).some((name) => containsPhrase(name, service)))
+        ? 1
+        : 0;
+}
 const encoder = new TextEncoder();
 /** Clip one echoed query term without splitting a non-BMP code point. */
 function boundedQueryTerm(term) {
@@ -47,10 +92,7 @@ export class DiscoveryPolicyError extends Error {
 function discoverySearchLimit(value) {
     if (value === undefined)
         return DEFAULT_SEARCH_LIMIT;
-    if (typeof value !== "number" ||
-        !Number.isInteger(value) ||
-        value < 1 ||
-        value > MAX_SEARCH_LIMIT) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > MAX_SEARCH_LIMIT) {
         throw new DiscoveryPolicyError("invalid_args", `limit must be a whole number from 1 through ${MAX_SEARCH_LIMIT}. Page through larger catalogs with offset.`);
     }
     return value;
@@ -60,11 +102,7 @@ function discoveryAddresses(args) {
     if (args.address !== undefined && args.addresses !== undefined) {
         throw new DiscoveryPolicyError("invalid_args", "describe takes either address or addresses, not both.");
     }
-    const value = args.address !== undefined
-        ? typeof args.address === "string"
-            ? [args.address]
-            : undefined
-        : args.addresses;
+    const value = args.address !== undefined ? (typeof args.address === "string" ? [args.address] : undefined) : args.addresses;
     if (!Array.isArray(value)) {
         throw new DiscoveryPolicyError("invalid_args", 'describe takes { address: "<connectorId>.<toolName>" } or { addresses: ["<connectorId>.<toolName>", ...] }.');
     }
@@ -89,8 +127,7 @@ function editDistance(left, right) {
     for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
         const current = [leftIndex + 1];
         for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
-            current.push(Math.min(previous[rightIndex + 1] + 1, current[rightIndex] + 1, previous[rightIndex] +
-                (left[leftIndex] === right[rightIndex] ? 0 : 1)));
+            current.push(Math.min(previous[rightIndex + 1] + 1, current[rightIndex] + 1, previous[rightIndex] + (left[leftIndex] === right[rightIndex] ? 0 : 1)));
         }
         previous = current;
     }
@@ -99,7 +136,7 @@ function editDistance(left, right) {
 /** Nearby names only; descriptions never influence describe-miss recovery. */
 function describeSuggestions(connectorId, attemptedName, tools) {
     const attempted = attemptedName.toLowerCase();
-    return tools
+    return (tools
         .map((tool, order) => {
         const name = tool.name.toLowerCase();
         return { tool, order, distance: editDistance(attempted, name) };
@@ -115,7 +152,7 @@ function describeSuggestions(connectorId, attemptedName, tools) {
         // A clipped address would no longer be canonical. Omit an implausibly
         // large catalog name instead of letting one suggestion erase the page.
         .filter((address) => boundedEchoText(address) === address)
-        .slice(0, MAX_DESCRIBE_SUGGESTIONS);
+        .slice(0, MAX_DESCRIBE_SUGGESTIONS));
 }
 /** Serialize once and count the exact bytes the MCP adapter would emit. */
 export function boundedDiscoveryText(value, hint) {
@@ -132,9 +169,7 @@ export function boundedDiscoveryText(value, hint) {
 function discoverySafety(value) {
     if (value === undefined)
         return "all";
-    if (value !== "readOnly" &&
-        value !== "approvalRequired" &&
-        value !== "all") {
+    if (value !== "readOnly" && value !== "approvalRequired" && value !== "all") {
         throw new DiscoveryPolicyError("invalid_args", 'safety must be "readOnly", "approvalRequired", or "all".');
     }
     return value;
@@ -142,9 +177,7 @@ function discoverySafety(value) {
 function toolsForSafety(tools, safety) {
     if (safety === "all")
         return tools;
-    return tools.filter((tool) => safety === "readOnly"
-        ? isExplicitlyReadOnly(tool)
-        : !isExplicitlyReadOnly(tool));
+    return tools.filter((tool) => safety === "readOnly" ? tool.classification === "read" : tool.classification !== "read");
 }
 /**
  * Reasons discovery can determine without reading arguments or guessing at a
@@ -157,7 +190,7 @@ function guideRequiredReasons(connector, tool, schemaTruncated) {
     const reasons = [];
     if (connectorGuideRequired(connector))
         reasons.push("connector_required");
-    if (!isExplicitlyReadOnly(tool))
+    if (tool.classification !== "read")
         reasons.push("approval_required");
     if (schemaTruncated)
         reasons.push("schema_truncated");
@@ -178,11 +211,152 @@ function schemaKeyMetadata(input, output) {
                 requiredInputKeys: inputKeys.required,
             }
             : {}),
-        ...(outputKeys && outputKeys.properties.length > 0
-            ? { outputKeys: outputKeys.properties }
-            : {}),
+        ...(outputKeys && outputKeys.properties.length > 0 ? { outputKeys: outputKeys.properties } : {}),
     };
 }
+const stringListSchema = { type: "array", items: { type: "string" } };
+const guideProperties = {
+    guide: { type: "string" },
+    guideSummary: { type: "string" },
+    guideRequired: { const: true },
+    guideRequiredReasons: {
+        type: "array",
+        items: { enum: ["connector_required", "approval_required", "schema_truncated"] },
+    },
+};
+const catalogFailureProperties = {
+    code: { type: "string" },
+    message: { type: "string" },
+    retryable: { type: "boolean" },
+    retryAfterMs: { type: "integer", minimum: 0 },
+    connector: { type: "string" },
+    recovery: { enum: ["oauth", "operator_config", "unavailable"] },
+    status: { const: "auth_required" },
+    authorizationUrl: { type: "string" },
+    operatorUrl: { type: "string" },
+    instructions: { type: "string" },
+    credential: {
+        type: "object",
+        required: ["label", "fields"],
+        additionalProperties: false,
+        properties: {
+            label: { type: "string" },
+            fields: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["name"],
+                    additionalProperties: false,
+                    properties: { name: { type: "string" }, guidance: { type: "string" } },
+                },
+            },
+        },
+    },
+    retry: { type: "string" },
+    nextAction: {
+        type: "object",
+        required: ["tool", "arguments", "operatorHandoff"],
+        additionalProperties: false,
+        properties: {
+            tool: { const: "authorize_connector" },
+            arguments: {
+                type: "object",
+                required: ["connector"],
+                additionalProperties: false,
+                properties: { connector: { type: "string" } },
+            },
+            operatorHandoff: { type: "string" },
+        },
+    },
+};
+/**
+ * The outputSchema contract for either search adapter. Guest API registration
+ * can reuse this value instead of maintaining a second page definition.
+ */
+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,
+                },
+            },
+        },
+        absence: {
+            type: "object",
+            required: ["service", "message", "configuredConnectors"],
+            additionalProperties: false,
+            properties: {
+                service: { type: "string" },
+                message: { type: "string" },
+                configuredConnectors: stringListSchema,
+            },
+        },
+        tools: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["name", "address"],
+                additionalProperties: false,
+                properties: {
+                    name: { type: "string" },
+                    address: { type: "string" },
+                    connectorTitle: { type: "string" },
+                    description: { type: "string" },
+                    inputSchema: {},
+                    outputSchema: {},
+                    signature: { type: "string" },
+                    schemaFormat: { enum: ["json", "text"] },
+                    outputSchemaSource: { const: "observed" },
+                    inputSchemaTruncated: { const: true },
+                    outputSchemaTruncated: { const: true },
+                    inputKeys: stringListSchema,
+                    requiredInputKeys: stringListSchema,
+                    outputKeys: stringListSchema,
+                    annotations: { type: "object" },
+                    classification: { enum: ["read", "write"] },
+                    ...guideProperties,
+                },
+            },
+        },
+        total: { type: "integer", minimum: 0 },
+        offset: { type: "integer", minimum: 0 },
+        limit: { type: "integer", minimum: 1, maximum: MAX_SEARCH_LIMIT },
+        hasMore: { type: "boolean" },
+        nextOffset: { type: "integer", minimum: 0 },
+        matchMode: { const: "partial" },
+        queryAnalysis: {
+            type: "object",
+            required: ["representedTerms", "otherResultTerms", "unmatchedTerms"],
+            additionalProperties: false,
+            properties: {
+                representedTerms: stringListSchema,
+                otherResultTerms: stringListSchema,
+                unmatchedTerms: stringListSchema,
+                truncated: { const: true },
+                connectorScope: { type: "string" },
+                unknownConnector: { const: true },
+                configuredConnectors: stringListSchema,
+                unavailableConnectorCount: { type: "integer", minimum: 0 },
+                catalogError: {
+                    type: "object",
+                    required: ["code", "message", "retryable"],
+                    additionalProperties: false,
+                    properties: catalogFailureProperties,
+                },
+                ...guideProperties,
+                guidance: { type: "string" },
+            },
+        },
+    },
+};
 function renderSearchSchema(schema, format) {
     if (format === "json")
         return { schema, truncated: false };
@@ -198,16 +372,17 @@ export class CatalogService {
     registry;
     baseUrl;
     requestScope;
+    defer;
     probeTimeoutMs;
     concurrency;
     searchRoute;
-    readOptions;
     requestSignal;
-    approval;
     // The request-scoped catalog cache: one shared read per connector asked
     // about, started by the first asker and joined by every later one. A
     // success stays for the rest of the request, so a search and the call after
-    // it see one catalog; a failure, or a read cancelled because every asker
+    // it see one catalog. The cache owns a deep copy and each asker receives
+    // another, so discovery, invocation, and guest code never hold its objects.
+    // A failure, or a read cancelled because every asker
     // left it, is dropped so the next ask reads again. The service lives and
     // dies with one request, so no read here is ever awaited from another.
     //
@@ -220,19 +395,12 @@ export class CatalogService {
     constructor(registry, baseUrl, options = {}) {
         this.registry = registry;
         this.baseUrl = baseUrl;
-        this.approval = options.approval ?? NO_EXEMPTIONS;
         this.requestScope = options.requestScope ?? {};
-        this.probeTimeoutMs =
-            normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
+        this.probeTimeoutMs = normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
         this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
         this.searchRoute = options.searchRoute ?? "search_tools";
         this.requestSignal = options.requestSignal;
-        this.readOptions = options.defer
-            ? {
-                defer: options.defer,
-                refreshTimeoutMs: this.probeTimeoutMs,
-            }
-            : undefined;
+        this.defer = options.defer;
     }
     /**
      * Send a caller back to discovery through the surface it can actually reach.
@@ -269,7 +437,13 @@ export class CatalogService {
         return Effect.suspend(() => {
             let read = this.catalogs.get(id);
             if (!read) {
-                const started = new SharedRead((signal) => this.registry.getTools(id, this.baseUrl, this.requestScope, { signal, timeoutMs: this.probeTimeoutMs }, this.readOptions), (succeeded) => {
+                const started = new SharedRead((signal) => this.registry
+                    .getTools(id, this.baseUrl, this.requestScope, {
+                    signal,
+                    timeoutMs: this.probeTimeoutMs,
+                    ...(this.defer ? { defer: this.defer } : {}),
+                })
+                    .then((tools) => carryCatalogFreshness(tools, structuredClone(tools))), (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) === started) {
@@ -279,7 +453,7 @@ export class CatalogService {
                 this.catalogs.set(id, started);
                 read = started;
             }
-            return read.join(callOptions.signal);
+            return Effect.map(read.join(callOptions.signal), (tools) => carryCatalogFreshness(tools, structuredClone(tools)));
         });
     }
     // Every named catalog under its own probe deadline, `concurrency` at a time,
@@ -291,22 +465,21 @@ export class CatalogService {
         return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => this.catalog(id, { signal }), {
             ...(this.requestSignal ? { signal: this.requestSignal } : {}),
             timeoutMs: this.probeTimeoutMs,
-            timeoutError: new Error(`${route} probe of "${id}" timed out after ${this.probeTimeoutMs}ms`),
+            timeoutError: new ConnectorCallError("timeout", `${route} probe of "${id}" timed out after ${this.probeTimeoutMs}ms`),
         })), { concurrency: this.concurrency });
     }
     outputSchema(connectorId, tool) {
         if (tool.outputSchema)
             return { schema: tool.outputSchema };
         const observed = this.registry.observedOutputSchema(connectorId, tool);
-        return observed
-            ? { schema: observed, source: "observed" }
-            : {};
+        return observed ? { schema: observed, source: "observed" } : {};
     }
     unknownAddressFailure(address, query) {
         return {
             ok: false,
             error: {
                 ...framingError("unknown_address", `Unknown address "${boundedEchoText(address)}"`),
+                configuredConnectors: this.registry.listConnectors().map((connector) => connector.id),
                 nextAction: this.searchRecovery({ query: recoveryQuery(query) }, "Find the configured canonical address before retrying."),
             },
             catalogMs: 0,
@@ -326,8 +499,10 @@ export class CatalogService {
         return {
             ok: false,
             error: {
-                ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(toolName)}" on connector "${connector.id}"`),
-                nextAction: this.searchRecovery({ query: recoveryQuery(toolName), connector: connector.id }, "Find the connector's current canonical tool address."),
+                ...framingError("unknown_tool", hasControlCharacters(toolName)
+                    ? `Unknown tool on connector "${connector.id}"`
+                    : `Unknown tool "${boundedEchoText(toolName)}" on connector "${connector.id}"`),
+                nextAction: this.searchRecovery({ query: hasControlCharacters(toolName) ? "" : recoveryQuery(toolName), connector: connector.id }, "Find the connector's current canonical tool address."),
             },
             catalogMs: Date.now() - started,
             connector,
@@ -357,19 +532,56 @@ export class CatalogService {
                     }
                     return {
                         ok: true,
-                        resolved: { connector, toolName, definition },
+                        resolved: { connector, toolName, definition, classificationFresh: catalogIsFresh(tools) },
                         catalogMs: Date.now() - started,
                     };
                 },
             });
         });
     }
+    async catalogFailure(connector, failure) {
+        const classified = classifyCallError(failure, "catalog_lookup_failed");
+        const error = {
+            connector: connector.id,
+            code: classified.code,
+            // Catalog discovery reports recovery facts, never connector-authored
+            // error text. Clipping a downstream message does not make it safe.
+            message: classified.code === "downstream_oauth_required"
+                ? `Connector "${connector.id}" requires downstream OAuth authorization. When an auth error includes a handoff, give it to the user or operator.`
+                : classified.code === "auth_required"
+                    ? `Connector "${connector.id}" requires operator-managed credentials or configuration. When an auth error includes a handoff, give it to the user or operator.`
+                    : classified.code === "provider_permission_denied"
+                        ? `Connector "${connector.id}" requires permission from the provider's resource owner or administrator. Reconnecting alone will not grant access.`
+                        : `Connector "${connector.id}" catalog lookup failed (${classified.code}).`,
+            retryable: classified.retryable,
+            ...(classified.retryAfterMs === undefined ? {} : { retryAfterMs: classified.retryAfterMs }),
+        };
+        if (error.code === "auth_required" || error.code === "downstream_oauth_required") {
+            error.recovery = connector.startAuth
+                ? "oauth"
+                : this.registry.credentialUiAvailable() &&
+                    connector.credential &&
+                    this.registry.contextFor(connector.id, this.baseUrl, this.requestScope).credential
+                    ? "operator_config"
+                    : "unavailable";
+            error.nextAction = {
+                tool: "authorize_connector",
+                arguments: { connector: connector.id },
+                operatorHandoff: "Give the URL and instructions it returns to the operator.",
+            };
+            error.retry = `Retry discovery after the operator completes recovery for "${connector.id}".`;
+        }
+        else if (error.code === "provider_permission_denied") {
+            error.retry =
+                "Ask the provider's resource owner or administrator to grant the required permission or scope, then retry. Reconnecting alone will not grant access.";
+        }
+        return withAuthorizationHandoff(this.requestScope, error);
+    }
     async search(args) {
         if (args.query !== undefined && typeof args.query !== "string") {
             throw new DiscoveryPolicyError("invalid_args", "query must be a string. Omit it or use an empty string to browse the catalog.");
         }
-        if (args.connector !== undefined &&
-            boundedEchoText(args.connector) !== args.connector) {
+        if (args.connector !== undefined && boundedEchoText(args.connector) !== args.connector) {
             // The scope is echoed back as `queryAnalysis.connectorScope`; a clipped
             // copy could name a different connector, so refuse instead of clamping.
             throw new DiscoveryPolicyError("invalid_args", "connector must be at most 512 UTF-8 bytes.");
@@ -378,38 +590,44 @@ export class CatalogService {
         const retrievalQuery = lexicalSearchQuery(query);
         const safety = discoverySafety(args.safety);
         const limit = discoverySearchLimit(args.limit);
-        if (args.offset !== undefined && (typeof args.offset !== "number" ||
-            !Number.isInteger(args.offset) ||
-            args.offset < 0)) {
+        if (args.offset !== undefined &&
+            (typeof args.offset !== "number" || !Number.isInteger(args.offset) || args.offset < 0)) {
             throw new DiscoveryPolicyError("invalid_args", "offset must be a non-negative whole number. Start at 0 or use the previous page's nextOffset.");
         }
         const offset = args.offset ?? 0;
-        const scopedConnector = args.connector
-            ? this.registry.getConnector(args.connector)
+        const scopedConnector = args.connector ? this.registry.getConnector(args.connector) : undefined;
+        const visibleConnectors = this.registry.listConnectors();
+        const namedService = !args.connector ? SERVICE_NAMES.find((name) => containsPhrase(query, name)) : undefined;
+        const absentService = args.connector && !scopedConnector
+            ? args.connector
+            : namedService &&
+                !visibleConnectors.some((connector) => connectorNames(connector).some((name) => containsPhrase(name, namedService)))
+                ? namedService
+                : undefined;
+        const absence = absentService
+            ? {
+                service: absentService,
+                message: `No connector for "${absentService}" is configured for this endpoint.`,
+                configuredConnectors: visibleConnectors.map((connector) => connector.id),
+            }
             : undefined;
-        const connectors = args.connector
-            ? scopedConnector
-                ? [scopedConnector]
-                : []
-            : this.registry.listConnectors();
-        // Named for this service's route: a scoped search echoes a timed-out
-        // probe's message back as `queryAnalysis.catalogError`, and a program
-        // cannot call search_tools.
+        const connectors = absence ? [] : args.connector ? (scopedConnector ? [scopedConnector] : []) : visibleConnectors;
+        // Timeout messages name the route the caller used.
         const catalogs = await runEdge(this.discoveryCatalogs(connectors.map((connector) => connector.id), this.searchRoute));
         const searchableCatalogs = catalogs.map((catalog) => Result.map(catalog, (tools) => toolsForSafety(tools, safety)));
         const matches = [];
         let matchMode = "all";
-        const statistics = lexicalCorpusStatistics(searchableCatalogs.flatMap((catalog) => Result.isSuccess(catalog) ? [catalog.success] : []), retrievalQuery);
+        const statistics = lexicalCorpusStatistics(searchableCatalogs.flatMap((catalog) => (Result.isSuccess(catalog) ? [catalog.success] : [])), retrievalQuery);
         const trimmedQuery = query.trim();
         const isBrowse = trimmedQuery.length === 0;
         const queryTerms = lexicalQueryTerms(retrievalQuery);
+        const rawPhrase = lexicalQueryTerms(query).join(" ");
         const queryTermCount = queryTerms.length;
         const unsearchableQuery = !isBrowse && queryTermCount === 0;
         const analysisTerms = unsearchableQuery ? [trimmedQuery] : queryTerms;
         const analyzedTerms = analysisTerms.slice(0, MAX_QUERY_TERMS);
         const displayTerm = (term) => boundedQueryTerm(term).text;
-        const queryMetadataTruncated = analysisTerms.length > analyzedTerms.length ||
-            analyzedTerms.some((term) => boundedQueryTerm(term).truncated);
+        const queryMetadataTruncated = analysisTerms.length > analyzedTerms.length || analyzedTerms.some((term) => boundedQueryTerm(term).truncated);
         const collectMatches = (mode) => {
             const collected = [];
             let orderBase = 0;
@@ -419,15 +637,43 @@ export class CatalogService {
                     throw new Error("Catalog result has no corresponding connector");
                 }
                 if (Result.isSuccess(catalog)) {
-                    for (const ranked of rankTools(catalog.success, retrievalQuery, mode, statistics, query)) {
+                    const connectorRank = args.connector ? 0 : connectorMatchRank(query, connector);
+                    const exactConnector = connectorRank > 0;
+                    const connectorTerms = new Set([
+                        ...connectorNames(connector).flatMap(lexicalQueryTerms),
+                        ...(namedService && connectorNames(connector).some((name) => containsPhrase(name, namedService))
+                            ? lexicalQueryTerms(namedService)
+                            : []),
+                    ]);
+                    const localStatistics = exactConnector
+                        ? lexicalCorpusStatistics([catalog.success], retrievalQuery)
+                        : undefined;
+                    // An exact identity is a browse even when one tool repeats that
+                    // identity in its name or description. Action queries still keep
+                    // identity terms that also name an actual capability.
+                    const identityBrowse = connectorNames(connector).some((name) => normalizedPhrase(query) === normalizedPhrase(name));
+                    const toolQuery = identityBrowse
+                        ? ""
+                        : exactConnector
+                            ? queryTerms
+                                .filter((term) => !connectorTerms.has(term) ||
+                                (localStatistics?.nameMatches.get(term)?.size ?? 0) > 0 ||
+                                (localStatistics?.descriptionMatches.get(term)?.size ?? 0) > 0)
+                                .join(" ")
+                            : retrievalQuery;
+                    const toolTermCount = lexicalQueryTerms(toolQuery).length;
+                    for (const ranked of rankTools(catalog.success, toolQuery, mode, statistics, query)) {
                         collected.push({
                             connector,
                             tool: ranked.tool,
                             score: ranked.score,
                             order: orderBase + ranked.order,
                             exactName: ranked.exactName,
+                            exactLookup: rawPhrase === lexicalQueryTerms(ranked.tool.name).join(" ") ||
+                                rawPhrase === lexicalQueryTerms(`${connector.id}.${ranked.tool.name}`).join(" "),
+                            connectorRank,
                             matchedTermCount: ranked.matchedTermCount,
-                            complete: isBrowse || ranked.matchedTermCount === queryTermCount,
+                            complete: isBrowse || ranked.matchedTermCount === toolTermCount,
                         });
                     }
                 }
@@ -438,34 +684,33 @@ export class CatalogService {
         // A non-empty query that normalizes to no lexical terms is not a browse.
         // Ranking an empty phrase would otherwise return every tool as an
         // unrelated zero-score match, with no coverage to explain the result.
-        const rankedMatches = unsearchableQuery
-            ? []
-            : collectMatches(isBrowse ? "all" : "partial");
+        const rankedMatches = unsearchableQuery ? [] : collectMatches(isBrowse ? "all" : "partial");
         const completeMatchCount = rankedMatches.filter((match) => match.complete).length;
         matches.push(...rankedMatches.filter((match) => match.complete ||
             completeMatchCount === 0 ||
             match.exactName ||
+            match.connectorRank > 0 ||
             match.matchedTermCount >= 2));
         if (!isBrowse && !unsearchableQuery && completeMatchCount === 0) {
             matchMode = "partial";
         }
-        // Complete matches and exact tool-name phrases share the first rank tier.
-        // This lets a strong action/object name beat a weak description-only
-        // decoy. Other partial matches fill the remaining page only after every
-        // complete match, regardless of a rare-term score spike.
+        // 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.
         matches.sort((a, b) => {
             const aFirstTier = a.complete || a.exactName;
             const bFirstTier = b.complete || b.exactName;
-            return (Number(bFirstTier) - Number(aFirstTier) ||
+            return (Number(b.exactLookup) - Number(a.exactLookup) ||
+                Number(b.exactName) - Number(a.exactName) ||
+                b.connectorRank - a.connectorRank ||
+                Number(bFirstTier) - Number(aFirstTier) ||
                 b.score - a.score ||
                 a.order - b.order);
         });
         const pageMatches = matches.slice(offset, offset + limit);
         const withSchemas = args.includeSchemas;
         const entries = pageMatches.map((match) => {
-            const output = withSchemas
-                ? this.outputSchema(match.connector.id, match.tool)
-                : {};
+            const output = withSchemas ? this.outputSchema(match.connector.id, match.tool) : {};
             const input = match.tool.inputSchema ?? { type: "object" };
             const signature = withSchemas === "typescript"
                 ? typescriptSignature(input, output.schema, {
@@ -484,9 +729,7 @@ export class CatalogService {
                 : schemaFormat && output.schema
                     ? renderSearchSchema(output.schema, schemaFormat)
                     : undefined;
-            const schemaKeys = withSchemas && args.includeSchemaKeys
-                ? schemaKeyMetadata(input, output.schema)
-                : undefined;
+            const schemaKeys = withSchemas && args.includeSchemaKeys ? schemaKeyMetadata(input, output.schema) : undefined;
             const description = summarizeDiscoveryDescription(match.tool.description, args.fullDescriptions === true);
             const requiredReasons = guideRequiredReasons(match.connector, match.tool, renderedInput?.truncated === true || renderedOutput?.truncated === true);
             const guideSummary = connectorGuideSummary(match.connector);
@@ -507,42 +750,25 @@ export class CatalogService {
                             inputSchema: renderedInput?.schema,
                         }
                         : {}),
+                    ...(withSchemas ? { schemaFormat: withSchemas === "json" ? "json" : "text" } : {}),
                     ...(signature ? { signature: signature.text } : {}),
-                    ...(renderedInput?.truncated
-                        ? { inputSchemaTruncated: true }
-                        : {}),
+                    ...(renderedInput?.truncated ? { inputSchemaTruncated: true } : {}),
                     ...(schemaFormat && output.schema
                         ? {
                             outputSchema: renderedOutput?.schema,
                         }
                         : {}),
-                    ...(withSchemas && output.source
-                        ? { outputSchemaSource: output.source }
-                        : {}),
-                    ...(renderedOutput?.truncated
-                        ? { outputSchemaTruncated: true }
-                        : {}),
+                    ...(withSchemas && output.source ? { outputSchemaSource: output.source } : {}),
+                    ...(renderedOutput?.truncated ? { outputSchemaTruncated: true } : {}),
                     ...(schemaKeys && !renderedInput?.truncated
                         ? {
-                            ...(schemaKeys.inputKeys
-                                ? { inputKeys: schemaKeys.inputKeys }
-                                : {}),
-                            ...(schemaKeys.requiredInputKeys
-                                ? { requiredInputKeys: schemaKeys.requiredInputKeys }
-                                : {}),
+                            ...(schemaKeys.inputKeys ? { inputKeys: schemaKeys.inputKeys } : {}),
+                            ...(schemaKeys.requiredInputKeys ? { requiredInputKeys: schemaKeys.requiredInputKeys } : {}),
                         }
                         : {}),
-                    ...(schemaKeys?.outputKeys && !renderedOutput?.truncated
-                        ? { outputKeys: schemaKeys.outputKeys }
-                        : {}),
-                    ...(match.tool.annotations
-                        ? { annotations: match.tool.annotations }
-                        : {}),
-                    // Config lets a program call this write without asking (#566).
-                    // A marker, not a class: the tool stays approval-required.
-                    ...(isApprovalExempt(this.approval, match.connector, match.tool.name, match.tool)
-                        ? { approval: "exempt" }
-                        : {}),
+                    ...(schemaKeys?.outputKeys && !renderedOutput?.truncated ? { outputKeys: schemaKeys.outputKeys } : {}),
+                    ...(match.tool.annotations ? { annotations: match.tool.annotations } : {}),
+                    classification: match.tool.classification,
                     ...(requiredReasons
                         ? {
                             guideRequired: true,
@@ -552,14 +778,9 @@ export class CatalogService {
                 },
             };
         });
-        const nextOffset = offset + entries.length < matches.length
-            ? offset + entries.length
-            : undefined;
+        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([
-            ...(statistics.nameMatches.get(term) ?? []),
-            ...(statistics.descriptionMatches.get(term) ?? []),
-        ]);
+        const matchingTools = (term) => new Set([...(statistics.nameMatches.get(term) ?? []), ...(statistics.descriptionMatches.get(term) ?? [])]);
         const representedTerms = [];
         const otherResultTerms = [];
         const unmatchedTerms = [];
@@ -576,32 +797,27 @@ export class CatalogService {
             }
         }
         const unavailableCatalogs = catalogs.filter(Result.isFailure).length;
-        // Named field by field rather than spread: `CallErrorDetails` also carries
-        // connector, operation, recovery, and nextAction, and a discovery read is
-        // not a call — widening the classifier must not silently widen what a
-        // catalog search hands back.
-        const scopedCatalogError = (() => {
-            const scopedCatalog = catalogs[0];
-            if (!scopedConnector ||
-                !scopedCatalog ||
-                Result.isSuccess(scopedCatalog)) {
-                return undefined;
-            }
-            const error = classifyCallError(scopedCatalog.failure, "catalog_lookup_failed");
-            return {
-                code: error.code,
-                message: boundedEchoText(error.message),
-                retryable: error.retryable,
-                ...(error.retryAfterMs === undefined
-                    ? {}
-                    : { retryAfterMs: error.retryAfterMs }),
-            };
-        })();
-        const safetyLabel = safety === "readOnly"
-            ? "read-only "
-            : safety === "approvalRequired"
-                ? "approval-required "
-                : "";
+        const catalogErrors = (await Promise.all(catalogs.map(async (catalog, index) => {
+            if (Result.isSuccess(catalog))
+                return [];
+            return [await this.catalogFailure(connectors[index], catalog.failure)];
+        }))).flat();
+        const needsAuth = (error) => error.code === "auth_required" ||
+            error.code === "downstream_oauth_required" ||
+            error.code === "provider_permission_denied";
+        catalogErrors.sort((a, b) => Number(needsAuth(b)) - Number(needsAuth(a)));
+        const scopedFailure = args.connector ? catalogErrors[0] : undefined;
+        const scopedCatalogError = scopedFailure
+            ? scopedFailure.code === "auth_required" || scopedFailure.code === "downstream_oauth_required"
+                ? scopedFailure
+                : {
+                    code: scopedFailure.code,
+                    message: scopedFailure.message,
+                    retryable: scopedFailure.retryable,
+                    ...(scopedFailure.retryAfterMs === undefined ? {} : { retryAfterMs: scopedFailure.retryAfterMs }),
+                }
+            : undefined;
+        const safetyLabel = safety === "readOnly" ? "read-only " : safety === "approvalRequired" ? "approval-required " : "";
         const filterRecovery = safety === "all" ? "" : " Change safety to inspect the other tools.";
         const scopedGuide = matches.length === 0 && scopedConnector && connectorGuide(scopedConnector)
             ? {
@@ -610,15 +826,9 @@ 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.
+        // Partial identity words can still explain a miss. Exact identities are
+        // already ranking inputs above; this guidance handles a title word such
+        // as "warehouse" when the full title is "Warehouse stock".
         const identityConnectorIds = matches.length === 0 && !isBrowse && !unsearchableQuery && !scopedConnector
             ? connectors
                 // The full query, not `analyzedTerms`: that cap exists to bound
@@ -626,8 +836,7 @@ export class CatalogService {
                 // 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))))
+                (connector.title !== undefined && matchesLexicalTerm(connector.title, term))))
                 .map((connector) => connector.id)
             : [];
         const namedIdentityConnectors = identityConnectorIds
@@ -637,17 +846,16 @@ export class CatalogService {
         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}`;
+            : `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
-        // 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.
+        // no catalog failed and the unavailable path below never fires. Name
+        // only configured connectors in the current identity/pool registry view.
         const unknownConnectorGuidance = args.connector && !scopedConnector
-            ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
+            ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools. Configured connectors for this endpoint: ${this.registry
+                .listConnectors()
+                .map((connector) => connector.id)
+                .join(", ") || "none"}.`
             : undefined;
         // Searchable queries report analysis when the scorer had to degrade. A
         // non-empty query with no searchable terms reports the bounded raw input
@@ -655,13 +863,16 @@ export class CatalogService {
         // no terms to analyse and normally reports none at all. Scope failures are
         // the exception, because an empty result alone looks like a connector that
         // correctly exposes no tools.
-        const reportsQueryAnalysis = unsearchableQuery ||
+        const reportsQueryAnalysis = absence !== undefined ||
+            unsearchableQuery ||
             (queryTerms.length > 0
                 ? matchMode === "partial"
                 : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0);
         const searchGuidance = () => {
             if (unknownConnectorGuidance)
                 return unknownConnectorGuidance;
+            if (absence)
+                return absence.message;
             if (unsearchableQuery) {
                 return scopedConnector && unavailableCatalogs > 0
                     ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
@@ -672,7 +883,7 @@ export class CatalogService {
                     return undefined;
                 return 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.`;
+                    : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Inspect catalogErrors for the typed reasons and recovery actions.`;
             }
             if (matches.length === 0) {
                 if (scopedConnector) {
@@ -700,44 +911,39 @@ export class CatalogService {
         };
         const guidance = searchGuidance();
         return {
+            catalogErrors,
+            ...(absence ? { absence } : {}),
             entries,
             total: matches.length,
             offset,
             limit,
             hasMore: nextOffset !== undefined,
             ...(nextOffset !== undefined ? { nextOffset } : {}),
-            ...(matchMode === "partial" && matches.length > 0
-                ? { matchMode }
-                : {}),
+            ...(matchMode === "partial" && matches.length > 0 ? { matchMode } : {}),
             ...(reportsQueryAnalysis
                 ? {
                     queryAnalysis: {
                         representedTerms,
                         otherResultTerms,
                         unmatchedTerms,
-                        ...(queryMetadataTruncated
-                            ? { truncated: true }
-                            : {}),
+                        ...(queryMetadataTruncated ? { truncated: true } : {}),
                         ...(args.connector ? { connectorScope: args.connector } : {}),
                         ...(args.connector && !scopedConnector
-                            ? { unknownConnector: true }
-                            : {}),
-                        ...(unavailableCatalogs > 0
-                            ? { unavailableConnectorCount: unavailableCatalogs }
+                            ? {
+                                unknownConnector: true,
+                                configuredConnectors: this.registry.listConnectors().map((connector) => connector.id),
+                            }
                             : {}),
+                        ...(unavailableCatalogs > 0 ? { unavailableConnectorCount: unavailableCatalogs } : {}),
                         ...(scopedCatalogError ? { catalogError: scopedCatalogError } : {}),
                         ...(scopedGuide
                             ? {
                                 guide: scopedGuide.guide,
-                                ...(scopedGuide.guideSummary
-                                    ? { guideSummary: scopedGuide.guideSummary }
-                                    : {}),
+                                ...(scopedGuide.guideSummary ? { guideSummary: scopedGuide.guideSummary } : {}),
                                 ...(scopedGuide.required
                                     ? {
                                         guideRequired: true,
-                                        guideRequiredReasons: [
-                                            "connector_required",
-                                        ],
+                                        guideRequiredReasons: ["connector_required"],
                                     }
                                     : {}),
                             }
@@ -756,12 +962,21 @@ export class CatalogService {
             return { address, resolved: this.registry.resolveAddress(address) };
         });
         const connectorIds = [
-            ...new Set(resolved
-                .map((entry) => entry.resolved?.connector.id)
-                .filter((id) => Boolean(id))),
+            ...new Set(resolved.map((entry) => entry.resolved?.connector.id).filter((id) => Boolean(id))),
         ];
         const loaded = await runEdge(this.discoveryCatalogs(connectorIds, "connecta.describe"));
         const catalogs = new Map(connectorIds.map((id, index) => [id, loaded[index]]));
+        const authFailures = new Map(await Promise.all(connectorIds.map(async (id) => {
+            const catalog = catalogs.get(id);
+            if (!catalog || !Result.isFailure(catalog))
+                return [id, undefined];
+            const classified = classifyCallError(catalog.failure, "catalog_lookup_failed");
+            const connector = this.registry.getConnector(id);
+            const error = classified.code === "auth_required" || classified.code === "downstream_oauth_required"
+                ? await this.catalogFailure(connector, catalog.failure)
+                : undefined;
+            return [id, error];
+        })));
         return resolved.map(({ address, resolved: addressResolution }) => {
             if (!addressResolution) {
                 const message = `Unknown address "${boundedEchoText(address)}"`;
@@ -770,12 +985,16 @@ export class CatalogService {
                     error: message,
                     errorDetails: {
                         ...framingError("unknown_address", message),
+                        configuredConnectors: this.registry.listConnectors().map((connector) => connector.id),
                         nextAction: this.searchRecovery({ query: recoveryQuery(address) }, "Find the configured canonical address before retrying."),
                     },
                 };
             }
             const catalog = catalogs.get(addressResolution.connector.id);
             if (catalog && Result.isFailure(catalog)) {
+                const authFailure = authFailures.get(addressResolution.connector.id);
+                if (authFailure)
+                    return { address: boundedEchoText(address), error: authFailure.message, errorDetails: authFailure };
                 const classified = classifyCallError(catalog.failure, "catalog_lookup_failed");
                 const message = boundedEchoText(classified.message);
                 return {
@@ -785,9 +1004,7 @@ export class CatalogService {
                         code: classified.code,
                         message,
                         retryable: classified.retryable,
-                        ...(classified.retryAfterMs === undefined
-                            ? {}
-                            : { retryAfterMs: classified.retryAfterMs }),
+                        ...(classified.retryAfterMs === undefined ? {} : { retryAfterMs: classified.retryAfterMs }),
                     },
                 };
             }
@@ -818,16 +1035,15 @@ export class CatalogService {
                     description: true,
                 })
                 : undefined;
-            const compactInput = format === "compact"
-                ? compactDescriptionSchema(input) : undefined;
-            const compactOutput = format === "compact" && output.schema
-                ? compactDescriptionSchema(output.schema) : undefined;
+            const compactInput = format === "compact" ? compactDescriptionSchema(input) : undefined;
+            const compactOutput = format === "compact" && output.schema ? compactDescriptionSchema(output.schema) : undefined;
             const inputTruncated = compactInput?.truncated === true || signature?.inputTruncated === true;
             const outputTruncated = compactOutput?.truncated === true || signature?.outputTruncated === true;
             const requiredReasons = guideRequiredReasons(addressResolution.connector, tool, inputTruncated || outputTruncated);
             const guideSummary = connectorGuideSummary(addressResolution.connector);
             return {
                 address,
+                schemaFormat: format === "json" ? "json" : "text",
                 name: tool.name,
                 ...(description !== undefined ? { description } : {}),
                 ...(connectorGuide(addressResolution.connector)
@@ -842,9 +1058,7 @@ export class CatalogService {
                         guideRequiredReasons: requiredReasons,
                     }
                     : {}),
-                ...(signature
-                    ? { signature: signature.text }
-                    : { inputSchema: compactInput?.text ?? input }),
+                ...(signature ? { signature: signature.text } : { inputSchema: compactInput?.text ?? input }),
                 ...(inputTruncated ? { inputSchemaTruncated: true } : {}),
                 ...(outputTruncated ? { outputSchemaTruncated: true } : {}),
                 ...(output.schema && !signature
@@ -854,9 +1068,7 @@ export class CatalogService {
                     : {}),
                 ...(output.source ? { outputSchemaSource: output.source } : {}),
                 ...(tool.annotations ? { annotations: tool.annotations } : {}),
-                ...(isApprovalExempt(this.approval, addressResolution.connector, tool.name, tool)
-                    ? { approval: "exempt" }
-                    : {}),
+                classification: tool.classification,
             };
         });
     }
@@ -872,45 +1084,17 @@ function pageTail(page) {
         ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
     };
 }
-export function groupedSearchResult(page) {
-    const groups = [];
-    const byConnector = new Map();
-    for (const entry of page.entries) {
-        const existing = byConnector.get(entry.connector.id);
-        if (existing) {
-            existing.tools.push(entry.tool);
-        }
-        else {
-            const group = {
-                id: entry.connector.id,
-                ...(entry.connector.title ? { title: entry.connector.title } : {}),
-                ...(entry.guide ? { guide: entry.guide } : {}),
-                ...(entry.guideSummary
-                    ? { guideSummary: entry.guideSummary }
-                    : {}),
-                tools: [],
-            };
-            byConnector.set(entry.connector.id, group);
-            groups.push(group);
-            group.tools.push(entry.tool);
-        }
-    }
-    return {
-        connectors: groups,
-        ...pageTail(page),
-    };
-}
 export function flatSearchResult(page) {
     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 }
-                : {}),
+            ...(entry.guideSummary ? { guideSummary: entry.guideSummary } : {}),
         })),
         ...pageTail(page),
     };