@zackbart/connecta 0.16.1 → 0.18.0

package/dist/registry.js

@@ -1,3 +1,4 @@
+import { closeConnectorScope, } from "./connector-scope.js";
 import { recordCatalogDriftActivity, } from "./activity.js";
 import { storedCredentialShape, } from "./credentials.js";
 import { ConnectorCallError } from "./errors.js";
@@ -6,6 +7,8 @@ import { boundedCatalogDrift } from "./catalog-drift.js";
 import { fingerprintSerializedCatalog, snapshotCatalog, } from "./catalog-fingerprint.js";
 import { MAX_CATALOG_CHUNK_BYTES, MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES, } from "./catalog-limits.js";
 import { mapSettledWithConcurrency } from "./concurrency.js";
+import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, } from "./skills.js";
+import { withAbortableTimeout } from "./timeout.js";
 const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
@@ -122,6 +125,10 @@ export class Registry {
     catalogMutations = new Map();
     /** Same-request cold loads share one promise without retaining the request. */
     requestCatalogLoads = new WeakMap();
+    /** One live refresh per connector across agent and operator requests. */
+    catalogRefreshes = new Map();
+    /** Last payload-free agent catalog access in this runtime. */
+    catalogAccess = new Map();
     /** Deployment-wide observations — every call, whatever view made it. */
     health = new HealthLog();
     /** Last drift counts reported to activity, per connector, in this runtime. */
@@ -146,6 +153,16 @@ export class Registry {
             if (this.connectors.has(c.id)) {
                 throw new Error(`Duplicate connector id "${c.id}"`);
             }
+            const configuredGuideSummary = typeof c.usageGuide === "object"
+                ? normalizeGuideSummary(c.usageGuide.summary ?? "")
+                : undefined;
+            if (configuredGuideSummary !== undefined &&
+                configuredGuideSummary.length > GUIDE_SUMMARY_LENGTH) {
+                throw new Error(`Connector "${c.id}" usageGuide.summary is ` +
+                    `${configuredGuideSummary.length} characters after whitespace ` +
+                    `normalization; the discovery bound is ${GUIDE_SUMMARY_LENGTH}. ` +
+                    "Shorten it or omit it to derive one.");
+            }
             this.connectors.set(c.id, c);
             if (c.callAdmission) {
                 this.callAdmission.set(c.id, new ConnectorCallAdmissionController(c.id, c.callAdmission));
@@ -592,19 +609,20 @@ export class Registry {
             .catch(() => { });
         return next;
     }
-    /** Force a live listTools refresh and replace both catalog cache layers. */
-    async refreshTools(id, baseUrl, requestScope, callOptions = {}) {
-        const connector = this.connectors.get(id);
-        if (!connector)
-            throw new Error(`Unknown connector "${id}"`);
-        if (connector.staticTools)
-            return connector.staticTools;
+    async refreshToolsWithContext(id, connector, ctx, skipPublicationWhenAborted = false) {
         const generation = this.catalogGeneration(id);
-        const tools = await connector.listTools(this.contextFor(id, baseUrl, requestScope, callOptions));
+        const tools = await connector.listTools(ctx);
         // The listing a maintained proxy just served is also the only catalog
         // comparison connecta ever makes. It rides this refresh whether or not the
         // result reaches a cache, because what drifted drifted.
         this.observeCatalogDrift(connector);
+        // A deferred deadline may close the owned scope while a connector that
+        // ignores abort is still listing. The completed list remains a valid drift
+        // observation, but must not overwrite a newer same-generation refresh.
+        // Blocking callers do not set this flag and retain their prior publication
+        // behavior when an inbound abort races a completed listing.
+        if (skipPublicationWhenAborted && ctx.signal?.aborted)
+            return tools;
         // The caller that began this refresh may still use its result, but a
         // credential/OAuth change that landed while listTools was in flight means
         // the listing must not enter either shared cache layer.
@@ -618,8 +636,10 @@ export class Registry {
         }
         const previous = this.cache.get(id);
         const snapshot = await snapshotCatalog(tools);
-        if (generation !== this.catalogGeneration(id))
+        if (generation !== this.catalogGeneration(id) ||
+            (skipPublicationWhenAborted && ctx.signal?.aborted)) {
             return tools;
+        }
         if (snapshot.serializedBytes.byteLength > MAX_SERIALIZED_CATALOG_BYTES) {
             const message = `Connector "${id}" returned a ${snapshot.serializedBytes.byteLength}-byte ` +
                 `serialized catalog, over the ${MAX_SERIALIZED_CATALOG_BYTES}-byte ceiling; ` +
@@ -653,8 +673,106 @@ export class Registry {
         }
         return tools;
     }
+    /**
+     * Publish one shared refresh promise before starting its connector work.
+     * The first caller owns the scope and deadline; every later caller joins the
+     * result without gaining access to that context.
+     */
+    startCatalogRefresh(id, generation, start, finish) {
+        const existing = this.catalogRefreshes.get(id);
+        if (existing?.generation === generation)
+            return existing;
+        let resolveWork;
+        let rejectWork;
+        const work = new Promise((resolve, reject) => {
+            resolveWork = resolve;
+            rejectWork = reject;
+        });
+        let flight;
+        const promise = work
+            .finally(async () => {
+            if (finish)
+                await finish();
+        })
+            .finally(() => {
+            if (this.catalogRefreshes.get(id) === flight) {
+                this.catalogRefreshes.delete(id);
+            }
+        });
+        flight = { generation, promise };
+        this.catalogRefreshes.set(id, flight);
+        try {
+            Promise.resolve(start()).then(resolveWork, rejectWork);
+        }
+        catch (err) {
+            rejectWork(err);
+        }
+        return flight;
+    }
+    /** Force a live listTools refresh and replace both catalog cache layers. */
+    async refreshTools(id, baseUrl, requestScope, callOptions = {}) {
+        const connector = this.connectors.get(id);
+        if (!connector)
+            throw new Error(`Unknown connector "${id}"`);
+        if (connector.staticTools)
+            return connector.staticTools;
+        const ctx = this.contextFor(id, baseUrl, requestScope, callOptions);
+        return this.startCatalogRefresh(id, this.catalogGeneration(id), () => this.refreshToolsWithContext(id, connector, ctx)).promise;
+    }
+    observeCatalogAccess(id, state) {
+        this.catalogAccess.set(id, {
+            state,
+            observedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * Start or join one shared refresh. A newly deferred task owns its scope,
+     * deadline, and teardown; no inbound signal or request scope crosses into it.
+     */
+    deferCatalogRefresh(id, baseUrl, expectedGeneration, options) {
+        const connector = this.connectors.get(id);
+        if (!connector || connector.staticTools || !options.defer)
+            return;
+        let flight = this.catalogRefreshes.get(id);
+        if (flight?.generation !== expectedGeneration)
+            flight = undefined;
+        if (!flight) {
+            const requestScope = {};
+            let ctx;
+            flight = this.startCatalogRefresh(id, expectedGeneration, () => withAbortableTimeout((signal) => {
+                const current = this.cache.get(id);
+                if (current && current.exp > Date.now()) {
+                    return Promise.resolve(current.tools);
+                }
+                if (expectedGeneration !== this.catalogGeneration(id) ||
+                    this.invalidated.has(id)) {
+                    return Promise.reject(new Error(`Deferred catalog refresh of "${id}" was invalidated before it started.`));
+                }
+                ctx = this.contextFor(id, baseUrl, requestScope, {
+                    signal,
+                    timeoutMs: options.refreshTimeoutMs,
+                });
+                return this.refreshToolsWithContext(id, connector, ctx, true);
+            }, options.refreshTimeoutMs, `deferred catalog refresh of "${id}"`), async () => {
+                if (ctx)
+                    await closeConnectorScope(connector, ctx, options.defer);
+            });
+        }
+        if (!flight.deferredTail) {
+            // Attach the rejection handler before handing the tail to waitUntil.
+            flight.deferredTail = flight.promise.then(() => { }, (err) => {
+                this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh failed: ${msg(err)}`);
+            });
+        }
+        try {
+            options.defer(flight.deferredTail);
+        }
+        catch (err) {
+            this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh could not attach to the runtime: ${msg(err)}`);
+        }
+    }
     /** Cached listTools with in-memory + persisted serializable catalog layers. */
-    async loadTools(id, baseUrl, requestScope, callOptions = {}) {
+    async loadTools(id, baseUrl, requestScope, callOptions = {}, readOptions) {
         const connector = this.connectors.get(id);
         if (!connector)
             throw new Error(`Unknown connector "${id}"`);
@@ -663,9 +781,14 @@ export class Registry {
         const now = Date.now();
         const requestGeneration = this.catalogGeneration(id);
         const hit = this.cache.get(id);
-        if (hit && hit.exp > now)
+        if (hit && hit.exp > now) {
+            if (readOptions?.defer)
+                this.observeCatalogAccess(id, "fresh");
             return hit.tools;
-        let stale = hit && hit.staleUntil > now ? hit.tools : undefined;
+        }
+        let stale = hit && hit.staleUntil > now
+            ? { tools: hit.tools, staleUntil: hit.staleUntil }
+            : undefined;
         if (this.persistToolCatalog && !this.invalidated.has(id)) {
             const generation = this.catalogGeneration(id);
             let persisted = null;
@@ -679,49 +802,95 @@ export class Registry {
                 persisted = null;
                 stale = undefined;
             }
-            if (persisted && persisted.staleUntil > now) {
+            // Storage can yield while another request finishes a live refresh. Read
+            // the shared cache again before an older manifest gets any authority.
+            // The candidate with the later fresh deadline wins; both candidates have
+            // already passed their own fingerprint and completeness checks.
+            const reconciledAt = Date.now();
+            const current = this.cache.get(id);
+            const usableCurrent = current && current.staleUntil > reconciledAt ? current : undefined;
+            if (usableCurrent) {
+                stale = {
+                    tools: usableCurrent.tools,
+                    staleUntil: usableCurrent.staleUntil,
+                };
+                if (usableCurrent.exp > reconciledAt) {
+                    if (readOptions?.defer)
+                        this.observeCatalogAccess(id, "fresh");
+                    return usableCurrent.tools;
+                }
+            }
+            if (persisted &&
+                persisted.staleUntil > reconciledAt &&
+                (!usableCurrent || persisted.expiresAt > usableCurrent.exp)) {
                 this.cache.set(id, {
                     tools: persisted.tools,
                     fingerprint: persisted.fingerprint,
                     exp: persisted.expiresAt,
                     staleUntil: persisted.staleUntil,
                 });
-                if (persisted.expiresAt > now)
+                if (persisted.expiresAt > reconciledAt) {
+                    if (readOptions?.defer)
+                        this.observeCatalogAccess(id, "fresh");
                     return persisted.tools;
-                stale = persisted.tools;
+                }
+                stale = {
+                    tools: persisted.tools,
+                    staleUntil: persisted.staleUntil,
+                };
+            }
+        }
+        if (stale &&
+            stale.staleUntil > Date.now() &&
+            readOptions?.defer &&
+            requestGeneration === this.catalogGeneration(id) &&
+            !this.invalidated.has(id)) {
+            this.deferCatalogRefresh(id, baseUrl, requestGeneration, readOptions);
+            // Invalidation can land synchronously while the refresh is attached.
+            // Repeat the authority check at the exact stale publication point.
+            if (stale.staleUntil > Date.now() &&
+                requestGeneration === this.catalogGeneration(id) &&
+                !this.invalidated.has(id)) {
+                this.observeCatalogAccess(id, "stale");
+                return stale.tools;
             }
         }
         try {
-            return await this.refreshTools(id, baseUrl, requestScope, callOptions);
+            const tools = await this.refreshTools(id, baseUrl, requestScope, callOptions);
+            if (readOptions?.defer)
+                this.observeCatalogAccess(id, "fresh");
+            return tools;
         }
         catch (err) {
             if (stale &&
+                stale.staleUntil > Date.now() &&
                 requestGeneration === this.catalogGeneration(id) &&
                 !this.invalidated.has(id)) {
+                if (readOptions?.defer)
+                    this.observeCatalogAccess(id, "stale");
                 this.opts.logger.warn(`[connecta] connector "${id}" catalog refresh failed; serving stale catalog: ${msg(err)}`);
-                return stale;
+                return stale.tools;
             }
             throw err;
         }
     }
     /**
-     * Coalesce one connector's cold load inside one inbound request. The WeakMap
-     * neither roots the request scope nor lets its connector context escape into
-     * another request; settled entries are also removed eagerly.
+     * Coalesce one connector's catalog traversal inside one inbound request. The
+     * WeakMap neither roots the request scope nor lets its connector context
+     * escape into another request; settled entries are also removed eagerly.
      *
-     * The first caller's `callOptions` govern the shared load: a later caller's
-     * signal or timeout neither cancels nor extends it, and an abort by the
-     * first caller rejects every coalesced caller. Within one request that is
-     * the deal being made — one fetch, one deadline.
+     * The deployment-wide flight below this layer coalesces the actual live
+     * refresh across requests. Its first caller's context and deadline govern;
+     * later callers join only its result, never its request scope.
      */
-    async getTools(id, baseUrl, requestScope, callOptions = {}) {
+    async getTools(id, baseUrl, requestScope, callOptions = {}, readOptions) {
         const connector = this.connectors.get(id);
         if (!connector)
             throw new Error(`Unknown connector "${id}"`);
         if (connector.staticTools)
             return connector.staticTools;
         if (!requestScope) {
-            return this.loadTools(id, baseUrl, requestScope, callOptions);
+            return this.loadTools(id, baseUrl, requestScope, callOptions, readOptions);
         }
         let loads = this.requestCatalogLoads.get(requestScope);
         if (!loads) {
@@ -731,7 +900,7 @@ export class Registry {
         const existing = loads.get(id);
         if (existing)
             return existing;
-        const loading = this.loadTools(id, baseUrl, requestScope, callOptions);
+        const loading = this.loadTools(id, baseUrl, requestScope, callOptions, readOptions);
         loads.set(id, loading);
         try {
             return await loading;
@@ -796,24 +965,39 @@ export class Registry {
         // The report is rebuilt rather than spread through: what the seam returned
         // is third-party output, and status is read by the operator UI and copied
         // into responses.
-        const withDrift = (status) => {
+        const withObservations = (status) => {
             const report = boundedCatalogDrift(connector.catalogDrift?.());
-            return report ? { ...status, catalogDrift: report } : status;
+            const access = this.catalogAccess.get(id);
+            // Connector.status is an open plugin seam. Rebuild its public fields so
+            // a connector cannot smuggle payload through either registry-owned
+            // observation when this runtime has not made one.
+            const boundedStatus = {
+                state: status.state,
+                ...(status.authorizationUrl !== undefined
+                    ? { authorizationUrl: status.authorizationUrl }
+                    : {}),
+                ...(status.message !== undefined ? { message: status.message } : {}),
+            };
+            return {
+                ...boundedStatus,
+                ...(report ? { catalogDrift: report } : {}),
+                ...(access ? { catalogAccess: { ...access } } : {}),
+            };
         };
         if (connector.status) {
             try {
-                return withDrift(await connector.status(ctx));
+                return withObservations(await connector.status(ctx));
             }
             catch (err) {
-                return withDrift({ state: "error", message: msg(err) });
+                return withObservations({ state: "error", message: msg(err) });
             }
         }
         try {
             await this.getTools(id, baseUrl, requestScope, callOptions);
-            return withDrift({ state: "ok" });
+            return withObservations({ state: "ok" });
         }
         catch (err) {
-            return withDrift({ state: "error", message: msg(err) });
+            return withObservations({ state: "error", message: msg(err) });
         }
     }
     markCatalogInvalid(id) {

package/dist/routes/mcp.js

@@ -234,6 +234,9 @@ async function serveMcp(request, opts, baseUrl, actor, registry, runtimeContext)
                 ? { discoveryConcurrency: opts.discoveryConcurrency }
                 : {}),
             requestSignal: request.signal,
+            ...(runtimeContext?.waitUntil
+                ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+                : {}),
         });
         registerExecuteTool(server, registry, {
             baseUrl,
@@ -241,6 +244,9 @@ async function serveMcp(request, opts, baseUrl, actor, registry, runtimeContext)
             logger: opts.logger,
             ...(activity ? { activity } : {}),
             requestSignal: request.signal,
+            ...(runtimeContext?.waitUntil
+                ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+                : {}),
             ...(opts.discoveryConcurrency !== undefined
                 ? { discoveryConcurrency: opts.discoveryConcurrency }
                 : {}),

package/dist/routes/ui.js

@@ -28,7 +28,7 @@ const INERT_ICON_HEADERS = {
     "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
     "X-Content-Type-Options": "nosniff",
 };
-/** Per-request base64 nonce for an operator shell's scripts (Node 20+ and Workers). */
+/** Per-request base64 nonce for an operator shell's scripts (Node 22+ and Workers). */
 function uiScriptNonce() {
     const bytes = crypto.getRandomValues(new Uint8Array(16));
     let binary = "";

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Connecta exposes seven meta-tools. For one read at an unknown address, search_tools with 2\u20134 distinctive action/object terms and includeSchemas=\"compact\", then one call_tool \u2014 a lone cold call is cheaper direct than a program. For read-only reduction, multiple or dependent calls, loops, joins, or branches, do not call top-level search_tools: make one execute_code call whose program searches, selects, calls, and reduces; never return discovery for another call. connecta.ui(html) is a guest function inside execute_code, never a connector address or search_tools result; pass one HTML string for display-only, or bind named read-only refresh/drill-down calls in its optional reads argument, and return the same initial summary data the HTML renders. Unannotated, write-capable, or destructive tools stay top level: search_tools, then call_destructive_tool; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: \"usage\" }).";
+export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use fields or get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: \"usage\" }) once for program syntax, selection, repair, examples, and runtime details.";
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export declare const USAGE_SKILL: string;
 /** The always-loaded MCP `instructions` string. */
@@ -10,6 +10,10 @@ export declare function hasConnectorGuides(connectors: readonly Connector[]): bo
 export declare function connectorSkillName(connectorId: string): string;
 /** The connector's guide, or undefined when it declares none (or a blank one). */
 export declare function connectorGuide(connector: Connector): string | undefined;
+/** Discovery budget for one connector-guide summary, including an ellipsis. */
+export declare const GUIDE_SUMMARY_LENGTH = 120;
+/** Normalize authored and derived summaries under one construction contract. */
+export declare function normalizeGuideSummary(summary: string): string | undefined;
 /** Bounded, decision-useful discovery summary for a connector guide. */
 export declare function connectorGuideSummary(connector: Connector): string | undefined;
 /** Whether correct use always depends on conventions outside the tool schema. */