@zackbart/connecta 0.38.0 → 0.39.0

package/dist/invocation.js

@@ -1,3 +1,4 @@
+import { routePhrases } from "./agent-routes.js";
 import { authCall, registerAuthMethod } from "./auth/native.js";
 import { withAuthorizationHandoffEffect } from "./authorization-handoff.js";
 import { hasControlCharacters } from "./tool-name.js";
@@ -9,7 +10,7 @@ import { downstreamValue } from "./mcp-result.js";
 import { carryFailureFacts, classifiedFailure, failureRecord, logFailure, recordedToolName, } from "./operator-record.js";
 import { splitAddress } from "./registry.js";
 import { causeError, runEdge, withDeadlineEffect } from "./runtime/run.js";
-import { validateCatalogToolInput } from "./validate.js";
+import { schemaExample, validateCatalogToolInput } from "./validate.js";
 import { sentSecretsFor, sentSecretsForRequest } from "./sent-secrets.js";
 import { recoveryRecord, recordRecoveryFacts } from "./call-recovery.js";
 import { callFromContext, contextView, viewServices, Credentials } from "./runtime/call.js";
@@ -141,6 +142,7 @@ export class InvocationFailure extends Error {
     }
 }
 keepErrorName(InvocationFailure, "InvocationFailure");
+const withoutExample = ({ example: _example, ...stated }) => stated;
 /**
  * Shared downstream invocation engine. Address/catalog resolution is delegated
  * to the request-local CatalogService; every remaining call semantic lives
@@ -406,6 +408,14 @@ export class InvocationService {
                             return error;
                         return {
                             ...error,
+                            // An example comes only from the published schema, never a connector's copy of the
+                            // call, unless the connector states why there is none.
+                            validation: {
+                                ...withoutExample(error.validation),
+                                ...(error.validation.exampleUnavailable === undefined && resolved?.definition.inputSchema
+                                    ? schemaExample(resolved.definition.inputSchema)
+                                    : {}),
+                            },
                             connector: target.connector.id,
                             operation: `${target.connector.id}.${target.toolName}`,
                             nextAction: this.catalog.searchRecovery({
@@ -552,7 +562,7 @@ export class InvocationService {
                     return framingError("read_only_endpoint", `Tool "${canonicalAddress}" is a write, and ${connectorReadOnly ? `connector "${target.connector.id}"` : "this endpoint"} is read-only. Nothing here can send it.`);
                 }
                 if (refusal === "destructive_tool_requires_approval") {
-                    return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is a write. Invoke it through call_destructive_tool so the MCP host can request approval.`);
+                    return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is a write. ${routePhrases(context).writeNeedsApproval}`);
                 }
                 // Remote MCP tools advertise their input schema in the catalog. Validate
                 // against that same request-local definition before admission or provider
@@ -580,7 +590,12 @@ export class InvocationService {
                     return yield* Effect.fail(callSignal.reason);
                 attempts = 1;
                 const call = (permit) => Effect.gen({ self: this }, function* () {
-                    const operationContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs, defer: this.catalog.defer }));
+                    const operationContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({
+                        signal: callSignal,
+                        timeoutMs: context.timeoutMs,
+                        defer: this.catalog.defer,
+                        routes: context.routes,
+                    }));
                     const lease = callFromContext(operationContext, write ? "write" : "read", {
                         admitted: true,
                         // An invocation deadline aborts when its call finishes. A
@@ -604,11 +619,11 @@ export class InvocationService {
                     yield* Effect.gen(function* () {
                         if (target.connector.credential) {
                             if (!connectorContext.credential) {
-                                throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. Call " +
-                                    `authorize_connector({ connector: "${target.connector.id}" }).`);
+                                throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. " +
+                                    routePhrases(connectorContext).authorizeCall(target.connector.id));
                             }
                             if (!(yield* Context.get(lease.services, Credentials).values)) {
-                                throw new ConnectorCallError("auth_required", `Connector "${target.connector.id}" has no stored credential. Call authorize_connector.`);
+                                throw new ConnectorCallError("auth_required", `Connector "${target.connector.id}" has no stored credential. ${routePhrases(connectorContext).authorizeCall()}`);
                             }
                         }
                         yield* resolveInvocationAuthEffect(connector, callTool, connectorContext);

package/dist/membership.d.ts

@@ -22,6 +22,7 @@ export interface ResolvedPool {
     readOnly: boolean;
     /** Exactly the pool's `tools`; nothing intersects or widens it. */
     access: ConnectorAccess;
