@zackbart/connecta 0.41.0 → 0.42.0

package/dist/catalog-service.js

@@ -4,19 +4,21 @@ 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 { readProgramRefuses } from "./tool-safety.js";
 import { withAuthorizationHandoffEffect } from "./authorization-handoff.js";
-import { carryCatalogFreshness, catalogIsFresh, catalogGenerationFor } from "./catalog-freshness.js";
+import { carryCatalogFreshness, catalogGenerationFor, catalogIsFresh, catalogStaleness, markCatalogStale, } 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 { prepareLexicalCatalog, carryLexicalCatalog, compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, typescriptSignature, } from "./catalog.js";
+import { Effect, Result, Semaphore } from "effect";
+import { prepareLexicalCatalog, carryLexicalCatalog, compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, discoverySummary, vocabularyScore, 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";
-import { runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { detach, runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { registryProgram } from "./runtime/registry.js";
 import { SharedRead } from "./runtime/shared-read.js";
+import { closeScope } from "./runtime/connector-scope.js";
 import { duringViewEffect } from "./runtime/call.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, UNSCOPED_DISCOVERY_BUDGET_MS, UNSCOPED_PROBE_TIMEOUT_MS, } from "./timeout.js";
 import { claimDiscoveryProbe, readDiscoveryHealth, settleDiscoveryHealth, } from "./discovery-health.js";
@@ -24,6 +26,27 @@ 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;
+/** Cached reads running at once in one discovery. Storage only, so they never wait for a probe slot. */
+const CATALOG_PEEK_CONCURRENCY = 16;
+/** The longest a stale catalog's read holds up a finished probe, and the least any peek gets. */
+const STALE_READ_TIMEOUT_MS = 1_000;
+/**
+ * One deferred refresh's whole tail, from being scheduled to the end of its
+ * cleanup: queueing, claim, listing, settlement and close. Inside the 30 seconds
+ * Workers keeps `waitUntil` alive.
+ */
+const CATALOG_REFRESH_TIMEOUT_MS = 20_000;
+/** The end of that tail no listing may use: the record's settlement, then connector cleanup. */
+const REFRESH_SETTLE_MS = 1_000;
+const REFRESH_CLOSE_MS = 2_000;
+/**
+ * Failures that say the connector did not answer, so its last complete catalog
+ * can stand in for the listing. Auth and permission failures, refusals and
+ * malformed catalogs are answers, and stay failures.
+ */
+const STALE_LISTING_CODES = new Set(["timeout", "unavailable", "rate_limited"]);
+/** A retryable downstream failure (HTTP 502, 503 or 504); a refusal under this code is not retryable. */
+const staleListingAllowed = (code, retryable) => STALE_LISTING_CODES.has(code) || (code === "connector_call_failed" && retryable);
 const lexicalStores = new WeakMap();
 let nextLexicalStore = 0;
 /** How long a probe claim outlives its request's discovery budget, for settlement and clock skew. */
@@ -38,10 +61,12 @@ class DiscoverySkipped extends Error {
         this.retryAfterMs = retryAfterMs;
     }
 }
-export const DEFAULT_SEARCH_LIMIT = 8;
+const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
 export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
+/** UTF-8 bytes of full tool purposes one describe call returns; fallback summaries have their own bound. */
+export const MAX_DESCRIBE_DESCRIPTION_BYTES = 32 * 1024;
 const MAX_QUERY_TERMS = 8;
 const MAX_QUERY_TERM_LENGTH = 64;
 /**
@@ -268,6 +293,23 @@ function schemaKeyMetadata(input, output) {
         ...(outputKeys && outputKeys.properties.length > 0 ? { outputKeys: outputKeys.properties } : {}),
     };
 }
+/** Fixed text and typed facts only: nothing here comes from the connector. */
+function staleCatalogFailure(connector, stale) {
+    // A downstream that asked for time gets it: asking now would only be refused again.
+    const advice = stale.code === "rate_limited" || stale.downstreamWait
+        ? `Wait${stale.retryAfterMs === undefined ? "" : ` ${stale.retryAfterMs} ms`} before searching with connector "${connector}".`
+        : `Search with connector "${connector}" to try it now.`;
+    return {
+        connector,
+        code: stale.code,
+        message: `Connector "${connector}" did not answer discovery (${stale.code}), so its tools are listed from its last complete catalog. Calls still check the live catalog. ${advice}`,
+        retryable: true,
+        ...(stale.retryAfterMs === undefined ? {} : { retryAfterMs: stale.retryAfterMs }),
+        stale: true,
+        ageMs: stale.ageMs,
+    };
+}
+const staleListedText = (count) => `${count} connector catalog${count === 1 ? " is" : "s are"} listed from an older complete catalog; inspect catalogErrors.`;
 const stringListSchema = { type: "array", items: { type: "string" } };
 const STRING = { type: "string" };
 // The reasons enum is stated once under `$defs` and referenced from each field.
@@ -281,6 +323,8 @@ const catalogFailureProperties = {
     message: { type: "string" },
     retryable: { type: "boolean" },
     retryAfterMs: { type: "integer", minimum: 0 },
+    stale: { const: true },
+    ageMs: { type: "integer" },
     connector: { type: "string" },
     recovery: { enum: ["oauth", "operator_config", "unavailable"] },
     status: { const: "auth_required" },
@@ -309,12 +353,12 @@ const catalogFailureProperties = {
     // additive action advice compact in the always-loaded search schema.
     nextAction: {
         type: "object",
-        anyOf: [{ required: ["tool"] }, { required: ["action"] }],
+        anyOf: [{ required: ["url"] }, { required: ["tool"] }, { required: ["action"] }],
         properties: {
+            url: STRING,
             tool: { const: "authorize_connector" },
             action: { enum: ["contact_operator", "inspect_capabilities"] },
             purpose: STRING,
-            operatorHandoff: STRING,
             arguments: { type: "object", properties: { connector: STRING } },
         },
     },
@@ -322,10 +366,10 @@ const catalogFailureProperties = {
 /** The one typed failure (and auth handoff) both failure fields reference. */
 const FAILURE_REF = { $ref: "#/$defs/failure" };
 /**
- * The outputSchema contract for either search adapter. Guest API registration
- * can reuse this value instead of maintaining a second page definition.
- * Every failure field references one local `$defs` entry, so the typed auth
- * handoff is advertised once instead of once per field.
+ * The full page contract for either search adapter, which the server validates
+ * every page against. `tools/list` advertises the open summary in `meta-output.ts`
+ * instead. Every failure field references one local `$defs` entry, so the typed
+ * auth handoff is stated once.
  */
 export const CATALOG_SEARCH_RESULT_SCHEMA = {
     type: "object",
@@ -364,6 +408,7 @@ export const CATALOG_SEARCH_RESULT_SCHEMA = {
                     name: { type: "string" },
                     address: { type: "string" },
                     description: { type: "string" },
+                    descriptionTruncated: { const: true },
                     inputSchema: {},
                     outputSchema: {},
                     signature: { type: "string" },
@@ -451,6 +496,7 @@ export class CatalogService {
     searchRoute;
     requestSignal;
     readOnly;
+    markUncallableWrites;
     // The request-scoped catalog cache: one shared read per connector asked
     // about, started by the first asker and joined by every later one. A
     // success stays while its in-process invalidation fence matches, so a search
@@ -475,6 +521,13 @@ export class CatalogService {
     // current by its own probes, so repeated searches read no storage.
     health = new Map();
     routes;
+    // This request's peeks: a stale listing is kept here, never in `catalogs`,
+    // because resolve reads `catalogs` and a call must never resolve through it.
+    peeks = new Map();
+    // At most one deferred refresh per connector per request.
+    refreshed = new Set();
+    refreshSlots;
+    unscopedProbeTimeoutMs;
     constructor(registry, baseUrl, options = {}) {
         this.registry = registry;
         this.baseUrl = baseUrl;
@@ -483,11 +536,13 @@ export class CatalogService {
         this.requestScope = options.requestScope ?? {};
         this.probeTimeoutMs = normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
         this.discoveryBudgetMs = normalizeTimeoutMs(options.discoveryBudgetMs) ?? UNSCOPED_DISCOVERY_BUDGET_MS;
+        this.unscopedProbeTimeoutMs = normalizeTimeoutMs(options.unscopedProbeTimeoutMs) ?? UNSCOPED_PROBE_TIMEOUT_MS;
         this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
         this.searchRoute = options.searchRoute ?? "search_tools";
         this.requestSignal = options.requestSignal;
         this.defer = options.defer;
         this.readOnly = options.readOnly === true;
+        this.markUncallableWrites = options.markUncallableWrites === true;
     }
     /**
      * Send a caller back to discovery through the surface it can actually reach.
@@ -571,10 +626,112 @@ export class CatalogService {
         if (!view) {
             view = toolsForSafety(readOnly ? tools.filter((tool) => tool.classification === "read") : tools, safety ?? "all");
             carryLexicalCatalog(tools, view);
+            const stale = catalogStaleness(tools);
+            if (stale)
+                markCatalogStale(view, stale);
             views.set(key, view);
         }
         return view;
     }
+    // One connector's cached catalog, read at most once per request and identity.
+    // Storage only (INV-10), under its own deadline and the request's signal. A
+    // read that fails or runs out of time is a miss: discovery never fails on it.
+    peek(id, timeoutMs) {
+        return withDeadlineEffect((signal) => this.joinPeek(id, signal), {
+            ...(this.requestSignal ? { signal: this.requestSignal } : {}),
+            timeoutMs,
+            timeoutError: new ConnectorCallError("timeout", `catalog peek of "${id}" timed out`),
+        }).pipe(Effect.catchCause(() => Effect.succeed(undefined)));
+    }
+    joinPeek(id, signal) {
+        return Effect.suspend(() => {
+            const identity = retainedCatalogIdentity(this.registry.contextFor(id, this.baseUrl, this.requestScope));
+            let retained = this.peeks.get(id);
+            if (!retained || retained.identity !== identity) {
+                const started = new SharedRead((signal) => registryProgram(this.registry, "peekCatalog", id, this.baseUrl, this.requestScope, { signal }).pipe(Effect.map((peek) => {
+                    if (!peek)
+                        return undefined;
+                    const connector = this.registry.getConnector(id);
+                    for (const tool of peek.tools)
+                        routeToolInPlace(connector, tool, this.routes);
+                    return peek;
+                })), (succeeded) => {
+                    if (!succeeded && this.peeks.get(id)?.read === started)
+                        this.peeks.delete(id);
+                }, this.requestScope);
+                retained = { identity, read: started };
+                this.peeks.set(id, retained);
+            }
+            return retained.read.join(signal);
+        });
+    }
+    /**
+     * A peek as this discovery's answer for a connector that did not. Whatever a
+     * listing would hide stays hidden: the view is filtered like a live one, and
+     * the mark is what makes search and native listing report it.
+     */
+    staleListing(id, peek, includeWrites, failure) {
+        const source = markCatalogStale(peek.tools.map((tool) => cloneTool(tool)), { ...failure, ageMs: Math.max(0, Date.now() - peek.fetchedAt) });
+        return this.searchView(id, source, includeWrites, "all");
+    }
+    /**
+     * Refresh a catalog whose probe ran out of time, in a request scope of its
+     * own under `defer`, the runtime's tail. Nothing here shares this request's
+     * signal, transports or reads, so nothing request-bound outlives the request
+     * (INV-7); the refresh owns its transport and closes it within its own
+     * deadline, which Workers `waitUntil` covers. It lists like any discovery:
+     * a partial walk publishes nothing (INV-8) and no authorization starts
+     * (INV-10). The health record's lease keeps other requests from starting
+     * another while this one runs, and its result settles that record.
+     *
+     * Every step answers to one clock, started as it is scheduled, so queueing,
+     * a slow claim and a slow settlement spend the same tail. Waiting on storage
+     * stops at its limit; a write already sent is left to land or to lapse.
+     */
+    refreshLater(id, slot, spentMs) {
+        const tailMs = Math.min(this.probeTimeoutMs, CATALOG_REFRESH_TIMEOUT_MS);
+        const closeMs = Math.min(REFRESH_CLOSE_MS, Math.floor(tailMs / 4));
+        const settleMs = Math.min(REFRESH_SETTLE_MS, Math.floor(tailMs / 4));
+        if (!this.defer || this.refreshed.has(id) || tailMs - closeMs - settleMs <= spentMs)
+            return;
+        this.refreshed.add(id);
+        const scope = {};
+        const connector = this.registry.getConnector(id);
+        const endsAt = Date.now() + tailMs;
+        const listEnd = endsAt - closeMs - settleMs;
+        const timeoutError = new ConnectorCallError("timeout", `catalog refresh of "${id}" timed out`);
+        const until = (limit, storage, otherwise) => Effect.suspend(() => limit <= Date.now()
+            ? Effect.succeed(otherwise)
+            : withDeadlineEffect(() => storage, { timeoutMs: limit - Date.now(), timeoutError }).pipe(Effect.catchCause(() => Effect.succeed(otherwise))));
+        const refresh = Effect.gen({ self: this }, function* () {
+            const claimed = yield* until(listEnd, claimDiscoveryProbe(slot, endsAt + CLAIM_MARGIN_MS), false);
+            // Only what the claim left: a claim that spent it all dispatches nothing,
+            // and its lease lapses by itself.
+            const timeoutMs = listEnd - Date.now();
+            if (!claimed || !connector || timeoutMs <= 0)
+                return;
+            const started = Date.now();
+            const result = yield* Effect.result(withDeadlineEffect((signal) => registryProgram(this.registry, "getTools", id, this.baseUrl, scope, {
+                signal,
+                timeoutMs,
+                ...(this.defer ? { defer: this.defer } : {}),
+            }), { timeoutMs, timeoutError }));
+            yield* until(endsAt - closeMs, settleDiscoveryHealth(slot, Result.isSuccess(result)
+                ? { ok: true }
+                : {
+                    ok: false,
+                    failure: result.failure,
+                    timedOut: result.failure === timeoutError,
+                    elapsedMs: Date.now() - started,
+                }), undefined);
+        });
+        this.refreshSlots ??= Semaphore.makeUnsafe(this.concurrency);
+        detach(this.refreshSlots
+            .withPermits(1)(refresh)
+            .pipe(Effect.ensuring(Effect.suspend(() => connector
+            ? closeScope(connector, this.registry.contextFor(id, this.baseUrl, scope), this.defer)
+            : Effect.void))), { waitUntil: this.defer });
+    }
     // Every named catalog under its own probe deadline, `concurrency` at a time,
     // each settling in its input slot: an unavailable catalog is a Failure
     // there, not a failed discovery. `route` names the surface in a timeout.
@@ -594,11 +751,22 @@ export class CatalogService {
     // it, then runs to its end. A lapsed record is claimed as its probe is
     // dispatched, leased to the end of this budget plus a margin.
     // Caller cancellation and a probe the budget cut short leave health as it was.
-    searchCatalogs(ids, scoped) {
+    //
+    // Unscoped search and a native listing also serve a connector's last complete
+    // catalog, marked stale, when it did not answer in time. A cached or authored
+    // catalog is read without a probe slot, so only a connector that must actually
+    // be asked waits for one. A native listing has no budget and gives a connector
+    // with nothing to fall back on its full deadline, since it would otherwise vanish.
+    searchCatalogs(ids, mode, includeWrites = false) {
         return Effect.gen({ self: this }, function* () {
-            const deadline = scoped ? this.probeTimeoutMs : Math.min(this.probeTimeoutMs, UNSCOPED_PROBE_TIMEOUT_MS);
-            const budgetEnd = scoped ? Infinity : Date.now() + this.discoveryBudgetMs;
-            const settleReserve = scoped ? 0 : Math.min(SETTLE_RESERVE_MS, Math.floor(this.discoveryBudgetMs / 10));
+            const scoped = mode === "scoped";
+            const shortDeadline = Math.min(this.probeTimeoutMs, this.unscopedProbeTimeoutMs);
+            const budgeted = mode === "unscoped";
+            const route = mode === "native" ? "tools/list" : this.searchRoute;
+            const budgetEnd = budgeted ? Date.now() + this.discoveryBudgetMs : Infinity;
+            const settleReserve = budgeted ? Math.min(SETTLE_RESERVE_MS, Math.floor(this.discoveryBudgetMs / 10)) : 0;
+            const slots = yield* Semaphore.make(this.concurrency);
+            const peekSlots = yield* Semaphore.make(CATALOG_PEEK_CONCURRENCY);
             // Health storage starts only while budget remains and the caller is
             // here; running out is not a failure, health is then unknown. Once
             // started, an operation is awaited to its end, never raced or detached:
@@ -630,60 +798,142 @@ export class CatalogService {
                 });
             };
             const probeOne = (id) => Effect.gen({ self: this }, function* () {
-                const verdict = scoped ? undefined : this.health.get(id);
-                const skip = verdict?.skip;
-                if (skip && skip.retryAt > Date.now())
+                const connector = this.registry.getConnector(id);
+                // An authored catalog answers from configuration: no slot, no budget, no health.
+                if (!scoped && connector?.staticTools)
                     return {
                         id,
-                        result: Result.fail(new DiscoverySkipped(skip.code, Math.ceil(skip.retryAt - Date.now()))),
+                        result: yield* Effect.result(this.probe(id, includeWrites, this.probeTimeoutMs, new ConnectorCallError("timeout", `${route} probe of "${id}" timed out after ${this.probeTimeoutMs}ms`))),
                     };
+                // Storage only, so a connector with a current catalog never queues
+                // behind one that must be asked. A custom connector is always listed
+                // anew and starts no cache I/O here; it peeks only if that fails.
+                let peek = !scoped && connector?.peekCatalog && Date.now() < budgetEnd
+                    ? yield* peekSlots.withPermits(1)(this.peek(id, Math.max(shortDeadline, STALE_READ_TIMEOUT_MS)))
+                    : undefined;
+                const verdict = scoped ? undefined : this.health.get(id);
+                const skip = verdict?.skip;
+                // A peek is only as good as the moment it was read. After any wait for
+                // a slot or a probe it is read again, through every acceptance fence,
+                // so an invalidation, a rotated credential or a refusal in the
+                // meantime retires it, in this isolate or another.
+                const staleAnswer = (failure, waited = true) => Effect.gen({ self: this }, function* () {
+                    // Caller cancellation is not a connector that failed to answer.
+                    if (scoped || this.requestSignal?.aborted)
+                        return undefined;
+                    if (waited)
+                        this.peeks.delete(id);
+                    if (waited || !peek)
+                        peek = yield* this.peek(id, STALE_READ_TIMEOUT_MS);
+                    return peek ? this.staleListing(id, peek, includeWrites, failure) : undefined;
+                });
+                if (skip && skip.retryAt > Date.now() && !peek?.fresh) {
+                    const retryAfterMs = Math.ceil(skip.retryAt - Date.now());
+                    // Discovery health records only timeouts and retryable failures.
+                    if (staleListingAllowed(skip.code, true)) {
+                        const stale = yield* staleAnswer({ code: skip.code, retryAfterMs }, false);
+                        if (stale)
+                            return { id, result: Result.succeed(stale) };
+                    }
+                    // A native listing has no search to come back through: it still asks.
+                    if (mode !== "native")
+                        return { id, result: Result.fail(new DiscoverySkipped(skip.code, retryAfterMs)) };
+                }
+                // With something to fall back on a short deadline is enough. Without
+                // it, a native listing waits its full deadline, as the connector
+                // would otherwise be absent; unscoped search keeps its short one.
+                const deadline = scoped || (mode === "native" && !peek) ? this.probeTimeoutMs : shortDeadline;
                 const timeoutFor = (remaining) => {
                     const budgetCut = remaining < deadline;
                     return {
                         budgetCut,
                         timeoutMs: budgetCut ? remaining : deadline,
                         timeoutError: budgetCut
-                            ? new ConnectorCallError("timeout", `${this.searchRoute} stopped probing "${id}" at the ${this.discoveryBudgetMs}ms discovery budget`)
-                            : new ConnectorCallError("timeout", `${this.searchRoute} probe of "${id}" timed out after ${deadline}ms`),
+                            ? new ConnectorCallError("timeout", `${route} stopped probing "${id}" at the ${this.discoveryBudgetMs}ms discovery budget`)
+                            : new ConnectorCallError("timeout", `${route} probe of "${id}" timed out after ${deadline}ms`),
                     };
                 };
-                let plan = timeoutFor(Math.ceil(budgetEnd - settleReserve - Date.now()));
-                if (plan.timeoutMs <= 0)
-                    return { id, result: Result.fail(plan.timeoutError) };
-                // A lapsed record: claim this probe now, as it is dispatched. The
-                // lease runs to an absolute time, the end of this request's
-                // discovery budget plus a margin, so however long the claim write
-                // takes, the probe the budget still allows ends inside it.
-                if (skip && verdict?.slot) {
-                    const leaseUntil = budgetEnd + CLAIM_MARGIN_MS;
-                    const claimed = yield* withinBudget(claimDiscoveryProbe(verdict.slot, leaseUntil), false);
-                    if (!claimed) {
-                        this.health.set(id, { slot: verdict.slot, skip: { code: skip.code, retryAt: leaseUntil } });
-                        return {
-                            id,
-                            result: Result.fail(new DiscoverySkipped(skip.code, Math.max(1, Math.ceil(leaseUntil - Date.now())))),
-                        };
-                    }
-                    this.health.set(id, { slot: verdict.slot });
-                    plan = timeoutFor(Math.ceil(budgetEnd - settleReserve - Date.now()));
+                const asked = Effect.gen({ self: this }, function* () {
+                    // A current catalog is a storage read in hand, not a probe the budget has to bound.
+                    const remaining = () => (peek?.fresh ? Infinity : Math.ceil(budgetEnd - settleReserve - Date.now()));
+                    let plan = timeoutFor(remaining());
                     if (plan.timeoutMs <= 0)
-                        return { id, result: Result.fail(plan.timeoutError) };
+                        return { result: Result.fail(plan.timeoutError), plan };
+                    // A lapsed record: claim this probe now, as it is dispatched. The
+                    // lease runs to an absolute time, the end of this request's
+                    // discovery budget plus a margin, so however long the claim write
+                    // takes, the probe the budget still allows ends inside it.
+                    if (budgeted && skip && verdict?.slot && !peek?.fresh) {
+                        const leaseUntil = budgetEnd + CLAIM_MARGIN_MS;
+                        const claimed = yield* withinBudget(claimDiscoveryProbe(verdict.slot, leaseUntil), false);
+                        if (!claimed) {
+                            this.health.set(id, { slot: verdict.slot, skip: { code: skip.code, retryAt: leaseUntil } });
+                            return {
+                                result: Result.fail(new DiscoverySkipped(skip.code, Math.max(1, Math.ceil(leaseUntil - Date.now())))),
+                                plan,
+                            };
+                        }
+                        this.health.set(id, { slot: verdict.slot });
+                        plan = timeoutFor(remaining());
+                        if (plan.timeoutMs <= 0)
+                            return { result: Result.fail(plan.timeoutError), plan };
+                    }
+                    const started = Date.now();
+                    const result = yield* Effect.result(this.probe(id, includeWrites, plan.timeoutMs, plan.timeoutError));
+                    // Elapsed time is this probe's own, measured as it settles.
+                    return { result, plan, elapsedMs: Date.now() - started };
+                });
+                // A current catalog's read takes no slot: it hands the peek to the listing.
+                const { result, plan, elapsedMs } = (peek?.fresh ? yield* asked : yield* slots.withPermits(1)(asked));
+                if (elapsedMs === undefined) {
+                    if (Result.isFailure(result)) {
+                        const failure = result.failure;
+                        const stale = yield* staleAnswer(failure instanceof DiscoverySkipped
+                            ? { code: failure.code, retryAfterMs: failure.retryAfterMs }
+                            : { code: "timeout" });
+                        if (stale)
+                            return { id, result: Result.succeed(stale) };
+                    }
+                    return { id, result };
                 }
-                const started = Date.now();
-                const result = yield* Effect.result(this.probe(id, false, plan.timeoutMs, plan.timeoutError));
-                // Elapsed time is this probe's own, measured as it settles.
-                const elapsedMs = Date.now() - started;
                 const outcome = plan.budgetCut && Result.isFailure(result) && result.failure === plan.timeoutError
                     ? { id, result }
                     : { id, result, settle: { timeoutError: plan.timeoutError, elapsedMs } };
                 if (scoped)
                     return outcome;
-                yield* settleOne(outcome);
+                // A catalog served from cache says nothing about a recorded failure.
+                if (!(skip && peek?.fresh))
+                    yield* settleOne(outcome);
+                if (Result.isSuccess(result))
+                    return { id, result };
+                const failure = result.failure;
+                // A probe that ran out of time: its abort left nothing cached, so ask
+                // again past this request, under the longer deadline the runtime's tail allows.
+                if (failure === plan.timeoutError && !plan.budgetCut) {
+                    // Only the request whose settlement recorded this: anyone else lost
+                    // to a record that already has an owner, or wrote nothing at all.
+                    const recorded = this.health.get(id);
+                    if (recorded?.slot && recorded.recorded)
+                        this.refreshLater(id, recorded.slot, plan.timeoutMs);
+                }
+                const classified = failure === plan.timeoutError
+                    ? { code: "timeout", retryable: true }
+                    : classifyCallError(failure, "catalog_lookup_failed");
+                if (staleListingAllowed(classified.code, classified.retryable)) {
+                    const stale = yield* staleAnswer({
+                        code: classified.code,
+                        ...(classified.retryAfterMs === undefined
+                            ? {}
+                            : { retryAfterMs: classified.retryAfterMs, downstreamWait: true }),
+                    });
+                    if (stale)
+                        return { id, result: Result.succeed(stale) };
+                }
                 return { id, result };
             });
             if (!scoped) {
                 yield* readHealth;
-                const probed = yield* Effect.forEach(ids, probeOne, { concurrency: this.concurrency });
+                const probed = yield* Effect.forEach(ids, probeOne, { concurrency: "unbounded" });
                 return probed.map((outcome) => outcome.result);
             }
             const [, probed] = yield* Effect.all([readHealth, Effect.forEach(ids, probeOne, { concurrency: this.concurrency })], { concurrency: 2 });
@@ -700,13 +950,20 @@ export class CatalogService {
      * settles on its own, so one unavailable connector is an `error` entry
      * beside the others rather than a failed listing.
      */
-    listCatalogs(includeWrites = false, connectors = this.registry.listConnectors()) {
-        return runEdge(this.listCatalogsEffect(includeWrites, connectors));
+    listCatalogs(includeWrites = false, connectors = this.registry.listConnectors(), allowStale = false) {
+        return runEdge(this.listCatalogsEffect(includeWrites, connectors, allowStale));
     }
-    listCatalogsEffect(includeWrites = false, connectors) {
+    /**
+     * `allowStale` is for a listing only. Resolving a native call must not pass
+     * it: uniqueness and authority come from a catalog that answered.
+     */
+    listCatalogsEffect(includeWrites = false, connectors, allowStale = false) {
         return duringViewEffect({ requestScope: this.requestScope, signal: this.requestSignal }, () => Effect.suspend(() => {
             const visible = connectors ?? this.registry.listConnectors();
-            return Effect.map(this.discoveryCatalogs(visible.map((connector) => connector.id), "tools/list", includeWrites), (results) => results.map((result, index) => {
+            const ids = visible.map((connector) => connector.id);
+            return Effect.map(allowStale
+                ? this.searchCatalogs(ids, "native", includeWrites)
+                : this.discoveryCatalogs(ids, "tools/list", includeWrites), (results) => results.map((result, index) => {
                 const connector = visible[index];
                 return Result.isSuccess(result)
                     ? { connector, tools: carryCatalogFreshness(result.success, result.success.map(cloneTool)) }
@@ -741,7 +998,10 @@ export class CatalogService {
             cause,
         };
     }
-    unknownToolFailure(toolName, connector, started) {
+    unknownToolFailure(toolName, connector, started, tools) {
+        // The same view discovery serves: a read-only scope never names a write here.
+        const visible = this.readOnly || connector.readOnly === true ? tools.filter((tool) => tool.classification === "read") : tools;
+        const suggestions = hasControlCharacters(toolName) ? [] : describeSuggestions(connector.id, toolName, visible);
         return {
             ok: false,
             error: {
@@ -749,6 +1009,7 @@ export class CatalogService {
                     ? `Unknown tool on connector "${connector.id}"`
                     : `Unknown tool "${boundedEchoText(toolName)}" on connector "${connector.id}"`),
                 nextAction: this.searchRecovery({ query: hasControlCharacters(toolName) ? "" : recoveryQuery(toolName), connector: connector.id }, "Find the connector's current canonical tool address."),
+                ...(suggestions.length > 0 ? { suggestions } : {}),
             },
             catalogMs: Date.now() - started,
             connector,
@@ -774,7 +1035,7 @@ export class CatalogService {
                 onSuccess: (tools) => {
                     const definition = tools.find((tool) => tool.name === toolName);
                     if (!definition) {
-                        return this.unknownToolFailure(toolName, connector, started);
+                        return this.unknownToolFailure(toolName, connector, started, tools);
                     }
                     return {
                         ok: true,
@@ -888,7 +1149,7 @@ export class CatalogService {
                 : undefined;
             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 catalogs = yield* this.searchCatalogs(connectors.map((connector) => connector.id), args.connector !== undefined ? "scoped" : "unscoped");
             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);
@@ -978,21 +1239,36 @@ export class CatalogService {
                                         order: original.success.indexOf(tool),
                                         exactName: false,
                                         matchedTermCount: toolTermCount,
+                                        headTerms: [],
+                                        nameTerms: [],
+                                        namesDistinctiveTerm: false,
                                     });
                             }
                         }
+                        // A tool on the named connector need not repeat that connector's name.
+                        const statedTerms = args.connector || exactConnector ? toolTerms.filter((term) => !connectorTerms.has(term)) : toolTerms;
+                        const requiredTerms = statedTerms.length > 0 ? statedTerms : toolTerms;
                         for (const ranked of rankedTools) {
+                            const complete = isBrowse || requiredTerms.every((term) => ranked.headTerms.includes(term));
+                            const vocabulary = vocabularyTools.has(ranked.tool);
+                            // Discovery pointers follow every tool that answers lexically.
+                            const vocabularyRank = complete ? 0 : vocabularyScore(requiredTerms, statistics);
                             collected.push({
                                 connector,
                                 tool: ranked.tool,
-                                score: vocabularyTools.has(ranked.tool) && !ranked.exactName ? 0 : ranked.score,
+                                score: vocabulary && !ranked.exactName ? vocabularyRank : ranked.score,
                                 order: orderBase + ranked.order,
-                                exactName: ranked.exactName,
+                                // A tool named just `search` is not what a longer query containing that verb names.
+                                exactName: ranked.exactName && !ACTION_WORD.test(ranked.tool.name.toLowerCase()),
                                 exactLookup: rawPhrase === lexicalQueryTerms(ranked.tool.name).join(" ") ||
                                     rawPhrase === lexicalQueryTerms(`${connector.id}.${ranked.tool.name}`).join(" "),
                                 connectorRank,
                                 matchedTermCount: vocabularyTools.has(ranked.tool) ? toolTermCount : ranked.matchedTermCount,
-                                complete: isBrowse || vocabularyTools.has(ranked.tool) || ranked.matchedTermCount === toolTermCount,
+                                complete,
+                                covered: isBrowse || vocabulary || ranked.matchedTermCount === toolTermCount,
+                                vocabulary,
+                                namesSubject: ranked.nameTerms.some((term) => !ACTION_WORD.test(term) && !connectorTerms.has(term)),
+                                namesDistinctiveTerm: ranked.namesDistinctiveTerm,
                             });
                         }
                     }
@@ -1005,12 +1281,13 @@ export class CatalogService {
             // unrelated zero-score match, with no coverage to explain the result.
             const rankedMatches = unsearchableQuery ? [] : collectMatches(isBrowse ? "all" : "partial");
             const completeMatchCount = rankedMatches.filter((match) => match.complete).length;
-            matches.push(...rankedMatches.filter((match) => match.complete ||
+            matches.push(...rankedMatches.filter((match) => match.covered ||
+                match.namesDistinctiveTerm ||
                 completeMatchCount === 0 ||
                 match.exactName ||
                 match.connectorRank > 0 ||
                 match.matchedTermCount >= 2));
-            if (!isBrowse && !unsearchableQuery && completeMatchCount === 0) {
+            if (!isBrowse && !unsearchableQuery && !rankedMatches.some((match) => match.covered)) {
                 matchMode = "partial";
             }
             // A read-intent verb leads the query once connector names are set aside.
@@ -1021,13 +1298,15 @@ export class CatalogService {
             // longer name such as get_issue_status cannot beat an exact get_issue
             // merely because its description repeats rare query terms. Within a
             // tier, a read-intent query puts reads before writes.
+            // A hatch with a matching operation stays above partial matches, as does a
+            // tool that names the query's subject and states the rest in its tail. A
+            // tail alone earns no tier: long prose can mention anything.
+            const tier = (match) => match.complete || match.exactName ? 2 : match.vocabulary || (match.covered && match.namesSubject) ? 1 : 0;
             matches.sort((a, b) => {
-                const aFirstTier = a.complete || a.exactName;
-                const bFirstTier = b.complete || b.exactName;
                 return (Number(b.exactLookup) - Number(a.exactLookup) ||
                     Number(b.exactName) - Number(a.exactName) ||
                     b.connectorRank - a.connectorRank ||
-                    Number(bFirstTier) - Number(aFirstTier) ||
+                    tier(b) - tier(a) ||
                     readFirst(b) - readFirst(a) ||
                     b.score - a.score ||
                     a.order - b.order);
@@ -1056,7 +1335,10 @@ export class CatalogService {
                         ? renderSearchSchema(output.schema, schemaFormat)
                         : undefined;
                 const schemaKeys = withSchemas && args.includeSchemaKeys ? schemaKeyMetadata(input, output.schema) : undefined;
-                const description = summarizeDiscoveryDescription(match.tool.description, args.fullDescriptions === true);
+                const summary = match.tool.description && args.fullDescriptions !== true
+                    ? discoverySummary(match.tool.description)
+                    : undefined;
+                const description = summary ? summary.text : match.tool.description || undefined;
                 const requiredReasons = guideRequiredReasons(match.connector, match.tool, renderedInput?.truncated === true || renderedOutput?.truncated === true);
                 const guideSummary = connectorGuideSummary(match.connector);
                 return {
@@ -1071,6 +1353,7 @@ export class CatalogService {
                         name: match.tool.name,
                         address: `${match.connector.id}.${match.tool.name}`,
                         ...(description !== undefined ? { description } : {}),
+                        ...(summary?.truncated ? { descriptionTruncated: true } : {}),
                         ...(schemaFormat
                             ? {
                                 inputSchema: renderedInput?.schema,
@@ -1095,6 +1378,7 @@ export class CatalogService {
                         ...(schemaKeys?.outputKeys && !renderedOutput?.truncated ? { outputKeys: schemaKeys.outputKeys } : {}),
                         ...(match.tool.annotations ? { annotations: match.tool.annotations } : {}),
                         classification: match.tool.classification,
+                        ...(this.markUncallableWrites && readProgramRefuses(match.tool) ? { callable: false } : {}),
                         ...(requiredReasons
                             ? {
                                 guideRequired: true,
@@ -1161,14 +1445,19 @@ export class CatalogService {
                 }
             }
             const unavailableCatalogs = catalogs.filter(Result.isFailure).length;
-            const catalogErrors = (yield* Effect.forEach(catalogs, (catalog, index) => Result.isSuccess(catalog)
-                ? Effect.succeed([])
-                : this.catalogFailure(connectors[index], catalog.failure).pipe(Effect.map((error) => [error])), { concurrency: "unbounded" })).flat();
+            const staleCatalogs = catalogs.filter((catalog) => Result.isSuccess(catalog) && catalogStaleness(catalog.success)).length;
+            const catalogErrors = (yield* Effect.forEach(catalogs, (catalog, index) => {
+                if (Result.isFailure(catalog))
+                    return this.catalogFailure(connectors[index], catalog.failure).pipe(Effect.map((error) => [error]));
+                const stale = catalogStaleness(catalog.success);
+                return Effect.succeed(stale ? [staleCatalogFailure(connectors[index].id, stale)] : []);
+            }, { concurrency: "unbounded" })).flat();
             const needsAuth = (error) => error.code === "auth_required" ||
                 error.code === "downstream_oauth_required" ||
                 error.code === "provider_permission_denied";
             catalogErrors.sort((a, b) => Number(needsAuth(b)) - Number(needsAuth(a)));
-            const scopedFailure = args.connector ? catalogErrors[0] : undefined;
+            // A stale row beside listed tools is not this scoped search's failure.
+            const scopedFailure = args.connector ? catalogErrors.find((error) => !error.stale) : undefined;
             const scopedCatalogError = scopedFailure
                 ? scopedFailure.code === "auth_required" || scopedFailure.code === "downstream_oauth_required"
                     ? scopedFailure
@@ -1238,6 +1527,7 @@ export class CatalogService {
                     (unavailableCatalogs
                         ? ` ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable; inspect catalogErrors.`
                         : "") +
+                    (staleCatalogs ? ` ${staleListedText(staleCatalogs)}` : "") +
                     filterRecovery;
             // A scope that resolved to nothing is the same silence one step earlier in
             // the lookup: no connector resolved, so no catalog was even attempted, so
@@ -1272,7 +1562,7 @@ export class CatalogService {
                 }
                 if (queryTerms.length === 0) {
                     if (unavailableCatalogs === 0)
-                        return undefined;
+                        return staleCatalogs ? staleListedText(staleCatalogs) : undefined;
                     return scopedConnector
                         ? `Connector "${scopedConnector.id}" could not be browsed because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
                         : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Inspect catalogErrors for the typed reasons and recovery actions.`;
@@ -1291,8 +1581,10 @@ export class CatalogService {
                     if (identityGuidance || apiSearchGuidance)
                         return ([identityGuidance, apiSearchGuidance].filter(Boolean).join(" ") +
                             (apiSearchGuidance ? "" : filterRecovery));
+                    if (unavailableCatalogs === 0 && staleCatalogs)
+                        return `No matching ${safetyLabel}capability was found. ${staleListedText(staleCatalogs)} Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`;
                     return unavailableCatalogs === 0
-                        ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+                        ? `No ${safetyLabel}tool matched these terms. Try other terms, scope by connector, or browse with an empty query.${filterRecovery}`
                         : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`;
                 }
                 if (matchMode !== "partial")
@@ -1399,6 +1691,10 @@ export class CatalogService {
                     : undefined;
                 return [id, error];
             }), { concurrency: "unbounded" }));
+            // Full prose shares one budget in address order, so a large batch keeps its
+            // schemas and a repeated describe renders the same text. A fallback summary
+            // spends none of it: every entry keeps its purpose, within 480 bytes each.
+            let descriptionBytes = MAX_DESCRIBE_DESCRIPTION_BYTES;
             return resolved.map(({ address, resolved: addressResolution }) => {
                 if (!addressResolution) {
                     const message = `Unknown address "${boundedEchoText(address)}"`;
@@ -1451,7 +1747,12 @@ export class CatalogService {
                 const tool = cloneTool(selected);
                 const input = tool.inputSchema ?? { type: "object" };
                 const output = this.outputSchema(addressResolution.connector.id, tool);
-                const description = summarizeDescription(tool.description, args.fullDescriptions === true);
+                const bytes = tool.description ? encoder.encode(tool.description).length : 0;
+                const withinBudget = args.fullDescriptions === true || bytes <= descriptionBytes;
+                if (withinBudget)
+                    descriptionBytes -= bytes;
+                const summary = withinBudget || !tool.description ? undefined : discoverySummary(tool.description);
+                const description = summary ? summary.text : tool.description || undefined;
                 const signature = format === "typescript"
                     ? typescriptSignature(input, output.schema, {
                         observed: output.source === "observed",
@@ -1469,6 +1770,7 @@ export class CatalogService {
                     schemaFormat: format === "json" ? "json" : "text",
                     name: tool.name,
                     ...(description !== undefined ? { description } : {}),
+                    ...(summary?.truncated ? { descriptionTruncated: true } : {}),
                     ...(connectorGuide(addressResolution.connector)
                         ? {
                             guide: connectorSkillName(addressResolution.connector.id),
@@ -1492,6 +1794,7 @@ export class CatalogService {
                     ...(output.source ? { outputSchemaSource: output.source } : {}),
                     ...(tool.annotations ? { annotations: tool.annotations } : {}),
                     classification: tool.classification,
+                    ...(this.markUncallableWrites && readProgramRefuses(tool) ? { callable: false } : {}),
                 };
             });
         });