@zackbart/connecta 0.25.0 → 0.26.1

package/dist/program-source.js

@@ -3,6 +3,8 @@
 // QuickJS normalizer runs it too for callers that drive that executor directly.
 /** A whole-program markdown fence, as QuickJS's normalizer recognizes one. */
 const FENCE = /^```[\w-]*\s*\n([\s\S]*?)\n?```$/;
+/** Intake accepts one JavaScript fence, optionally surrounded by prose. */
+const PROGRAM_FENCE = /^```(?:js|javascript)?[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*$/gm;
 /** Leading whitespace and comments, which may precede the arrow expression. */
 const LEADING_TRIVIA = /^(?:\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/)+/;
 /** One character of an identifier, keyword, or number; `\\` for escapes. */
@@ -44,6 +46,120 @@ export function withoutProgramTerminator(code) {
     const stripped = stripTerminators(source);
     return stripped === source ? code : stripped;
 }
+/**
+ * Recover wrappers that models put around a single program. This runs in the
+ * host, so QuickJS and Dynamic Workers receive the same source. It does not
+ * turn arbitrary statements into a program: an arrow remains the contract.
+ */
+export function normalizeProgramSource(code) {
+    let source = code.trim();
+    const head = source.replace(LEADING_TRIVIA, "");
+    // A program may itself contain fenced Markdown in a comment or string. Once
+    // the source starts as a program, a fence inside it is data, never a wrapper.
+    if (!/^(?:async\b|\(|export\s+default\s+async\b)/.test(head)) {
+        const fences = [...source.matchAll(PROGRAM_FENCE)];
+        if (fences.length === 1) {
+            const fence = fences[0];
+            const outside = source.slice(0, fence.index) + source.slice(fence.index + fence[0].length);
+            const body = fence[1].trim();
+            const fencedHead = body.replace(LEADING_TRIVIA, "");
+            if (!outside.includes("```") && /^(?:async\b|\(|export\s+default\s+async\b)/.test(fencedHead)) {
+                source = body;
+            }
+        }
+    }
+    source = source.replace(/^export\s+default\s+(?=async\s*(?:\(|[A-Za-z_$]))/, "");
+    // The declaration must be the whole source. A scanner finds its own closing
+    // brace rather than mistaking a brace in a string or a second statement for
+    // the end of the function.
+    const named = /^async\s+function\s+([A-Za-z_$][\w$]*)\s*\(([^()]*)\)\s*\{/.exec(source);
+    if (named) {
+        const end = functionBodyEnd(source, named[0].length - 1);
+        if (end !== undefined && /^(?:\s|;|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*$/.test(source.slice(end + 1))) {
+            // Invoke a named function expression inside the arrow. Its own name and
+            // `arguments` binding then work exactly as in the original declaration.
+            source = `async (...args) => (async function ${named[1]}(${named[2]}) {${source.slice(named[0].length, end)}})(...args)${source.slice(end + 1)}`;
+        }
+    }
+    return withoutProgramTerminator(source);
+}
+/** Find the matching closing brace of a named function's body. */
+function functionBodyEnd(source, open) {
+    let depth = 0;
+    let previous = "";
+    for (let i = open; i < source.length; i++) {
+        const c = source[i];
+        if (/\s/.test(c))
+            continue;
+        if (c === "/" && source[i + 1] === "/") {
+            const end = source.indexOf("\n", i + 2);
+            i = end === -1 ? source.length : end;
+            continue;
+        }
+        if (c === "/" && source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            if (end === -1)
+                return undefined;
+            i = end + 1;
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            let end = i + 1;
+            for (; end < source.length && source[end] !== c; end++) {
+                if (source[end] === "\\")
+                    end++;
+                else if (source[end] === "\n" && c !== "`")
+                    return undefined;
+            }
+            if (end >= source.length)
+                return undefined;
+            i = end;
+            previous = "0";
+            continue;
+        }
+        if (c === "/" && startsRegex(previous)) {
+            let end = i + 1;
+            let inClass = false;
+            for (; end < source.length; end++) {
+                const r = source[end];
+                if (r === "\n")
+                    return undefined;
+                if (r === "\\")
+                    end++;
+                else if (r === "[")
+                    inClass = true;
+                else if (r === "]")
+                    inClass = false;
+                else if (r === "/" && !inClass)
+                    break;
+            }
+            if (end >= source.length)
+                return undefined;
+            i = end;
+            previous = "0";
+            continue;
+        }
+        if (WORD.test(c)) {
+            let end = i + 1;
+            while (end < source.length && WORD.test(source[end]))
+                end++;
+            previous = source.slice(i, end);
+            i = end - 1;
+            continue;
+        }
+        if (c === "{")
+            depth++;
+        else if (c === "}") {
+            depth--;
+            if (depth === 0)
+                return i;
+            if (depth < 0)
+                return undefined;
+        }
+        previous = c;
+    }
+    return undefined;
+}
 function stripTerminators(source) {
     const head = source.replace(LEADING_TRIVIA, "");
     if (!/^async\b/.test(head) && !head.startsWith("("))

package/dist/registry.d.ts

@@ -3,6 +3,7 @@ import type { CatalogDriftReport, Connector, ConnectorContext, ConnectorStatus,
 import { type DeferredWork } from "./connector-scope.js";
 import { type CatalogDriftActivityContext } from "./activity.js";
 import { type CallAdmissionPermit, type ConnectorCallAdmissionSnapshot } from "./call-admission.js";
+import { type ConnectorCaller } from "./connector-caller.js";
 /**
  * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
  * no dots, so a downstream tool name may. Exported because an address that
@@ -129,8 +130,11 @@ export type ToolAccess = ReadonlyMap<string, ReadonlySet<string>>;
 export interface RegistryScope {
     connectorIds: "all" | readonly string[];
     toolAccess?: ToolAccess;
+    guardedToolAccess?: ToolAccess;
     subjectKey?: string;
     principalKey?: string;
+    /** The admitted caller, readable only by built-in connectors; see connector-caller.ts. */
+    caller?: ConnectorCaller;
 }
 /**
  * Holds the connector set, resolves addresses, and caches per-connector tool
@@ -147,7 +151,7 @@ export declare class Registry implements RegistryView {
     private readonly catalogGenerations;
     /** Serialize persisted catalog set/delete operations within this isolate. */
     private readonly catalogMutations;
-    /** 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. */
     private readonly requestCatalogLoads;
     /** One live refresh per connector across agent and operator requests. */
@@ -283,11 +287,37 @@ export declare class Registry implements RegistryView {
     private enqueueCatalogMutation;
     private refreshToolsWithContext;
     /**
-     * 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.
+     */
+    private mayPublish;
+    /**
+     * 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.
      */
     private startCatalogRefresh;
+    /**
+     * 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.
+     */
+    private abandonCatalogRefresh;
+    /**
+     * 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.
+     */
+    private joinCatalogRefresh;
     /** Force a live listTools refresh and replace both catalog cache layers. */
     private refreshTools;
     private observeCatalogAccess;
@@ -303,9 +333,15 @@ export declare class Registry implements RegistryView {
      * 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.
      */
     getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, readOptions?: CatalogReadOptions): Promise<ToolDef[]>;
     credentialDriftFor(id: string): Promise<string | undefined>;

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. */
@@ -752,9 +767,10 @@ export class Registry {
             });
         });
     }
