@zackbart/connecta 0.39.0 → 0.41.0

package/dist/catalog-cache.js

@@ -1,3 +1,5 @@
+import { traceFor } from "./timing-trace.js";
+import { markCatalogGeneration } from "./catalog-freshness.js";
 import { detach, runEdge } from "./runtime/run.js";
 import { Deferred, Effect } from "effect";
 import { authFlow, authCall, authInvoke, authValue, authMethod, authProgram, registerAuth, authStorage, authStorageMany, authMap, authAwait, } from "./auth/native.js";
@@ -412,6 +414,83 @@ const invalidateCatalogCacheNative = /* @__PURE__ */ registerAuth(invalidateCata
         advanceCatalogRevision(storage);
     }
 }));
+// Only detached JSON facts cross requests: no context, storage, promises or
+// callbacks. FIFO bounds retained partitions, JSON/key text (UTF-16 worst
+// case) and structural slots. No WeakRef or timers required.
+const catalogStores = new WeakMap();
+const validatedCatalogs = new Map();
+let validatedBytes = 0;
+const VALIDATED_BYTES = 8 * 1024 * 1024;
+function rememberValidated(key, value, bytes) {
+    bytes = bytes * 2 + key.length * 2;
+    if (bytes > VALIDATED_BYTES || validatedCatalogs.has(key))
+        return;
+    const pending = [value];
+    while (pending.length) {
+        const item = pending.pop();
+        if (!item || typeof item !== "object" || Object.isFrozen(item))
+            continue;
+        Object.freeze(item);
+        for (const child of Object.values(item)) {
+            // Charge structural overhead too: tiny JSON objects/arrays can occupy
+            // much more heap than their serialized bytes alone suggest.
+            bytes += 64;
+            if (bytes > VALIDATED_BYTES)
+                return;
+            pending.push(child);
+        }
+    }
+    while (validatedCatalogs.size >= 4 || validatedBytes + bytes > VALIDATED_BYTES) {
+        const oldest = validatedCatalogs.keys().next().value;
+        validatedBytes -= validatedCatalogs.get(oldest).bytes;
+        validatedCatalogs.delete(oldest);
+    }
+    validatedCatalogs.set(key, { value, bytes });
+    validatedBytes += bytes;
+}
+const catalogLocation = authMethod((ctx, config, authPartition) => authFlow(function* () {
+    const policy = serviceFor(ctx, CatalogPolicy);
+    const partition = JSON.stringify([
+        policy?.partition ?? JSON.stringify(callerOf(ctx) ?? null),
+        ctx.baseUrl,
+        ctx.publicUrl,
+        authPartition,
+    ]);
+    const sharedPartition = JSON.stringify([
+        "host-shared",
+        policy?.sharedPartition ?? JSON.stringify([ctx.baseUrl, ctx.publicUrl, callerOf(ctx)?.pool]),
+        authPartition,
+    ]);
+    const configHash = (yield authCall(fingerprintSerializedCatalog, [
+        JSON.stringify([
+            config,
+            policy?.defaultTtlMs ?? 300000,
+            policy?.minTtlMs ?? 0,
+            policy?.maxTtlMs ?? MAX_CACHE_TTL_MS,
+        ]),
+    ])).fingerprint;
+    return { partition, sharedPartition, configHash };
+}));
+/** Prefetch candidates only; authority, identity and acceptance stay fresh. */
+export const prefetchCatalog = authMethod((ctx, connectorId, config, authPartition, sharing, credentialIdentity, negotiationKey) => authFlow(function* () {
+    const { partition, sharedPartition, configHash } = yield authCall(catalogLocation, [ctx, config, authPartition]);
+    const slots = sharing === "shared" ? [partition, sharedPartition] : [partition];
+    const suffixes = [];
+    for (const slot of slots)
+        suffixes.push((yield authCall(fingerprintSerializedCatalog, [
+            JSON.stringify(["tools/list", slot, credentialIdentity ?? null]),
+        ])).fingerprint);
+    const storage = serviceFor(ctx, CatalogPolicy)?.storage ?? ctx.storage;
+    yield ownerReads(Context.get(viewServices(ctx), RequestScope)).prefetch([
+        { storage: ctx.storage, key: negotiationKey },
+        { storage, key: responseCacheKeys.generation(connectorId) },
+    ], (storage, keys) => authStorageMany(storage, keys), {
+        storage,
+        generationKey: responseCacheKeys.generation(connectorId),
+        prefix: responseCacheKeys.locatorPrefix(connectorId, configHash),
+        suffixes,
+    });
+}));
 /** Keys ignore self-reported serverInfo and bind the configured connector instead. */
 export function catalogClientOptions(ctx, connectorId, config, authPartition, connectionSignal, owner, sharing = "private", resolveCredentialIdentity, connectionless = false) {
     return runEdge(authProgram(catalogClientOptionsNative, [
@@ -441,26 +520,11 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
     // canonical request owner, never the initiating call's live services.
     const cacheMethod = (program) => authMethod((...args) => program(...args).pipe(Effect.provideService(RequestScope, request)));
     const policy = serviceFor(ctx, CatalogPolicy);
-    const partition = JSON.stringify([
-        policy?.partition ?? JSON.stringify(callerOf(ctx) ?? null),
-        ctx.baseUrl,
-        ctx.publicUrl,
-        authPartition,
-    ]);
-    const sharedPartition = JSON.stringify([
-        "host-shared",
-        policy?.sharedPartition ?? JSON.stringify([ctx.baseUrl, ctx.publicUrl, callerOf(ctx)?.pool]),
-        authPartition,
-    ]);
+    const { partition, sharedPartition, configHash } = yield authCall(catalogLocation, [ctx, config, authPartition]);
     const storage = policy?.storage ?? ctx.storage;
-    const configHash = (yield authCall(fingerprintSerializedCatalog, [
-        JSON.stringify([
-            config,
-            policy?.defaultTtlMs ?? 300000,
-            policy?.minTtlMs ?? 0,
-            policy?.maxTtlMs ?? MAX_CACHE_TTL_MS,
-        ]),
-    ])).fingerprint;
+    let storeIdentity = catalogStores.get(storage);
+    if (!storeIdentity)
+        catalogStores.set(storage, (storeIdentity = crypto.randomUUID()));
     const scope = cacheScope(ctx, connectorId, owner);
     let unavailable = false;
     const connectionGeneration = {};
@@ -518,7 +582,8 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
     }));
     const namespace = cacheMethod((operation, memoized = false) => authFlow(function* () {
         const { stopped, generation, io } = operation;
-        if (resolveCredentialIdentity &&
+        if (!memoized &&
+            resolveCredentialIdentity &&
             (yield authCall(io, [resolveCredentialIdentity])) !== operation.credentialIdentity)
             return undefined;
         const current = (yield authCall(currentGeneration, [operation, memoized]));
@@ -544,7 +609,9 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             pair.length !== 2 ||
             (pair[1] !== partition && (pair[1] !== "" || sharing !== "shared")))
             return undefined;
-        // Locating only: get's fence and set's publication re-check fresh.
+        // Locate with the listing's pinned identity and generation. Neither
+        // authorizes acceptance: get's post-chunk fence and set's publication
+        // re-read both, so rotation or disconnect during I/O refuses the entry.
         const prefix = (yield authCall(namespace, [operation, true]));
         if (!prefix || stopped())
             return undefined;
@@ -636,12 +703,36 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
         get: cacheMethod((key) => authFlow(function* () {
             const operation = capture();
             const { ctx, stopped, io } = operation;
+            const trace = traceFor(ctx.requestScope);
+            trace?.record("catalog.cache.lookup");
             const root = (yield authCall(address, [key, operation]));
             if (!root || stopped())
                 return undefined;
-            const m = manifest((yield authCall(io, [
-                cacheMethod(() => authStorage(storage, "get", [root])),
-            ])));
+            // The SDK probes private, then public. Derive both addresses from
+            // the already-bound locating generation and identity, and fetch
+            // them in one statement. The post-chunk namespace check stays fresh.
+            const listing = operation.listing;
+            if (listing && !listing.manifests?.has(root)) {
+                const slots = sharing === "shared" ? [partition, sharedPartition] : [partition];
+                const roots = [];
+                for (const slot of slots) {
+                    const { fingerprint } = (yield authCall(fingerprintSerializedCatalog, [
+                        JSON.stringify([key.method, slot, operation.credentialIdentity ?? null]),
+                    ]));
+                    roots.push(responseCacheKeys.entry(responseCacheKeys.namespace(connectorId, configHash, operation.generation.value), fingerprint));
+                }
+                yield reads.prefetch(roots.map((key) => ({ storage, key })), (storage, keys) => authStorageMany(storage, keys));
+                const values = [];
+                for (const root of roots)
+                    values.push(yield reads.read(storage, root, authStorage(storage, "get", [root])));
+                listing.manifests ??= new Map();
+                roots.forEach((root, i) => listing.manifests.set(root, values[i] ?? null));
+            }
+            const m = manifest(listing?.manifests?.has(root)
+                ? listing.manifests.get(root)
+                : (yield authCall(io, [
+                    cacheMethod(() => authStorage(storage, "get", [root])),
+                ])));
             if (stopped() ||
                 !m ||
                 (m.expiresAt <= Date.now() &&
@@ -670,23 +761,41 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                 !(yield authCall(namespace, [operation])) ||
                 stopped())
                 return undefined;
-            const result = JSON.parse(value);
             const method = key.method;
-            const items = catalogItems(method, result);
-            if (!Array.isArray(items) ||
-                items.length > MAX_CATALOG_TOOLS ||
-                "nextCursor" in result ||
-                (result.resultType !== undefined && result.resultType !== "complete"))
-                return undefined;
-            const validated = (yield authInvoke(catalogSchema(method)["~standard"], "validate", [result]));
-            if (stopped() || validated.issues)
-                return undefined;
-            const clean = intake(ctx, method, validated.value);
+            // root binds connector/config/generation/scope/credential; partition
+            // also binds the current owner/deployment even for public entries.
+            // Hash the chunks again above, never trust the manifest alone.
+            const reuseKey = JSON.stringify([storeIdentity, root, partition, m.fingerprint]);
+            let accepted = validatedCatalogs.get(reuseKey)?.value;
+            trace?.record(accepted ? "catalog.validated.hit" : "catalog.validated.miss");
+            if (!accepted) {
+                const result = JSON.parse(value);
+                trace?.record("catalog.decode", 0, fingerprint.byteLength);
+                const items = catalogItems(method, result);
+                if (!Array.isArray(items) ||
+                    items.length > MAX_CATALOG_TOOLS ||
+                    "nextCursor" in result ||
+                    (result.resultType !== undefined && result.resultType !== "complete"))
+                    return undefined;
+                const validated = (yield authInvoke(catalogSchema(method)["~standard"], "validate", [result]));
+                trace?.record("catalog.validate");
+                if (stopped() || validated.issues)
+                    return undefined;
+                accepted = validated.value;
+            }
+            // Redaction depends on this request's sent credentials. It must
+            // still run, and returns detached objects from the frozen facts.
+            const clean = intake(ctx, method, accepted);
+            trace?.record("catalog.intake");
+            trace?.record("catalog.chunks", 0, fingerprint.byteLength, 0, 0, m.chunkCount);
+            rememberValidated(reuseKey, accepted, fingerprint.byteLength);
             if (m.expiresAt <= Date.now()) {
+                trace?.record("catalog.cache.expired");
                 if (method === "tools/list" && (!staleTools || staleTools.manifest.fetchedAt < m.fetchedAt))
                     staleTools = { result: clean, manifest: m };
                 return undefined;
             }
+            trace?.record("catalog.cache.hit");
             observeCatalogFetch(ctx, m.fetchedAt, method);
             observeCatalogExpiry(ctx, method, clean.ttlMs, m.expiresAt);
             return { value: JSON.stringify(clean), stamp: m.stamp, expiresAt: m.expiresAt, scope: m.scope };
@@ -697,6 +806,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             const root = (yield authCall(address, [key, operation]));
             if (!root || stopped())
                 return 0;
+            operation.listing?.manifests?.delete(root);
             const result = JSON.parse(entry.value);
             const method = key.method;
             if (catalogTtlMs(ctx, result.ttlMs) === 0) {
@@ -783,10 +893,12 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
         delete: cacheMethod((key) => authFlow(function* () {
             const operation = capture();
             const root = (yield authCall(address, [key, operation]));
-            if (root && !operation.stopped())
+            if (root && !operation.stopped()) {
+                operation.listing?.manifests?.delete(root);
                 (yield authInvoke(operation, "io", [
                     cacheMethod(() => authStorage(storage, "delete", [root])),
                 ]));
+            }
         })),
         evict: cacheMethod((method) => authFlow(function* () {
             if (isCatalogMethod(method))
@@ -860,7 +972,9 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                         logFailure(listingCtx.logger, "catalog read failed", failureRecord({ connector: connectorId }, error));
                     }
                 }
-                return yield authCall(read, []);
+                const result = yield authCall(read, []);
+                markCatalogGeneration(listingCtx.requestScope, connectorId, listing.generation.value);
+                return result;
             }
             finally {
                 listing.ended = true;

package/dist/catalog-freshness.js

@@ -11,3 +11,16 @@ export function carryCatalogFreshness(source, copy) {
 export function catalogIsFresh(tools) {
     return (deadlines.get(tools) ?? 0) > Date.now();
 }
+// Primitive accepted-generation evidence lives only beside the current request.
+const generations = new WeakMap();
+export function markCatalogGeneration(scope, connector, generation) {
+    if (!scope || generation === undefined)
+        return;
+    let values = generations.get(scope);
+    if (!values)
+        generations.set(scope, (values = new Map()));
+    values.set(connector, generation);
+}
+export function catalogGenerationFor(scope, connector) {
+    return generations.get(scope)?.get(connector);
+}

package/dist/catalog-service.js

@@ -1,12 +1,16 @@
+import { utilityRecovery } from "./utility-recovery.js";
+import { traceFor } from "./timing-trace.js";
+import { utf8Length } from "./bytes.js";
+import { catalogOwnerPartition } from "./catalog-policy.js";
 import { registerAuthMethod } from "./auth/native.js";
 import { META_ROUTES, routeToolInPlace } from "./agent-routes.js";
 import { withAuthorizationHandoffEffect } from "./authorization-handoff.js";
-import { carryCatalogFreshness, catalogIsFresh } from "./catalog-freshness.js";
+import { carryCatalogFreshness, catalogIsFresh, catalogGenerationFor } from "./catalog-freshness.js";
 import { retainedCatalogIdentity } from "./catalog-cache.js";
 import { cloneTool } from "./tool-safety.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 { prepareLexicalCatalog, carryLexicalCatalog, compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, typescriptSignature, } from "./catalog.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, ConnectorCallError, framingError } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName } from "./skills.js";
@@ -20,6 +24,8 @@ import { keepErrorName } from "./redaction-identity.js";
 import { operationVocabularyMatches, searchSynonyms } from "./operation-vocabulary.js";
 /** The slice of an unscoped search's budget kept for recording what its probes saw. */
 const SETTLE_RESERVE_MS = 500;
+const lexicalStores = new WeakMap();
+let nextLexicalStore = 0;
 /** How long a probe claim outlives its request's discovery budget, for settlement and clock skew. */
 const CLAIM_MARGIN_MS = 2_000;
 /** A connector unscoped search skipped because its discovery failed recently. */
@@ -299,19 +305,17 @@ const catalogFailureProperties = {
         },
     },
     retry: { type: "string" },
+    // Handoff fields above carry the detailed authorization contract. Keep
+    // additive action advice compact in the always-loaded search schema.
     nextAction: {
         type: "object",
-        required: ["tool", "arguments", "operatorHandoff"],
-        additionalProperties: false,
+        anyOf: [{ required: ["tool"] }, { required: ["action"] }],
         properties: {
             tool: { const: "authorize_connector" },
-            arguments: {
-                type: "object",
-                required: ["connector"],
-                additionalProperties: false,
-                properties: { connector: { type: "string" } },
-            },
-            operatorHandoff: { type: "string" },
+            action: { enum: ["contact_operator", "inspect_capabilities"] },
+            purpose: STRING,
+            operatorHandoff: STRING,
+            arguments: { type: "object", properties: { connector: STRING } },
         },
     },
 };
@@ -533,6 +537,7 @@ export class CatalogService {
                     timeoutMs: this.probeTimeoutMs,
                     ...(this.defer ? { defer: this.defer } : {}),
                 }).pipe(Effect.map((tools) => {
+                    traceFor(this.requestScope)?.record("catalog.accepted", 0, utf8Length(JSON.stringify(tools)), 0, 0, tools.length);
                     // An authored catalog lists its declared descriptions for this request's surface.
                     const connector = this.registry.getConnector(id);
                     return carryCatalogFreshness(tools, tools.map((tool) => {
@@ -565,6 +570,7 @@ export class CatalogService {
         let view = views.get(key);
         if (!view) {
             view = toolsForSafety(readOnly ? tools.filter((tool) => tool.classification === "read") : tools, safety ?? "all");
+            carryLexicalCatalog(tools, view);
             views.set(key, view);
         }
         return view;
@@ -793,6 +799,9 @@ export class CatalogService {
                     message: `Connector "${connector.id}" was skipped because its catalog lookup failed recently (${failure.code}). Search with connector "${connector.id}" to try it now.`,
                     retryable: true,
                     retryAfterMs: failure.retryAfterMs,
+                    ...(["unavailable", "catalog_lookup_failed", "unsupported_capability"].includes(failure.code)
+                        ? { nextAction: utilityRecovery(failure.code, "Catalog lookup is unavailable.").nextAction }
+                        : {}),
                 };
             }
             const classified = classifyCallError(failure, "catalog_lookup_failed");
@@ -830,6 +839,9 @@ export class CatalogService {
                 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.";
             }
+            if (["unavailable", "catalog_lookup_failed", "unsupported_capability"].includes(error.code)) {
+                error.nextAction = utilityRecovery(error.code, error.message).nextAction;
+            }
             return yield* withAuthorizationHandoffEffect(this.requestScope, error);
         });
     }
@@ -877,7 +889,22 @@ export class CatalogService {
             const connectors = absence ? [] : args.connector ? (scopedConnector ? [scopedConnector] : []) : visibleConnectors;
             // Timeout messages name the route the caller used.
             const catalogs = yield* this.searchCatalogs(connectors.map((connector) => connector.id), args.connector !== undefined);
-            const searchableCatalogs = catalogs.map((catalog, index) => Result.map(catalog, (tools) => this.searchView(connectors[index].id, tools, true, safety)));
+            const searchableCatalogs = catalogs.map((catalog, index) => Result.map(catalog, (tools) => {
+                const id = connectors[index].id;
+                const ctx = this.registry.contextFor(id, this.baseUrl, this.requestScope);
+                const { storage, partition } = catalogOwnerPartition(ctx);
+                let store = lexicalStores.get(storage);
+                if (store === undefined)
+                    lexicalStores.set(storage, (store = ++nextLexicalStore));
+                prepareLexicalCatalog(tools, JSON.stringify([
+                    store,
+                    id,
+                    partition,
+                    retainedCatalogIdentity(ctx),
+                    catalogGenerationFor(this.requestScope, id),
+                ]));
+                return this.searchView(id, tools, true, safety);
+            }));
             const matches = [];
             let matchMode = "all";
             // Provider-declared synonyms widen term matching within their own catalog only.

package/dist/catalog.js

@@ -164,38 +164,93 @@ export function lexicalSearchContent(query) {
     return contentTerms.join(" ");
 }
 const searchIndexes = new WeakMap();
-function indexFor(tools) {
-    let index = searchIndexes.get(tools);
-    if (!index) {
-        const nameTokenDocuments = new Map();
-        const descriptionTokenDocuments = new Map();
-        const addTokens = (target, tokens, tool) => {
-            for (const token of new Set(tokens)) {
-                const documents = target.get(token) ?? [];
-                documents.push(tool);
-                target.set(token, documents);
-            }
-        };
-        const documents = tools.map((tool) => {
-            const nameTokens = lexicalTokens(tool.name);
-            const descriptionTokens = lexicalTokens(tool.description ?? "");
-            addTokens(nameTokenDocuments, nameTokens, tool);
-            addTokens(descriptionTokenDocuments, descriptionTokens, tool);
-            return {
-                tool,
-                name: nameTokens.join(" "),
-                nameTokens,
-                descriptionTokens,
-            };
+// Only immutable token strings and numeric positions cross requests. The key
+// holds exactly what buildIndex reads, in order, so schemas cost nothing here;
+// it avoids hash collisions and charges its UTF-16 storage as well.
+const retainedIndexes = new Map();
+const INDEX_BYTES = 8 * 1024 * 1024;
+let retainedBytes = 0;
+function buildIndex(tools) {
+    const nameTokenDocuments = new Map();
+    const descriptionTokenDocuments = new Map();
+    const addTokens = (target, tokens, position) => {
+        for (const token of new Set(tokens)) {
+            const documents = target.get(token) ?? [];
+            documents.push(position);
+            target.set(token, documents);
+        }
+    };
+    const documents = tools.map((tool, position) => {
+        const nameTokens = lexicalTokens(tool.name);
+        const descriptionTokens = [...new Set(lexicalTokens(tool.description ?? ""))];
+        addTokens(nameTokenDocuments, nameTokens, position);
+        addTokens(descriptionTokenDocuments, descriptionTokens, position);
+        return Object.freeze({
+            name: nameTokens.join(" "),
+            nameTokens: Object.freeze(nameTokens),
+            descriptionTokens: Object.freeze(descriptionTokens),
         });
-        index = {
-            documents,
-            nameTokenDocuments,
-            descriptionTokenDocuments,
-        };
-        searchIndexes.set(tools, index);
+    });
+    for (const map of [nameTokenDocuments, descriptionTokenDocuments])
+        for (const positions of map.values())
+            Object.freeze(positions);
+    // Maps remain private to this module and are never mutated after construction.
+    return Object.freeze({
+        documents: Object.freeze(documents),
+        nameTokenDocuments,
+        descriptionTokenDocuments,
+    });
+}
+function bindIndex(tools, index) {
+    const view = { index, tools: new Map(tools.map((tool, position) => [position, tool])) };
+    searchIndexes.set(tools, view);
+    return view;
+}
+/** Only call after complete catalog acceptance, redaction and classification. */
+export function prepareLexicalCatalog(tools, partition) {
+    if (searchIndexes.has(tools))
+        return;
+    const key = JSON.stringify([partition, tools.map((tool) => [tool.name, tool.description ?? ""])]);
+    const retained = retainedIndexes.get(key);
+    if (retained) {
+        bindIndex(tools, retained.index);
+        return;
+    }
+    const index = buildIndex(tools);
+    bindIndex(tools, index);
+    let bytes = key.length * 2 + 128;
+    for (const doc of index.documents) {
+        bytes += 128 + doc.name.length * 2;
+        for (const tokens of [doc.nameTokens, doc.descriptionTokens])
+            for (const token of tokens)
+                bytes += 32 + token.length * 2;
     }
-    return index;
+    for (const map of [index.nameTokenDocuments, index.descriptionTokenDocuments])
+        for (const [token, positions] of map)
+            bytes += 96 + token.length * 2 + positions.length * 8;
+    if (bytes > INDEX_BYTES)
+        return;
+    while (retainedIndexes.size >= 4 || retainedBytes + bytes > INDEX_BYTES) {
+        const oldest = retainedIndexes.keys().next().value;
+        retainedBytes -= retainedIndexes.get(oldest).bytes;
+        retainedIndexes.delete(oldest);
+    }
+    retainedIndexes.set(key, { index, bytes });
+    retainedBytes += bytes;
+}
+/** Project immutable positions onto this request's currently visible objects. */
+export function carryLexicalCatalog(source, visible) {
+    const view = searchIndexes.get(source);
+    if (!view || source === visible)
+        return;
+    const allowed = new Set(visible);
+    searchIndexes.set(visible, {
+        index: view.index,
+        tools: new Map([...view.tools].filter(([, tool]) => allowed.has(tool))),
+    });
+}
+function indexFor(tools) {
+    return searchIndexes.get(tools) ?? bindIndex(tools, buildIndex(tools));
 }
 /**
  * Whole-token equality is the ordinary lexical match. A deliberately narrow
@@ -289,11 +344,15 @@ export function lexicalCorpusStatistics(toolSets, query, synonymsFor) {
         for (const tools of toolSets) {
             const index = indexFor(tools);
             for (const candidate of synonymCandidates(term, synonymsFor?.(tools))) {
-                for (const tool of index.nameTokenDocuments.get(candidate) ?? []) {
-                    termNameMatches.add(tool);
+                for (const position of index.index.nameTokenDocuments.get(candidate) ?? []) {
+                    const tool = index.tools.get(position);
+                    if (tool)
+                        termNameMatches.add(tool);
                 }
-                for (const tool of index.descriptionTokenDocuments.get(candidate) ?? []) {
-                    termDescriptionMatches.add(tool);
+                for (const position of index.index.descriptionTokenDocuments.get(candidate) ?? []) {
+                    const tool = index.tools.get(position);
+                    if (tool)
+                        termDescriptionMatches.add(tool);
                 }
             }
         }
@@ -365,13 +424,19 @@ export function rankTools(tools, query, mode = "all", statistics = lexicalCorpus
     const exactNamePhrase = normalized(exactNameQuery);
     const terms = [...new Set(phrase.split(/\s+/).filter(Boolean))];
     const ranked = [];
-    indexFor(tools).documents.forEach((doc, order) => {
-        const scored = scoreDocument(doc, phrase, terms, mode, statistics);
+    const view = indexFor(tools);
+    let order = 0;
+    view.index.documents.forEach((doc, position) => {
+        const tool = view.tools.get(position);
+        if (!tool)
+            return;
+        const visibleOrder = order++;
+        const scored = scoreDocument({ ...doc, tool }, phrase, terms, mode, statistics);
         if (scored !== null) {
             ranked.push({
-                tool: doc.tool,
+                tool,
                 score: scored.score,
-                order,
+                order: visibleOrder,
                 exactName: queryContainsExactName(doc, exactNamePhrase),
                 matchedTermCount: scored.matchedTermCount,
             });

package/dist/config.d.ts

@@ -211,7 +211,7 @@ declare const pool: {
      * What this pool is for, in plain words for the model: appended to the MCP
      * `initialize` instructions at `/mcp/<name>` and `/agent/<name>`, so a
      * caller learns its scope ("Team tier: shared tools only."). Trimmed, 1 to
-     * 500 characters, no line breaks or control characters. It grants and hides nothing; plain
+     * 500 UTF-16 code units, no line breaks or control characters. It grants and hides nothing; plain
      * `/mcp` never shows it.
      */
     description: import("./config-schema.js").Field<string, string | undefined, true>;
@@ -283,8 +283,9 @@ declare const connectaConfig: {
      */
     storage: import("./config-schema.js").Field<KVStorage, KVStorage, true>;
     /**
-     * Public base URL. Defaults to the request origin per-request. Configuring an
-     * HTTPS URL also redirects matching inbound HTTP requests to HTTPS.
+     * Public base URL. Defaults to the request origin per-request, except that
+     * clerkAuth requires it here or as its own `publicUrl`. Configuring an HTTPS
+     * URL also redirects matching inbound HTTP requests to HTTPS.
      */
     publicUrl: import("./config-schema.js").Field<string, string | undefined, true>;
     /**
@@ -294,7 +295,10 @@ declare const connectaConfig: {
     allowedOrigins: import("./config-schema.js").Field<readonly string[] | "*", readonly string[] | "*" | undefined, true>;
     /** Optional recorder and reader, created by activityHistory() from /activity. */
     activity: import("./config-schema.js").Field<ActivityModule, ActivityModule | undefined, true>;
-    /** Replaceable owner-partitioned credential storage. Omit for config-owned secrets. */
+    /**
+     * Replaceable owner-partitioned credential storage. Omit for config-owned
+     * secrets. With any OAuth connector it must implement `seal` and `open`.
+     */
     vault: import("./config-schema.js").Field<CredentialVault, CredentialVault | undefined, true>;
     /** Optional connection UI, created by operatorUi() from /ui. */
     ui: import("./config-schema.js").Field<OperatorSurface, OperatorSurface | undefined, true>;
@@ -542,6 +546,8 @@ declare const connectaConfig: {
             };
         };
     };
+    /** Payload-free request timing logs; 0 disables tracing, 1 samples every MCP request. */
+    timingTraceSampleRate: import("./config-schema.js").Field<number, number, true>;
     /** Diagnostic output. Use "silent" to disable all diagnostic logging. */
     logger: import("./config-schema.js").Field<Logger | "silent", Logger, true>;
     serverInfo: import("./config-schema.js").Field<{