@zackbart/connecta 0.25.0 → 0.26.0

package/dist/registry.js

@@ -1,4 +1,4 @@
-import { Cause, Clock, Deferred, Effect, Exit, Result } from "effect";
+import { Cause, Clock, Deferred, Duration, Effect, Exit, Option, Result, } from "effect";
 import { storedCredentialShape, } from "./credential-rules.js";
 import { ConnectorCallError, msg } from "./errors.js";
 import { ConnectorCallAdmissionController, aggregateCallAdmissionSnapshots, } from "./call-admission.js";
@@ -8,10 +8,14 @@ import { MAX_CATALOG_CHUNK_BYTES, MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTE
 import { ObservedOutputSchemas } from "./result-shapes.js";
 import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, } from "./skills.js";
 import { attachOAuthSealer, vaultOAuthSealer } from "./oauth-sealing.js";
+import { attachCaller } from "./connector-caller.js";
 import { closeScopeOnExit } from "./runtime/connector-scope.js";
 import { detach, runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { SharedRead } from "./runtime/shared-read.js";
 import { Logger as LoggerService } from "./runtime/services.js";
 import { runOnPartition, storageDelete, storageGet, storageSet, } from "./runtime/storage.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs } from "./timeout.js";
+import { isExplicitlyReadOnly } from "./tool-safety.js";
 const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
@@ -69,6 +73,17 @@ export function resolveMaxResultBytes(value, inherited) {
         ? value
         : inherited;
 }
+/**
+ * What a joiner hears from a flight that will not answer for it: one that
+ * passed its bound, or failed for a reason that was its owner's alone. It
+ * never reaches a caller; a joiner that hears it makes a fresh attempt.
+ */
+class AbandonedCatalogRefresh extends Error {
+    constructor(id) {
+        super(`The catalog refresh of "${id}" was abandoned.`);
+        this.name = "AbandonedCatalogRefresh";
+    }
+}
 const CATALOG_CHUNK_IO_CONCURRENCY = 4;
 /**
  * Run `operation` over every chunk index or chunk with the fixed chunk I/O
@@ -129,7 +144,7 @@ export class Registry {
     // completes once its storage work is done; see enqueueCatalogMutation.
     /** Serialize persisted catalog set/delete operations within this isolate. */
     catalogMutations = new Map();
-    /** Same-request cold loads share one promise without retaining the request.
+    /** Same-request cold loads share one read without retaining the request.
      * See documentation/architecture.md#the-two-lifetimes. */
     requestCatalogLoads = new WeakMap();
     /** One live refresh per connector across agent and operator requests. */
@@ -811,7 +826,7 @@ export class Registry {
             Deferred.doneUnsafe(turn, Exit.void);
         }
     }