-    // Remove the persisted catalog: the manifest always, then the chunks it
-    // names. Every delete is attempted; the effect fails with the manifest
-    // read's error first, then the first chunk delete's.
+    // Remove the persisted catalog: the manifest and every chunk it names, all
+    // at once under the chunk I/O bound. Every delete is attempted; the effect
+    // fails with the manifest read's error first, then the manifest delete's,
+    // then the first chunk delete's by index.
     deleteCatalog(id) {
         return Effect.gen({ self: this }, function* () {
             const read = yield* Effect.result(storageGet(this.catalogKey(id)));
@@ -762,18 +778,20 @@ export class Registry {
                 ? this.parseCatalogManifest(read.success)
                 : null;
             // The root is authoritative, so attempt its deletion even when the
-            // best-effort read needed for physical chunk cleanup failed.
-            yield* storageDelete(this.catalogKey(id));
-            let firstError;
-            for (let index = 0; manifest && index < manifest.chunkCount; index++) {
-                const deleted = yield* Effect.result(storageDelete(this.catalogChunkKey(id, manifest.revision, index)));
-                if (Result.isFailure(deleted))
-                    firstError ??= deleted;
-            }
+            // best-effort read needed for physical chunk cleanup failed. It need
+            // not land first: a reader that finds the root but not a chunk has an
+            // incomplete catalog, which is never served, and an eventually
+            // consistent store could show it that way whatever the order.
+            const keys = [
+                this.catalogKey(id),
+                ...Array.from({ length: manifest?.chunkCount ?? 0 }, (_, index) => this.catalogChunkKey(id, manifest.revision, index)),
+            ];
+            const deleted = yield* forEachChunk(keys, (key) => storageDelete(key));
             if (Result.isFailure(read))
                 return yield* Effect.fail(read.failure);
-            if (firstError)
-                return yield* Effect.fail(firstError.failure);
+            const failed = deleted.find(Result.isFailure);
+            if (failed)
+                return yield* Effect.fail(failed.failure);
         });
     }
     catalogGeneration(id) {
@@ -811,7 +829,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 +844,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 +857,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 +891,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 +980,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 +1020,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 +1034,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 +1044,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 +1168,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 +1192,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 +1333,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 +1355,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]);