@zackbart/connecta 0.37.1 → 0.39.0

package/dist/native-tools.js

@@ -1,3 +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";
@@ -35,7 +37,7 @@ function shortHash(text) {
 const shortHashNative = /* @__PURE__ */ registerAuth(shortHash, function (text) {
     return authFlow(function* () {
         const digest = new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", enc.encode(text)])));
-        return [...digest.subarray(0, HASH_CHARS / 2)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+        return bytesToHex(digest.subarray(0, HASH_CHARS / 2));
     });
 });
 /**
@@ -148,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"),
         });
     }
     /**
@@ -182,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-handoff.js

@@ -1,3 +1,4 @@
+import { decodeBase64url } from "./bytes.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, authStorage, registerAuth } from "./auth/native.js";
 import { runEdge } from "./runtime/run.js";
@@ -58,8 +59,7 @@ function encodeSegment(value) {
 function decodeSegment(value) {
     if (!/^[A-Za-z0-9_-]+$/.test(value))
         throw new Error("Invalid handoff encoding");
-    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
-    const decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+    const decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(decodeBase64url(value));
     if (encodeSegment(decoded) !== value)
         throw new Error("Noncanonical handoff encoding");
     return decoded;

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,8 +1,18 @@
 // 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();
-export const OPERATION_VOCABULARY_BOUNDS = {
+const synonymGroups = new WeakMap();
+const OPERATION_VOCABULARY_BOUNDS = {
     operations: 8192,
     rowChars: 1024,
     chars: 2_097_152,
@@ -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

@@ -1,52 +1,4 @@
-// What an operator may read about a failure: log records and status text.
-// Web-API only — no node: imports here.
-//
-// Inbound identity-provider text never enters operator logs or status, even
-// when it fits a grammar. Activity retains its separate typed actor fields.
-//
-// Threat model. INV-6 here covers records of calls and failures: logs,
-// activity rows, status and statusFor, health, doctor output, and any native
-// runtime output connecta triggers (workerd's console). Text a downstream
-// server, HTTP API, or client authored, and anything derived from it, never
-// reaches one as arbitrary text. Self-declared client name/version facts in
-// activity use the bounded ASCII grammars in activityClientFact; invalid values are
-// absent at recording, SQL write/read, and operator UI boundaries. Client
-// capabilities and other metadata are never recorded. Every typed field
-// connecta records is checked against a closed set or a grammar. Operator-
-// authored code (custom connectors, plugin `status()`, decorators) is trusted
-// to follow the contract, and connecta still checks
-// the typed fields it records from it; deliberately adversarial operator code
-// is out of scope.
-//
-// Catalog metadata a connector serves is configuration the operator chose to
-// load, and agents already see it: a tool name that fits MCP's tool-name
-// grammar, a description, and input and output schemas may appear in the
-// authenticated operator page's catalog views, and such a name may be
-// logged. A name outside the grammar is withheld everywhere operator-facing,
-// the page included. Names containing C0, DEL, or C1 are dropped at catalog
-// intake; spaces and non-ASCII names remain callable with withheld records.
-//
-// INV-6 says logs carry no arguments, results, code, or raw downstream error
-// text. Filtering errors where they arise kept missing sources: a validator's
-// diagnostic, a stream's TypeError, a JSON-RPC error the agent may see. So the
-// rule is enforced here, at the sink. A failure reaches an operator only as
-// the fields of a `FailureRecord`, which `failureRecord` alone builds: each
-// one copied from an explicit list, checked against a constant table or a
-// grammar, and never taken from an error's message, cause, stack, data,
-// nested errors, or name. `logFailure` writes nothing else, and every status
-// message about a failure comes from `describeFailure`
-// (test/operator-record-sources.node.test.ts holds src/ to that).
-//
-// Provenance is by identity, never by shape. Text that merely looks like
-// connecta's (an error named like one of its classes, a status sentence
-// shaped like a record) carries no weight: a class label comes from the
-// prototype chain, a status message from the status object connecta built.
-//
-// Agent-facing results are a different surface with a different rule: a
-// downstream's own answer to a call may reach the agent that made it (see
-// documentation/architecture.md, "Errors and records"). Core's sent-secrets
-// boundary removes credentials used by the upstream request from those answers, including
-// allowed diagnostics, tool results and nested error causes/data (INV-5).
+// Payload-free operator failure records. See documentation/architecture.md, "Errors and records".
 import { carryProviderFailure } from "./provider-call-facts.js";
 import { followRedactedCopies, keepErrorName } from "./redaction-identity.js";
 import { classificationCode, ConnectorCallError, NETWORK_ERROR_CODES, WithheldTextError, } from "./errors.js";
@@ -134,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,8 +25,18 @@ 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 (#837). */
+/** Whole connector access, or exact tool grants. `requireReadOnly` is always false since guarded grants were removed. */
 export interface OperatorGrant {
     connectorId: string;
     tools: "all" | Array<{
@@ -197,5 +207,5 @@ export interface OperatorUiContractV2 {
         viewerKey: string;
     };
 }
-/** The operator contract `GET /ui/api/config` serves; schema version 1 was removed (#837). */
+/** The operator contract `GET /ui/api/config` serves; schema version 1 was removed. */
 export type OperatorUiContract = OperatorUiContractV2;