-    async refreshToolsWithContext(id, connector, ctx, skipPublicationWhenAborted = false) {
+    async refreshToolsWithContext(id, connector, ctx, skipPublicationWhenAborted = false, flight) {
         const generation = this.catalogGeneration(id);
         const tools = await connector.listTools(ctx);
         // The listing a maintained proxy just served is also the only catalog
@@ -826,9 +841,10 @@ export class Registry {
         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.
-        if (generation !== this.catalogGeneration(id))
+        // credential/OAuth change that landed while listTools was in flight, or a
+        // flight abandoned while it listed, means the listing must not enter
+        // either shared cache layer.
+        if (!this.mayPublish(id, generation, flight))
             return tools;
         if (tools.length > MAX_CATALOG_TOOLS) {
             const message = `Connector "${id}" returned ${tools.length} tools, over the ` +
@@ -838,7 +854,7 @@ export class Registry {
         }
         const previous = this.cache.get(id);
         const snapshot = await snapshotCatalog(tools);
-        if (generation !== this.catalogGeneration(id) ||
+        if (!this.mayPublish(id, generation, flight) ||
             (skipPublicationWhenAborted && ctx.signal?.aborted)) {
             return tools;
         }
@@ -872,28 +888,88 @@ 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.
+     * Whether a refresh may still enter the shared cache layers: its generation
+     * is current, and the flight it runs in has been neither abandoned nor
+     * outlived its bound. Asked at each publication point, since listing and
+     * snapshotting both yield, and a late result must never overwrite the one a
+     * fresh attempt published in the meantime.
+     */
+    mayPublish(id, generation, flight) {
+        return (generation === this.catalogGeneration(id) &&
+            (!flight || (!flight.abandoned && Date.now() < flight.abandonAt)));
+    }
+    /**
+     * Publish one shared refresh before starting its connector work. The first
+     * caller owns the scope and signal, and the flight lives `boundMs` from now
+     * at most; every later caller joins the result without gaining access to
+     * that context. A flight found past its bound is abandoned here, and this
+     * caller starts the fresh attempt.
      */
-    startCatalogRefresh(id, generation, work) {
+    startCatalogRefresh(id, generation, boundMs, work, ownerLeft = () => false) {
         const existing = this.catalogRefreshes.get(id);
-        if (existing?.generation === generation)
-            return { flight: existing };
+        if (existing?.generation === generation) {
+            if (Date.now() < existing.abandonAt)
+                return { flight: existing };
+            this.abandonCatalogRefresh(id, existing);
+        }
         const flight = {
             generation,
+            abandonAt: Date.now() + boundMs,
+            abandoned: false,
             outcome: Deferred.makeUnsafe(),
         };
         this.catalogRefreshes.set(id, flight);
-        const owner = Effect.onExit(work, (exit) => Effect.sync(() => {
+        const owner = Effect.onExit(work(flight), (exit) => Effect.sync(() => {
             if (this.catalogRefreshes.get(id) === flight) {
                 this.catalogRefreshes.delete(id);
             }
+            // A failure that was the owner's alone is no answer for anyone
+            // else: its own cancellation (its signal, read here in its own
+            // request), or anything that arrives once the flight is past its
+            // bound. Joiners make a fresh attempt under their own deadlines.
+            const ownersAlone = Exit.isFailure(exit) &&
+                (flight.abandoned ||
+                    Date.now() >= flight.abandonAt ||
+                    ownerLeft());
             // Last, because joined fibers resume inside this call.
-            Deferred.doneUnsafe(flight.outcome, exit);
+            Deferred.doneUnsafe(flight.outcome, ownersAlone ? Exit.fail(new AbandonedCatalogRefresh(id)) : exit);
         }));
         return { flight, owner };
     }
+    /**
+     * Give up on a flight that outlived its bound. Later readers start a fresh
+     * attempt, its joiners are told to, and nothing its owner lists from now on
+     * reaches a cache. The owner's work is left alone: it belongs to another
+     * request, which nothing here may reach into, and it can no longer publish.
+     */
+    abandonCatalogRefresh(id, flight) {
+        if (flight.abandoned)
+            return;
+        flight.abandoned = true;
+        if (this.catalogRefreshes.get(id) === flight) {
+            this.catalogRefreshes.delete(id);
+        }
+        this.opts.logger.warn(`[connecta] connector "${id}" catalog refresh outlived its bound; abandoning it for a fresh attempt.`);
+        Deferred.doneUnsafe(flight.outcome, Exit.fail(new AbandonedCatalogRefresh(id)));
+    }
+    /**
+     * Wait on another caller's flight, no longer than its bound. Succeeds with
+     * its tools, or with `undefined` when it will not answer for this caller —
+     * past its bound, when this waiter abandons it, or failed for its owner
+     * alone — so the caller makes a fresh attempt. The timer is this waiter's
+     * own: on workerd it is what keeps a request that waits on another alive,
+     * and bounded.
+     */
+    joinCatalogRefresh(id, flight) {
+        return Effect.suspend(() => Deferred.await(flight.outcome).pipe(Effect.timeoutOption(Duration.millis(Math.max(0, flight.abandonAt - Date.now()))), Effect.flatMap((joined) => Option.isSome(joined)
+            ? Effect.succeed(joined.value)
+            : Effect.sync(() => {
+                this.abandonCatalogRefresh(id, flight);
+                return undefined;
+            })), Effect.catch((error) => error instanceof AbandonedCatalogRefresh
+            ? Effect.succeed(undefined)
+            : Effect.fail(error))));
+    }
     /** Force a live listTools refresh and replace both catalog cache layers. */
     async refreshTools(id, baseUrl, requestScope, callOptions = {}) {
         const connector = this.connectors.get(id);
@@ -901,14 +977,27 @@ export class Registry {
             throw new Error(`Unknown connector "${id}"`);
         if (connector.staticTools)
             return connector.staticTools;
-        const { flight, owner } = this.startCatalogRefresh(id, this.catalogGeneration(id), Effect.tryPromise({
-            try: () => this.refreshToolsWithContext(id, connector, this.contextFor(id, baseUrl, requestScope, callOptions)),
-            catch: (error) => error,
-        }));
-        // The owner lists in its own request. A joiner waits through an edge of
-        // its own, and whatever it does with the tools happens after that, back in
-        // its request (see "Effect inside" in documentation/architecture.md).
-        return runEdge(owner ?? Deferred.await(flight.outcome));
+        // A flight lives as long as its owner will wait for it. Past that, the
+        // owner may have answered and gone, and on workerd its I/O went with it.
+        const boundMs = normalizeTimeoutMs(callOptions.timeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
+        for (;;) {
+            const { flight, owner } = this.startCatalogRefresh(id, this.catalogGeneration(id), boundMs, (flight) => Effect.tryPromise({
+                try: () => this.refreshToolsWithContext(id, connector, this.contextFor(id, baseUrl, requestScope, callOptions), false, flight),
+                catch: (error) => error,
+            }), () => callOptions.signal?.aborted === true);
+            // The owner lists in its own request. A joiner waits through an edge of
+            // its own, under its own signal, and whatever it does with the tools
+            // happens after that, back in its request (see "Effect inside" in
+            // documentation/architecture.md). A flight that will not answer for it
+            // sends it round again, to join a fresh attempt or to own one.
+            if (owner)
+                return runEdge(owner);
+            const joined = await runEdge(this.joinCatalogRefresh(id, flight), {
+                signal: callOptions.signal,
+            });
+            if (joined)
+                return joined;
+        }
     }
     observeCatalogAccess(id, state) {
         this.catalogAccess.set(id, {
@@ -928,7 +1017,7 @@ export class Registry {
         // The refresh this request starts, if none of this generation is live.
         // Its scope is closed however it ends, deadline included, before the
         // flight completes.
-        const refresh = withDeadlineEffect((signal) => Effect.gen({ self: this }, function* () {
+        const refresh = (flight) => withDeadlineEffect((signal) => Effect.gen({ self: this }, function* () {
             const current = this.cache.get(id);
             if (current && current.exp > Date.now())
                 return current.tools;
@@ -942,7 +1031,7 @@ export class Registry {
             });
             yield* closeScopeOnExit(connector, ctx, defer);
             return yield* Effect.tryPromise({
-                try: () => this.refreshToolsWithContext(id, connector, ctx, true),
+                try: () => this.refreshToolsWithContext(id, connector, ctx, true, flight),
                 catch: (error) => error,
             });
         }), {
@@ -952,14 +1041,15 @@ export class Registry {
         const logFailure = (err) => {
             this.opts.logger.warn(`[connecta] connector "${id}" deferred catalog refresh failed: ${msg(err)}`);
         };
-        const { flight, owner } = this.startCatalogRefresh(id, expectedGeneration, Effect.scoped(refresh));
+        const { flight, owner } = this.startCatalogRefresh(id, expectedGeneration, options.refreshTimeoutMs, (flight) => Effect.scoped(refresh(flight)));
         if (owner) {
             // Runs past this response, under the runtime's waitUntil below.
             flight.deferredTail = detach(Effect.catchCause(owner, (cause) => Effect.sync(() => logFailure(Cause.squash(cause)))));
         }
         // A stale reader that joins a blocking refresh logs its failure once for
-        // every reader after it, and waits through an edge of its own.
-        flight.deferredTail ??= runEdge(Deferred.await(flight.outcome)).then(() => { }, logFailure);
+        // every reader after it, and waits through an edge of its own, no longer
+        // than the flight's bound.
+        flight.deferredTail ??= runEdge(this.joinCatalogRefresh(id, flight)).then(() => { }, logFailure);
         try {
             defer(flight.deferredTail);
         }
@@ -1075,9 +1165,15 @@ export class Registry {
      * WeakMap neither roots the request scope nor lets its connector context
      * escape into another request; settled entries are also removed eagerly.
      *
+     * The read owns its signal, and each caller waits under its own: one that
+     * is cancelled while others wait leaves with its own failure, and the read
+     * is cancelled only when every caller has gone (src/runtime/shared-read.ts).
+     *
      * 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.
+     * refresh across requests. Its owner's context governs the listing, and its
+     * owner's deadline bounds it; later callers join only its result, never its
+     * request scope, and a failure that was the owner's alone sends them to a
+     * fresh attempt rather than to them.
      */
     async getTools(id, baseUrl, requestScope, callOptions = {}, readOptions) {
         const connector = this.connectors.get(id);
@@ -1093,20 +1189,23 @@ export class Registry {
             loads = new Map();
             this.requestCatalogLoads.set(requestScope, loads);
         }
-        const existing = loads.get(id);
-        if (existing)
-            return existing;
-        const loading = this.loadTools(id, baseUrl, requestScope, callOptions, readOptions);
-        loads.set(id, loading);
-        try {
-            return await loading;
-        }
-        finally {
-            if (loads.get(id) === loading)
-                loads.delete(id);
-            if (loads.size === 0)
-                this.requestCatalogLoads.delete(requestScope);
+        const requestLoads = loads;
+        let load = requestLoads.get(id);
+        if (!load) {
+            const started = new SharedRead((signal) => this.loadTools(id, baseUrl, requestScope, { ...callOptions, signal }, readOptions), 
+            // Settled or cancelled, the read leaves the map before any caller
+            // resumes, so the next one asks the caches afresh.
+            () => {
+                if (requestLoads.get(id) === started)
+                    requestLoads.delete(id);
+                if (requestLoads.size === 0) {
+                    this.requestCatalogLoads.delete(requestScope);
+                }
+            });
+            requestLoads.set(id, started);
+            load = started;
         }
+        return runEdge(load.join(callOptions.signal));
     }
     async credentialDriftFor(id) {
         const credential = this.connectors.get(id)?.credential;
@@ -1231,15 +1330,17 @@ class ScopedRegistryView {
             throw new Error(`Unknown connector "${args[0]}"`);
         }
         const tools = await registry.getTools(...args);
-        const granted = this.scope.toolAccess?.get(args[0]);
+        const guarded = this.scope.guardedToolAccess?.get(args[0]);
+        const granted = this.scope.toolAccess?.get(args[0]) ?? guarded;
         if (!granted)
             return tools;
         // Every consumer — search, describe, call_tool, and a program's
         // connecta.call — resolves through this list, so an ungranted tool is
         // indistinguishable from one the connector never had.
-        const visible = tools.filter((tool) => granted.has(tool.name));
+        const visible = tools.filter((tool) => granted.has(tool.name) &&
+            (!guarded?.has(tool.name) || isExplicitlyReadOnly(tool)));
         if (visible.length < granted.size) {
-            const present = new Set(visible.map((tool) => tool.name));
+            const present = new Set(tools.map((tool) => tool.name));
             for (const name of granted) {
                 if (!present.has(name))
                     this.root.noteAbsentGrant(args[0], name);
@@ -1251,7 +1352,7 @@ class ScopedRegistryView {
         const registry = this.registryFor(args[0]);
         if (!registry)
             throw new Error(`Unknown connector "${args[0]}"`);
-        return registry.contextFor(...args);
+        return attachCaller(registry.contextFor(...args), this.scope.caller);
     }
     admitCall(...args) {
         const registry = this.registryFor(args[0]);