@zackbart/connecta 0.40.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";
@@ -446,6 +448,49 @@ function rememberValidated(key, value, bytes) {
     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, [
@@ -475,29 +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;
     let storeIdentity = catalogStores.get(storage);
     if (!storeIdentity)
         catalogStores.set(storage, (storeIdentity = crypto.randomUUID()));
-    const configHash = (yield authCall(fingerprintSerializedCatalog, [
-        JSON.stringify([
-            config,
-            policy?.defaultTtlMs ?? 300000,
-            policy?.minTtlMs ?? 0,
-            policy?.maxTtlMs ?? MAX_CACHE_TTL_MS,
-        ]),
-    ])).fingerprint;
     const scope = cacheScope(ctx, connectorId, owner);
     let unavailable = false;
     const connectionGeneration = {};
@@ -676,6 +703,8 @@ 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;
@@ -692,7 +721,10 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     ]));
                     roots.push(responseCacheKeys.entry(responseCacheKeys.namespace(connectorId, configHash, operation.generation.value), fingerprint));
                 }
-                const values = (yield authCall(io, [cacheMethod(() => authStorageMany(storage, roots))]));
+                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));
             }
@@ -735,8 +767,10 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             // 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 ||
@@ -744,6 +778,7 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
                     (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;
@@ -751,12 +786,16 @@ const catalogClientOptionsNative = /* @__PURE__ */ registerAuth(catalogClientOpt
             // 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 };
@@ -933,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<{

package/dist/config.js

@@ -189,7 +189,7 @@ function assertFlag(value, path) {
     if (typeof value !== "boolean")
         throw new ConfigError(`${path} must be true or false.`);
 }
-/** Longest pool `description`, in characters, after trimming. */
+/** Longest pool `description`, in UTF-16 code units, after trimming. */
 const MAX_POOL_DESCRIPTION_LENGTH = 500;
 /**
  * A pool description is one line of prose for the model. C0 and C1 controls
@@ -209,9 +209,9 @@ function assertPoolDescription(value, path) {
     const trimmed = typeof value === "string" ? value.trim() : undefined;
     if (trimmed === undefined ||
         trimmed.length === 0 ||
-        [...trimmed].length > MAX_POOL_DESCRIPTION_LENGTH ||
+        trimmed.length > MAX_POOL_DESCRIPTION_LENGTH ||
         hasLineBreakOrControlCharacter(trimmed)) {
-        throw new ConfigError(`${path} must be text of 1 to ${MAX_POOL_DESCRIPTION_LENGTH} characters after trimming, with no line breaks or control characters.`);
+        throw new ConfigError(`${path} must be text of 1 to ${MAX_POOL_DESCRIPTION_LENGTH} UTF-16 code units after trimming, with no line breaks or control characters.`);
     }
 }
 /** Shape only; each reference resolves against auth and agents in createConnecta. */
@@ -263,7 +263,7 @@ 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: opaque({ check: assertPoolDescription }),
@@ -396,8 +396,9 @@ const connectaConfig = {
         resolve: (value) => value ?? memoryStorage(),
     }),
     /**
-     * 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: opaque({ check: httpUrl }),
     /**
@@ -419,7 +420,10 @@ const connectaConfig = {
             }
         },
     }),
-    /** 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: opaque({
         check: (value) => {
             if (!hasMethods(value, ["get", "getAll", "set", "setAll", "metadata", "delete"]) ||
@@ -464,6 +468,14 @@ const connectaConfig = {
      * saturation.
      */
     admission: object(admission),
+    /** Payload-free request timing logs; 0 disables tracing, 1 samples every MCP request. */
+    timingTraceSampleRate: opaque({
+        check: (value, path) => {
+            if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1)
+                throw new ConfigError(`${path} must be a finite number between 0 and 1.`);
+        },
+        resolve: (value) => value ?? 0,
+    }),
     /** Diagnostic output. Use "silent" to disable all diagnostic logging. */
     logger: opaque({
         check: (value, path) => {
@@ -528,10 +540,21 @@ function assertCoherent(config) {
         config.discovery.catalogMaxTtlSeconds > 86_400) {
         throw new ConfigError("ConnectaConfig.discovery requires catalogMinTtlSeconds <= catalogMaxTtlSeconds <= 86400.");
     }
+    const { vault } = config;
+    const oauth = config.connectors.find((connector) => connector.startAuth);
+    if (oauth && vault && (typeof vault.seal !== "function" || typeof vault.open !== "function")) {
+        throw new ConfigError(`ConnectaConfig.vault must implement both seal and open: connector "${oauth.id}" stores downstream OAuth ` +
+            "tokens, client registration and PKCE verifiers through it. Use encryptedCredentialVault(storage, key) " +
+            "from @zackbart/connecta/credentials, or add both methods.");
+    }
     if (config.agents.some((agent) => !agent.vercel) && !config.accessTokens) {
         throw new ConfigError("ConnectaConfig.agents needs accessTokens: accessTokens(storage) from @zackbart/connecta/auth/access-tokens " +
             "holds each agent's token slot.");
     }
+    if (!config.publicUrl && config.auth.some((provider) => provider.requiresPublicUrl)) {
+        throw new ConfigError("ConnectaConfig.publicUrl is required with clerkAuth, which checks tokens and sessions against it: " +
+            "set it, or clerkAuth({ publicUrl }), to this deployment's URL, http://localhost:<port> for local development.");
+    }
 }
 /**
  * Validate a configuration and apply every default. Unknown keys are refused

package/dist/connectors/remote-mcp/call.js

@@ -55,7 +55,7 @@ export function remoteMcpCall(rt) {
                     }
                     : state.toolDefinitions.get(name);
                 if (toolDefinition?.execution?.taskSupport === "required") {
-                    throw new ConnectorCallError("connector_call_failed", `Tool "${name}" requires task-based execution, which Connecta does not support.`);
+                    throw new ConnectorCallError("unsupported_capability", `Tool "${name}" requires task-based execution, which Connecta does not support.`);
                 }
                 let output;
                 const outputError = (code, message) => rt.atMcpBoundary(ctx, new ProtocolError(code, message), "tools/call", client.transport, [ctx.signal]);