+    /** Non-empty and homogeneous: all people or all agents. */
     members: readonly Member[];
     /** Trimmed `owner`: the Workspace address agents in this pool act as. */
     owner?: string;
@@ -40,11 +41,8 @@ export interface MemberContext {
 }
 /** The namespaces bare ids may resolve in, read from the resolved providers. */
 export declare function memberContext(auth: readonly InboundAuth[], agents: readonly string[]): MemberContext;
-/**
- * Resolve one list of references, throwing on any that is malformed,
- * ambiguous, unknown, or repeated (INV-11).
- */
-export declare function resolveMembers(value: unknown, path: string, context: MemberContext): Member[];
+/** Resolve a pool's members, which are all people or all agents (INV-11). */
+export declare function resolvePoolMembers(value: unknown, path: string, context: MemberContext): Member[];
 /**
  * `maintainers`: people only. Required whenever an inbound provider can admit
  * a person, which is any provider but the built-in agent-token adapter. With
@@ -53,5 +51,15 @@ export declare function resolveMembers(value: unknown, path: string, context: Me
 export declare function resolveMaintainers(value: unknown, admitsPeople: boolean, context: MemberContext): readonly IdentityReference[];
 /** Whether an admitted identity is this member. An agent never matches a person. */
 export declare function isMember(member: Member, identity: Readonly<AuthenticatedIdentity>): boolean;
+/**
+ * Non-maintainer people listed in several pools, in declaration order. Plain
+ * `/mcp` routes a person by their single pool, so it refuses each of these.
+ * An open deployment admits no people, so it has none.
+ */
+export declare function peopleInSeveralPools(pools: ReadonlyMap<string, ResolvedPool>, maintainers: readonly IdentityReference[]): Array<{
+    namespace: string;
+    id: string;
+    pools: string[];
+}>;
 /** Whether an admitted identity is a listed maintainer. */
 export declare function isMaintainer(maintainers: readonly IdentityReference[], identity: Readonly<AuthenticatedIdentity>): boolean;

package/dist/membership.js

@@ -65,7 +65,7 @@ const memberKey = (member) => member.kind === "agent" ? `agent\0${member.name}`
  * Resolve one list of references, throwing on any that is malformed,
  * ambiguous, unknown, or repeated (INV-11).
  */
-export function resolveMembers(value, path, context) {
+function resolveMembers(value, path, context) {
     if (!Array.isArray(value)) {
         throw new ConfigError(`${path} must be an array of principal ids, { namespace, id }, or "agent:<name>".`);
     }
@@ -79,6 +79,14 @@ export function resolveMembers(value, path, context) {
         return Object.freeze(member);
     });
 }
