@zackbart/connecta 0.38.0 → 0.40.0

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",

package/dist/operator-ui/contract.d.ts

@@ -25,6 +25,16 @@ export interface OperatorConnectorOverlay {
     catalogAgeMs: number | null;
     /** Latest visible call in the bounded activity window, or null when unknown. */
     lastCall: OperatorLastCall | null;
+    /**
+     * Age of the stored status observation this row shows, when it came from
+     * storage rather than a live read. Its tools may be empty until a live read.
+     */
+    observedAgeMs?: number;
+    /**
+     * Browser-only: when that stored observation was made, in epoch
+     * milliseconds, fixed once as the row lands so its age keeps counting.
+     */
+    observedAt?: number;
 }
 /** Whole connector access, or exact tool grants. `requireReadOnly` is always false since guarded grants were removed. */
 export interface OperatorGrant {