+/** Resolve a pool's members, which are all people or all agents (INV-11). */
+export function resolvePoolMembers(value, path, context) {
+    const members = resolveMembers(value, path, context);
+    if (!members.every((member) => member.kind === members[0].kind)) {
+        throw new ConfigError(`${path} mixes people and agents; list only one kind.`);
+    }
+    return members;
+}
 /**
  * `maintainers`: people only. Required whenever an inbound provider can admit
  * a person, which is any provider but the built-in agent-token adapter. With
@@ -88,7 +96,7 @@ export function resolveMaintainers(value, admitsPeople, context) {
     const path = "ConnectaConfig.maintainers";
     if (value === undefined || (Array.isArray(value) && value.length === 0)) {
         if (admitsPeople) {
-            throw new ConfigError(`${path} is required with inbound auth: list the people who may use plain /mcp, administer shared ` +
+            throw new ConfigError(`${path} is required with inbound auth: list the people who receive the whole catalog at plain /mcp, administer shared ` +
                 "credentials, manage agent tokens, and read activity.");
         }
         return Object.freeze([]);
@@ -115,6 +123,30 @@ export function isMember(member, identity) {
         principal.namespace === member.namespace &&
         principal.id === member.id);
 }
+/**
+ * Non-maintainer people listed in several pools, in declaration order. Plain
+ * `/mcp` routes a person by their single pool, so it refuses each of these.
+ * An open deployment admits no people, so it has none.
+ */
+export function peopleInSeveralPools(pools, maintainers) {
+    if (maintainers.length === 0)
+        return [];
+    const people = new Map();
+    for (const [name, pool] of pools) {
+        for (const member of pool.members) {
+            if (member.kind !== "human")
+                continue;
+            if (maintainers.some((m) => m.namespace === member.namespace && m.id === member.id))
+                continue;
+            const key = JSON.stringify([member.namespace, member.id]);
+            const person = people.get(key) ?? { namespace: member.namespace, id: member.id, pools: [] };
+            if (!person.pools.includes(name))
+                person.pools.push(name);
+            people.set(key, person);
+        }
+    }
+    return [...people.values()].filter((person) => person.pools.length > 1);
+}
 /** Whether an admitted identity is a listed maintainer. */
 export function isMaintainer(maintainers, identity) {
     return maintainers.some((maintainer) => isMember({ kind: "human", ...maintainer }, identity));

package/dist/meta-tools.js

@@ -1,3 +1,4 @@
+import { META_ROUTES } from "./agent-routes.js";
 import { toolError } from "./tool-error.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, authMethod, authStorage, registerAuth } from "./auth/native.js";
@@ -178,7 +179,7 @@ function isWellFormedText(text) {
  * reported the decoy near the top instead. A write never gets this: repeating
  * it is the one thing its notice forbids.
  */
-const READ_REDUCE_FIRST = "To find something specific, repeat this read inside execute_code with connecta.call and filter or search the result there, returning only what matters";
+const readReduceFirst = (routes) => `To find something specific, repeat this read inside ${routes.program} with connecta.call and filter or search the result there, returning only what matters`;
 function pagingHint(results, totalBytes, preview) {
     if (results.pagingTool === "read_result") {
         const shown = preview.kind === "prefix"
@@ -190,13 +191,13 @@ function pagingHint(results, totalBytes, preview) {
     }
     if (!results.write) {
         if (results.binding.program)
-            return "filter/map/slice data inside execute_code and return only what you need; page this completed return with connecta.result using nextAction.";
+            return `filter/map/slice data inside ${results.routes.program} and return only what you need; page this completed return with connecta.result using nextAction.`;
         const [shown, full] = preview.kind === "prefix"
             ? [`Bytes 0-${preview.bytes} of ${totalBytes} follow.`, "to read it in full, page the rest"]
             : preview.kind === "text-of-envelope"
                 ? ["Its text follows.", `to read the full ${totalBytes}-byte content array as JSON, page it`]
                 : [`The result is ${totalBytes} bytes.`, "to read it in full, page it"];
-        return `${shown} ${READ_REDUCE_FIRST}; ${full} with connecta.result using nextAction.`;
+        return `${shown} ${readReduceFirst(results.routes)}; ${full} with connecta.result using nextAction.`;
     }
     const body = preview.kind === "prefix"
         ? `Bytes 0-${preview.bytes} of ${totalBytes} follow; page the rest with connecta.result using nextAction.`
@@ -263,7 +264,7 @@ const stashResult = function (bytes, results, preview, rawText) {
                     ? `Paging is unavailable. ${WRITE_ALREADY_RAN}`
                     : results.pagingTool
                         ? "Paging is unavailable."
-                        : "Paging is unavailable. Use execute_code to reduce read-only results before returning them.",
+                        : `Paging is unavailable. Use ${results.routes.program} to reduce read-only results before returning them.`,
             };
         }
         return {
@@ -302,6 +303,8 @@ const pageProgramResultNative = /* @__PURE__ */ registerAuth(pageProgramResult,
         const bytes = enc.encode(text);
         const write = resolved.definition.classification !== "read";
         const notice = yield* upwardStep(stashResult(bytes, {
+            // Program-call pages name only execute_code, listed wherever programs run.
+            routes: META_ROUTES,
             binding: {
                 identity: registry.resultIdentity(),
                 baseUrl,
@@ -341,6 +344,8 @@ const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn
         const cap = Math.min(registry.maxResultBytes, ...dependencies.map((dependency) => resolveMaxResultBytes(registry.getConnector(dependency.connector)?.maxResultBytes, registry.maxResultBytes)));
         const results = {
             secrets,
+            // A program return names only execute_code, which every surface running programs lists.
+            routes: META_ROUTES,
             binding: {
                 identity: registry.resultIdentity(),
                 baseUrl,
@@ -541,12 +546,13 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     // identity lets remote connectors reuse one downstream client inside that
     // request without leaking request-bound I/O into the next one.
     const requestScope = opts.requestScope ?? {};
+    const routes = opts.routes ?? META_ROUTES;
     if (opts.canManageAuth || opts.oauthConnectUrl || opts.credentialHandoffUrl || opts.oauthConnectUnavailable) {
         bindAuthorizationHandoffs(requestScope, authMethod((connector) => authCall(authorizationHandoff, [
             registry,
             baseUrl,
             requestScope,
-            opts,
+            { ...opts, routes },
             { connector },
         ])));
     }
@@ -567,6 +573,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
         requestSignal: opts.requestSignal,
         // searchRoute keeps its top-level default. In-program callers use a
         // separate CatalogService configured for connecta.search.
+        routes,
     });
     const invocation = new InvocationService(registry, catalog, opts.activity);
     /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
@@ -584,6 +591,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     activitySource: opts.activitySource,
                     sentSecrets,
                     readOnly: opts.readOnly,
+                    routes,
                     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                     ...(opts.requestSignal !== undefined ? { requestSignal: opts.requestSignal } : {}),
                     unwrapResult: call.resultMode === "value",
@@ -612,6 +620,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                         const cap = resolveMaxResultBytes(resolved.connector.maxResultBytes, globalCap);
                         const results = {
                             secrets,
+                            routes,
                             binding: {
                                 identity: registry.resultIdentity(),
                                 baseUrl,
@@ -836,6 +845,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 binding.identity.subject !== identity.subject ||
                 binding.identity.principal !== identity.principal ||
                 binding.identity.endpoint !== identity.endpoint ||
+                binding.identity.pool !== identity.pool ||
                 binding.identity.origin !== identity.origin ||
                 (binding.program === undefined
                     ? typeof binding.connector !== "string" || typeof binding.tool !== "string"
@@ -990,11 +1000,15 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
         })),
     };
 }
-const SEARCH_DESC = (readOnly) => `${readOnly ? "Use top-level search for catalog inspection; this read-only endpoint omits write tools." : "Use top-level search for catalog inspection or write work before call_destructive_tool."} Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" selects reads; "approvalRequired" selects the fail-closed write complement. The host owns confirmation; these filters grant no authority. Empty query browses. Returns { catalogErrors, tools, total, offset, limit, hasMore }; read catalogErrors and absence before selecting a tool. Compact schemas have schemaFormat="text".`;
-const CALL_DESC = (readOnly) => `Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. ${readOnly ? "This endpoint is read-only and refuses every write." : "Unannotated or write-capable tools fail closed to call_destructive_tool."} A truncated result carries a connecta.result action.`;
+// Each description states only its own tool's scope; the full routing rule
+// lives once in the server instructions. A client that drops instructions
+// still routes correctly from these scopes plus execute_code's terse lead.
+// Only the meta surface lists these tools, so they use its names.
+const SEARCH_DESC = (readOnly) => `${readOnly ? "Catalog inspection; this read-only endpoint omits write tools." : `Catalog inspection, or finding a write before ${META_ROUTES.write}.`} For read work, search inside one ${META_ROUTES.program} program that also calls and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" selects reads; "approvalRequired" selects the fail-closed write complement; neither grants authority. Empty query browses. Read catalogErrors and absence before selecting a tool. Compact schemas have schemaFormat="text".`;
+const CALL_DESC = (readOnly) => `Call one known-address read: a tool explicitly annotated readOnlyHint: true. Other read work: ${META_ROUTES.program}. ${readOnly ? "This endpoint is read-only and refuses every write." : `Unannotated or write-capable tools fail closed to ${META_ROUTES.write}.`} A truncated result carries a connecta.result action.`;
 const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHint: true. Include a short reason for the human reviewer after checking the schema and consequences. The reason grants no authority and is not sent downstream.";
 /** A read-only endpoint keeps the six-tool surface, so this tool says why it never writes here. */
-const CALL_DESTRUCTIVE_READ_ONLY_DESC = "This endpoint is read-only: search and describe omit write tools, and every write call here is refused. Reads still run; prefer call_tool or execute_code for them.";
+const CALL_DESTRUCTIVE_READ_ONLY_DESC = `This endpoint is read-only: search and describe omit write tools, and every write call here is refused. Reads still run; prefer ${META_ROUTES.read} or ${META_ROUTES.program} for them.`;
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or required deployment configuration. A configured credential reports presence only: if a call just failed with an authentication or operator-configuration error, give the retained handoff to the operator; otherwise proceed with the call. force=true requests an OAuth restart when the verified user opens the /connect URL; this tool never accepts credentials.";
 const SKILLS_DESC = "List or fetch on-demand guidance. Fetch usage only when the always-loaded instructions are insufficient or a program needs repair.";
 /**
@@ -1084,6 +1098,7 @@ const AUTHORIZE_INPUT = advertisedSchema(z.object({
 export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
         maxProgramResultChars: ctx.maxProgramResultChars,
+        routes: ctx.routes,
         ...(ctx.native && !ctx.native.executeCode ? { pagingTool: "read_result" } : {}),
         ...(ctx.native ? { activitySource: "native" } : {}),
         downstreamInput: Boolean(ctx.authElicitation),

package/dist/native-recovery.js

@@ -1,5 +1,5 @@
 /** Adapt only Connecta error envelopes; successful downstream payloads stay untouched. */
-export function nativeRecovery(result, executeCode, wireName) {
+export function nativeRecovery(result, wireName) {
     const response = result;
     const body = response?.structuredContent;
     if (!response?.isError || !body || typeof body.error !== "object" || !body.error)
@@ -28,22 +28,10 @@ export function nativeRecovery(result, executeCode, wireName) {
             }
             : { host: "search", purpose: action.purpose };
     }
-    // These are Connecta-authored recovery fields, never arbitrary downstream data.
-    const rewrite = (text) => text.replace(/authorize_connector|search_tools|call_(?:destructive_)?tool|execute_code/g, (tool) => tool === "authorize_connector"
-        ? "the returned authorization handoff"
-        : tool.startsWith("call_")
-            ? "the original native tool"
-            : tool === "execute_code" && executeCode
-                ? tool
-                : "your host's tool search");
-    for (const key of ["message", "instructions", "retry"])
-        if (typeof error[key] === "string")
-            error[key] = rewrite(error[key]);
+    // Recovery text already uses the native wording: native pools build it with
+    // native route names. Only the address in retry text becomes the wire name.
     if (wireName && typeof error.operation === "string" && typeof error.retry === "string")
-        error.retry = error.retry.replaceAll(rewrite(error.operation), wireName);
-    if (!executeCode && typeof error.instructions === "string") {
-        error.instructions = error.instructions.replace(/; connecta\.search[\s\S]*$/, ". Retry the original native call after recovery.");
-    }
+        error.retry = error.retry.replaceAll(error.operation, wireName);
     return {
         ...response,
         structuredContent: { ...body, error },

package/dist/native-tools.js

@@ -1,4 +1,5 @@
 import { bytesToHex } from "./bytes.js";
+import { routeNames } from "./agent-routes.js";
 import { duringViewEffect } from "./runtime/call.js";
 import { RequestScope, requestOwner } from "./runtime/request-scope.js";
 import { Effect } from "effect";
@@ -149,6 +150,8 @@ export class NativeSurface {
             // Listing omits a read-only endpoint's writes, as search does.
             readOnly: options.readOnly,
             defer: options.defer,
+            // Declared schema descriptions read as this pool serves them.
+            routes: routeNames(options.executeCode ? "native-code" : "native"),
         });
     }
     /**
@@ -183,7 +186,7 @@ export class NativeSurface {
             ...(entry ? { _meta: { "dev.connecta/address": `${entry.connector.id}.${entry.tool.name}` } } : {}),
         }, authMethod((args, request) => Effect.gen({ self: this }, function* () {
             const result = yield* authInvoke(this, "call", [name, args ?? {}, request]);
-            return nativeRecovery(result, this.options.executeCode, name);
+            return nativeRecovery(result, name);
         })));
     }
     /**

package/dist/oauth-sealing.js

@@ -46,3 +46,13 @@ export async function deriveRequestStateKey(raw) {
         info: new TextEncoder().encode("auth-elicitation"),
     }, material, 256));
 }
+/** A non-extractable HMAC key for secret-bearing stored cache keys; nothing is stored. */
+export async function deriveStorageDigestKey(raw) {
+    const material = await crypto.subtle.importKey("raw", new Uint8Array(raw), "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new TextEncoder().encode("connecta:storage-digest:v1"),
+        info: new TextEncoder().encode("cache-keys"),
+    }, material, { name: "HMAC", hash: "SHA-256", length: 256 }, false, ["sign"]);
+}

package/dist/operation-vocabulary.js

@@ -1,7 +1,17 @@
 // Private, request-free discovery facts. No provider, schema, handler or I/O dependency.
 import { lexicalSearchContent, lexicalQueryTerms } from "./catalog.js";
+/** Ready calls one vocabulary offers a search: only its top-ranked operation. */
+const MAX_READY_PER_VOCABULARY = 1;
+/**
+ * Normalized action words. A summary may supply these; every other query word
+ * names an object and must match the operation's resource identity.
+ */
+const ACTIONS = new Set(["get", "list", "count", "show", "create", "update", "delete"]);
+/** Path tokens that version an API rather than name a resource. */
+const VERSION = /^v?\d+$/;
 const tools = new WeakMap();
 const connectors = new WeakMap();
+const synonymGroups = new WeakMap();
 const OPERATION_VOCABULARY_BOUNDS = {
     operations: 8192,
     rowChars: 1024,
@@ -28,20 +38,56 @@ const aliases = {
     modify: "update",
     remove: "delete",
 };
-const terms = (text) => [
-    ...new Set(lexicalQueryTerms(lexicalSearchContent(text)).map((word) => aliases[word] ?? token(word))),
-];
+const normal = (word) => aliases[word] ?? token(word);
+const terms = (text) => [...new Set(lexicalQueryTerms(lexicalSearchContent(text)).map(normal))];
+/** Resource words of a path segment or operation id, without version or action words. */
+const identity = (text) => terms(text).filter((word) => !VERSION.test(word) && !ACTIONS.has(word));
+function resourceOf(path, operationId) {
+    const segments = path.slice(0, OPERATION_VOCABULARY_BOUNDS.rowChars).split("/").map(identity);
+    const names = [...segments, identity(operationId.slice(0, OPERATION_VOCABULARY_BOUNDS.rowChars))].filter((name) => name.length > 0);
+    return { names, last: segments.at(-1) ?? [], terms: new Set(names.flat()) };
+}
+/**
+ * Attach a maintained provider's lexical synonym groups to its connector. Each
+ * group's words are interchangeable query terms for that connector's tool
+ * ranking and operation vocabulary; nothing is inferred.
+ */
+export function registerSearchSynonyms(connector, groups) {
+    synonymGroups.set(connector, groups);
+}
+/** A connector's groups, including those a provider stamp inherits. */
+function groupsOf(connector) {
+    let target = connector;
+    while (target && !synonymGroups.has(target))
+        target = Object.getPrototypeOf(target);
+    return target ? synonymGroups.get(target) : undefined;
+}
+/** The other words of every group holding `word`, each word under `normalize`. */
+function synonymsIn(groups, word, normalize = (raw) => raw) {
+    return groups.flatMap((group) => {
+        const words = group.map(normalize);
+        return words.includes(word) ? words.filter((other) => other !== word) : [];
+    });
+}
+/** Word to its declared synonyms for a connector's tool ranking, when its provider declares any. */
+export function searchSynonyms(connector) {
+    const groups = groupsOf(connector);
+    return groups && ((word) => synonymsIn(groups, word));
+}
 /** Register only construction-authored compact summaries; never whole request/response schemas. */
 export function registerOperationVocabulary(tool, rows) {
     let postings;
     const routes = [];
     const cache = new Map();
-    tools.set(tool, (query, visible, safety, readOnly) => {
+    tools.set(tool, (query, visible, safety, readOnly, synonyms) => {
+        const none = { matched: false, ready: [] };
         if (query.length > OPERATION_VOCABULARY_BOUNDS.queryChars)
-            return false;
+            return none;
         const wanted = terms(query);
         if (!wanted.length || wanted.length > OPERATION_VOCABULARY_BOUNDS.terms)
-            return false;
+            return none;
+        // Each wanted word matches through itself or any declared synonym.
+        const alternatives = wanted.map((word) => [word, ...(synonyms ? synonymsIn(synonyms, word, normal) : [])]);
         if (!postings) {
             postings = new Map();
             let chars = 0;
@@ -52,7 +98,19 @@ export function registerOperationVocabulary(tool, rows) {
                     break;
                 chars += text.length;
                 const id = routes.length;
-                routes.push({ route: row.route, write: row.write });
+                routes.push({
+                    route: row.route,
+                    write: row.write,
+                    ...(row.ready
+                        ? {
+                            ready: {
+                                path: row.ready.path,
+                                summary: row.ready.summary.slice(0, OPERATION_VOCABULARY_BOUNDS.rowChars),
+                                ...resourceOf(row.ready.path, row.ready.operationId),
+                            },
+                        }
+                        : {}),
+                });
                 for (const word of terms(text)) {
                     const hits = postings.get(word);
                     if (hits)
@@ -62,17 +120,20 @@ export function registerOperationVocabulary(tool, rows) {
                 }
             }
         }
-        const key = wanted.join(" ");
+        const key = alternatives.map((words) => words.join("|")).join(" ");
         let found = cache.get(key);
         if (!found) {
-            const lists = wanted.map((word) => postings.get(word) ?? []).sort((a, b) => a.length - b.length);
+            const lists = alternatives
+                .map((words) => [...new Set(words.flatMap((word) => postings.get(word) ?? []))])
+                .sort((a, b) => a.length - b.length);
             const rest = lists.slice(1).map((list) => new Set(list));
             found = lists[0].filter((id) => rest.every((set) => set.has(id)));
             if (cache.size >= OPERATION_VOCABULARY_BOUNDS.cache)
                 cache.delete(cache.keys().next().value);
             cache.set(key, found);
         }
-        return found.some((id) => {
+        // The same endpoint, safety and visibility checks decide both answers.
+        const admitted = found.filter((id) => {
             const row = routes[id];
             if (row.write && readOnly)
                 return false;
@@ -80,6 +141,47 @@ export function registerOperationVocabulary(tool, rows) {
                 return false;
             return row.route !== undefined && visible.has(row.route);
         });
+        // A ready call must name what the query asks for. Every object word, or
+        // a declared synonym, belongs to a whole resource name whose words the
+        // query states in order. A word met only in a summary, or only as part of
+        // a compound name, can route a search, never stand in for the resource.
+        const objects = alternatives.filter((words) => !ACTIONS.has(words[0]));
+        const at = (name, start) => start + name.length <= objects.length && name.every((word, offset) => objects[start + offset].includes(word));
+        const covers = (names) => {
+            const covered = objects.map(() => false);
+            for (const name of names)
+                for (let start = 0; start < objects.length; start++)
+                    if (at(name, start))
+                        name.forEach((_, offset) => (covered[start + offset] = true));
+            return covered.every(Boolean);
+        };
+        const asked = new Set(alternatives.flat());
+        return {
+            matched: admitted.length > 0,
+            ready: objects.length
+                ? admitted
+                    .flatMap((id) => {
+                    const { route, write, ready } = routes[id];
+                    if (!ready || write || !route || !covers(ready.names))
+                        return [];
+                    return [
+                        {
+                            path: ready.path,
+                            summary: ready.summary,
+                            route,
+                            id,
+                            // Relevance first: the last segment names the resource asked
+                            // for, then the fewest resource words the query did not ask for.
+                            last: Number(objects.some((_, start) => ready.last.length > 0 && at(ready.last, start))),
+                            extra: [...ready.terms].filter((word) => !asked.has(word) && !ACTIONS.has(word)).length,
+                        },
+                    ];
+                })
+                    .sort((a, b) => b.last - a.last || a.extra - b.extra || a.path.length - b.path.length || a.id - b.id)
+                    .slice(0, MAX_READY_PER_VOCABULARY)
+                    .map(({ path, summary, route }) => ({ path, summary, route }))
+                : [],
+        };
     });
 }
 /** Move private facts across the public ApiTool -> Connector construction boundary. */
@@ -91,11 +193,31 @@ export function registerConnectorVocabulary(connector, declarations) {
     if (entries.length)
         connectors.set(connector, new Map(entries));
 }
+/**
+ * Read tools whose operation vocabulary matches every query word, and the
+ * fully determined reads among those operations, each through a visible read
+ * tool of `catalog`: the caller's view, after endpoint, connector, hidden-tool
+ * and grant filtering.
+ */
 export function operationVocabularyMatches(connector, catalog, query, safety, readOnly) {
     const registered = connectors.get(connector);
+    const tools = [];
+    const ready = [];
     if (!registered)
-        return [];
+        return { tools, ready };
     const visible = new Set(catalog.map((tool) => tool.name));
-    return catalog.filter((tool) => tool.classification === "read" &&
-        registered.get(tool.name)?.(query, visible, safety, readOnly || connector.readOnly === true));
+    const synonyms = groupsOf(connector);
+    for (const tool of catalog) {
+        const vocabulary = tool.classification === "read" ? registered.get(tool.name) : undefined;
+        const found = vocabulary?.(query, visible, safety, readOnly || connector.readOnly === true, synonyms);
+        if (!found?.matched)
+            continue;
+        tools.push(tool);
+        for (const { route, ...call } of found.ready) {
+            const target = catalog.find((candidate) => candidate.name === route);
+            if (target?.classification === "read")
+                ready.push({ ...call, tool: target });
+        }
+    }
+    return { tools, ready };
 }

package/dist/operator-record.d.ts

@@ -8,7 +8,7 @@ type FailureStep = "MCP handshake" | "tools/list" | "tools/call" | "resources/re
  */
 export declare const OAUTH_ERROR_CODES: ReadonlySet<string>;
 /** Inbound denial facts, never identity text or provider diagnostics. */
-export type AuthDenialReason = "authentication_abandoned_saturated" | "authentication_busy" | "authentication_failed" | "authentication_provider_missing" | "authentication_unreachable" | "access_context_missing" | "access_context_unavailable" | "access_audience_invalid" | "access_identity_unavailable" | "access_authorization_header_rejected" | "authorization_header_invalid" | "token_type_mismatch" | "oauth_verification_failed" | "oauth_client_not_allowed" | "oauth_binding_mismatch" | "session_origin_mismatch" | "token_identity_mismatch" | "organization_membership_denied" | "organization_lookup_failed" | "organization_lookup_busy" | "user_missing" | "email_lookup_failed" | "verified_email_invalid" | "email_domain_denied" | "gate_denied" | "gate_failed" | "not_maintainer" | "pool_not_declared" | "not_pool_member";
+export type AuthDenialReason = "authentication_abandoned_saturated" | "authentication_busy" | "authentication_failed" | "authentication_provider_missing" | "authentication_unreachable" | "access_context_missing" | "access_context_unavailable" | "access_audience_invalid" | "access_identity_unavailable" | "access_authorization_header_rejected" | "authorization_header_invalid" | "token_type_mismatch" | "oauth_verification_failed" | "oauth_client_not_allowed" | "oauth_binding_mismatch" | "session_origin_mismatch" | "token_identity_mismatch" | "organization_membership_denied" | "organization_lookup_failed" | "organization_lookup_busy" | "user_missing" | "email_lookup_failed" | "verified_email_invalid" | "email_domain_denied" | "gate_denied" | "gate_failed" | "ambiguous_pool" | "not_maintainer" | "pool_not_declared" | "not_pool_member";
 /**
  * Name `ctor`'s instances `label` in records and fixed text. Call once, at
  * module scope, beside the class. An error whose prototype chain reaches no
@@ -110,7 +110,7 @@ export declare function failureRecord(subject: FailureSubject, failure?: unknown
  * The events an operator log reports failures as. Closed: a new one is a
  * reviewed line here, never a string assembled at the call site.
  */
-export type FailureEvent = "Authentication admission refused" | "Cloudflare Access verification unavailable" | "operator_refused" | "Authentication released after its pending work became unreachable" | "negotiation cache read failed" | "negotiation cache write failed" | "pool tool grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "MCP agent endpoint request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "operator agent slots read failed" | "result paging unavailable" | "native catalog unavailable" | "native name collision" | "native tools/list refused a pool over the 1,000-tool native cap" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
+export type FailureEvent = "Authentication admission refused" | "Cloudflare Access verification unavailable" | "operator_refused" | "Authentication released after its pending work became unreachable" | "negotiation cache read failed" | "negotiation cache write failed" | "discovery health read failed" | "discovery health write failed" | "pool tool grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "credential verification record failed" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "MCP agent endpoint request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "operator agent slots read failed" | "result paging unavailable" | "native catalog unavailable" | "native name collision" | "native tools/list refused a pool over the 1,000-tool native cap" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
 /**
  * Log one failure as `[connecta] <event>` and its record. A record
  * `failureRecord` did not build is replaced, whatever its shape, by a fixed

package/dist/operator-record.js

@@ -86,6 +86,7 @@ const AUTH_DENIAL_REASONS = new Set([
     "email_domain_denied",
     "gate_denied",
     "gate_failed",
+    "ambiguous_pool",
     "not_maintainer",
     "pool_not_declared",
     "not_pool_member",