@zackbart/connecta 0.39.0 → 0.41.0

package/dist/guarded-transport.js

@@ -1,6 +1,8 @@
 // The plain runtime slot keeps the HTTP kit and Node sender off the root
 // and Worker graphs. /node installs its sender when listen() starts serving.
 import { ConnectorCallError } from "./errors.js";
+/** Internal request marker: only downstream-learned URL fetches set this. */
+export const learnedDestination = Symbol("connecta.learnedDestination");
 let owned;
 /** Runtime configuration, never request data. Returns the previous slot for isolated fixtures. */
 export function configureGuardedTransport(transport) {

package/dist/http/client.js

@@ -30,6 +30,12 @@ import { RedirectRefused, Refusal, RequestRefused, ResendRefused, ResponseTooLar
 import { Classification, Dispatches, IdempotencyKey, Ledger, RequestFacts, Secrets, Signal, WriteCapacity, reserveWrite, writeRequestKey, } from "./services.js";
 const decoder = new TextDecoder();
 const responseEntries = new WeakMap();
+// Private request identity for middleware observing a rejected response. Never
+// attach headers or body to the failure or its payload-free ledger entry.
+const failedRequests = new WeakMap();
+export function failedResponseRequest(failure) {
+    return failedRequests.get(failure);
+}
 /** The core's physical request, also available to direct HttpClient middleware. */
 export function responseRequest(response) {
     return responseEntries.get(response);
@@ -216,6 +222,7 @@ export function guardedClient(options) {
             const refused = (failure) => {
                 dispatch.failure = failure;
                 responseEntries.set(failure, entry);
+                failedRequests.set(failure, request);
                 return Effect.fail(failure);
             };
             const response = yield* Effect.tryPromise({

package/dist/http/hatch.js

@@ -1171,6 +1171,8 @@ export function hatch(options) {
         const send = options.binding
             ? options.binding.send(call(), sendOptions)
             : connection.sendPath(request, sendOptions);
+        // Both send paths share the binding result contract. Keep its optional
+        // metadata typed even when the plain HTTP branch omits those properties.
         const answer = yield* send.pipe(Effect.catch((failure) => Effect.gen(function* () {
             if (!key || args.idempotencyKey)
                 return yield* Effect.fail(failure);

package/dist/http/node-transport.js

@@ -1,9 +1,68 @@
 // Node-only: owned undici dispatcher and Node stream adapters, reached via /node.
+import { Resolver } from "node:dns/promises";
+import { learnedDestination } from "../guarded-transport.js";
+import { learnedUrlRefusal } from "../url-safety.js";
+import { OAuthRequestNotSentError } from "../auth/oauth-request-not-sent.js";
 import { Readable } from "node:stream";
 import { isIP } from "node:net";
 import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
 import { Client, ProxyAgent } from "undici";
 import { ConnectorCallError } from "../errors.js";
+/** Each lookup owns its DNS channels; cancellation closes them before returning. */
+async function resolveAddresses(hostname, signal) {
+    const resolver = new Resolver();
+    const cancel = () => resolver.cancel();
+    signal.throwIfAborted();
+    signal.addEventListener("abort", cancel, { once: true });
+    try {
+        const results = await Promise.allSettled([resolver.resolve4(hostname), resolver.resolve6(hostname)]);
+        signal.throwIfAborted();
+        for (const result of results) {
+            if (result.status === "rejected" && !["ENODATA", "ENOTFOUND"].includes(result.reason?.code))
+                throw result.reason;
+        }
+        return results.flatMap((result, index) => result.status === "fulfilled" ? result.value.map((address) => ({ address, family: index === 0 ? 4 : 6 })) : []);
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+        resolver.cancel();
+    }
+}
+/** Observe even a misbehaving injected resolver, without holding the request open. */
+async function boundedLookup(lookup, hostname, requestSignal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(requestSignal?.reason);
+    const timer = setTimeout(() => controller.abort(new Error("DNS resolution timed out.")), 10_000);
+    requestSignal?.addEventListener("abort", abort, { once: true });
+    let onAbort;
+    let resolution;
+    try {
+        if (requestSignal?.aborted)
+            abort();
+        controller.signal.throwIfAborted();
+        resolution = lookup(hostname, controller.signal);
+        return await Promise.race([
+            resolution,
+            new Promise((_, reject) => {
+                onAbort = () => reject(controller.signal.reason);
+                controller.signal.addEventListener("abort", onAbort, { once: true });
+                if (controller.signal.aborted)
+                    onAbort();
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        requestSignal?.removeEventListener("abort", abort);
+        if (onAbort)
+            controller.signal.removeEventListener("abort", onAbort);
+        controller.abort();
+        // Drain the owned resolver after cancelling its channels (INV-7). Test
+        // injections may ignore cancellation, but cannot hold send() open.
+        if (lookup === resolveAddresses)
+            await resolution?.catch(() => { });
+    }
+}
 /** Pull-based bridge: Node 22's Readable.toWeb can enqueue after Web cancellation. */
 function responseBody(body, signal) {
     const chunks = body[Symbol.asyncIterator]();
@@ -43,7 +102,7 @@ function responseBody(body, signal) {
  * HTTP/2 REFUSED_STREAM and pipeline recovery paths, for every method.
  * The response/abort owns the client until the body ends or is cancelled.
  */
-export function createNodeGuardedTransport(proxy) {
+export function createNodeGuardedTransport(proxy, lookup = resolveAddresses) {
     let proxyUri;
     let proxyToken;
     if (proxy !== undefined) {
@@ -68,7 +127,41 @@ export function createNodeGuardedTransport(proxy) {
     return {
         delaysDispatch: true,
         async send(url, init, beforeDispatch = () => { }) {
+            const configured = init[learnedDestination];
+            let pinned;
+            if (configured && url.origin !== configured.origin) {
+                const refuse = () => new OAuthRequestNotSentError("connector_call_failed", "The learned URL resolved to an unsafe destination; nothing was sent.", { retryable: false });
+                if (learnedUrlRefusal(configured, url))
+                    throw refuse();
+                const hostname = url.hostname.replace(/^\[|\]$/g, "");
+                let addresses;
+                try {
+                    addresses = isIP(hostname)
+                        ? [{ address: hostname, family: isIP(hostname) }]
+                        : await boundedLookup(lookup, hostname, init.signal);
+                }
+                catch {
+                    init.signal?.throwIfAborted();
+                    throw refuse();
+                }
+                init.signal?.throwIfAborted();
+                if (addresses.length === 0 ||
+                    addresses.some(({ address, family }) => {
+                        if (!isIP(address) || isIP(address) !== family)
+                            return true;
+                        const resolved = new URL(url);
+                        resolved.hostname = family === 6 ? `[${address}]` : address;
+                        return learnedUrlRefusal(configured, resolved) !== undefined;
+                    }))
+                    throw refuse();
+                pinned = addresses[0];
+            }
+            const destination = new URL(url);
+            if (pinned && proxyUri)
+                destination.hostname = pinned.family === 6 ? `[${pinned.address}]` : pinned.address;
             const framed = new Request(url, init);
+            if (pinned)
+                framed.headers.set("host", url.host);
             if (!framed.headers.has("user-agent"))
                 framed.headers.set("user-agent", "connecta");
             let dispatched = false;
@@ -86,6 +179,7 @@ export function createNodeGuardedTransport(proxy) {
                     uri: proxyUri,
                     ...(proxyToken ? { token: proxyToken } : {}),
                     proxyTunnel: true,
+                    ...(pinned ? { requestTls: { servername: isIP(url.hostname) ? "" : url.hostname } } : {}),
                     ...clientOptions,
                     interceptors: { Agent: [], Client: [] },
                     // Neither side of CONNECT uses a Pool, interceptor or global dispatcher.
@@ -99,7 +193,7 @@ export function createNodeGuardedTransport(proxy) {
                                 // ProxyAgent 6 explicitly sets SNI to the proxy hostname.
                                 // Node 26 rejects IP SNI. Omit it for literal IPs; tls.connect
                                 // still checks the certificate against its connection host.
-                                connect({ ...parameters, ...(name && isIP(name.replace(/^\[|\]$/g, "")) ? { servername: "" } : {}) }, callback);
+                                connect({ ...parameters, ...(name ? { servername: isIP(name.replace(/^\[|\]$/g, "")) ? "" : name } : {}) }, callback);
                             },
                         }));
                     },
@@ -135,7 +229,19 @@ export function createNodeGuardedTransport(proxy) {
                         });
                     },
                 })
-                : new Client(url.origin, clientOptions);
+                : new Client(url.origin, {
+                    ...clientOptions,
+                    ...(pinned
+                        ? {
+                            connect: {
+                                // No second resolver can replace the checked address. The Client
+                                // retains the URL hostname for SNI and certificate verification.
+                                lookup: (_hostname, _options, callback) => callback(null, pinned.address, pinned.family),
+                                autoSelectFamily: false,
+                            },
+                        }
+                        : {}),
+                });
             const destroy = () => Promise.allSettled([tunnelClient?.destroy(), client.destroy()]);
             const abort = () => {
                 void destroy();
@@ -146,7 +252,7 @@ export function createNodeGuardedTransport(proxy) {
                 if (!proxyUri)
                     dispatch();
                 const answer = await client.request({
-                    origin: url.origin,
+                    origin: destination.origin,
                     path: `${url.pathname}${url.search}`,
                     method: framed.method,
                     headers: Object.fromEntries(framed.headers),

package/dist/http/oauth.js

@@ -30,7 +30,7 @@ import * as HttpClientResponse from "effect/http/HttpClientResponse";
 import { readRequest, renewedAfterUnauthorized } from "../provider-call.js";
 import { renewableGrantFor } from "../auth/renewable-grant.js";
 import { ConnectorCallError } from "../errors.js";
-import { responseRequest } from "./client.js";
+import { failedResponseRequest, responseRequest } from "./client.js";
 import { Refusal, RequestRefused } from "./errors.js";
 import { Dispatches, Signal, duringCall } from "./services.js";
 /** The calling owner's renewable token, as the operations a transport needs from it. */
@@ -53,6 +53,9 @@ export function grantFromOAuth(oauth) {
     return {
         token: use(grant ? () => grant.token() : missing),
         refresh: (stale) => use(grant ? () => grant.refresh(stale) : missing),
+        ...(grant?.observe
+            ? { observe: (token, outcome) => use(() => grant.observe(token, outcome)) }
+            : {}),
         rejected: use(grant ? () => grant.rejected() : missing),
     };
 }
@@ -80,12 +83,21 @@ export function refreshOnce(guarded, options) {
         return yield* Effect.fail(refusal);
     });
     const execute = (request) => Effect.gen(function* () {
-        const response = yield* inner.execute(request).pipe(Effect.catchTag("ResponseTooLarge", (failure) => {
+        const grant = yield* Grant;
+        const observeOversized = (failure) => {
+            const sent = failedResponseRequest(failure);
+            return responseRequest(failure)?.status === 401 && sent && grant.observe
+                ? grant.observe(sentToken(sent), "refused")
+                : Effect.void;
+        };
+        const response = yield* inner.execute(request).pipe(Effect.tapErrorTag("ResponseTooLarge", observeOversized), Effect.catchTag("ResponseTooLarge", (failure) => {
             const entry = responseRequest(failure);
             return options?.challengeMaxBytes !== undefined && entry?.status === 401
                 ? challengeFailure(entry)
                 : Effect.fail(failure);
         }));
+        if (grant.observe && (response.status === 401 || (response.status >= 200 && response.status < 300)))
+            yield* grant.observe(sentToken(response.request), response.status === 401 ? "refused" : "accepted");
         if (response.status !== 401)
             return response;
         // Read under the ceiling now, so nothing is left open while renewing.
@@ -94,7 +106,6 @@ export function refreshOnce(guarded, options) {
             .pipe(Effect.catchTag("ResponseTooLarge", (failure) => options?.challengeMaxBytes !== undefined
             ? challengeFailure(responseRequest(response))
             : Effect.fail(failure)));
-        const grant = yield* Grant;
         const stale = sentToken(response.request);
         const entry = responseRequest(response);
         if (!readRequest(entry ?? {}) && options?.writeRenewal === "discard") {
@@ -135,11 +146,11 @@ export function refreshOnce(guarded, options) {
             return yield* Effect.fail(new RequestRefused({ message: "This call has ended; no renewal work may continue." }));
         renewedAfterUnauthorized(entry, stale, fresh);
         // `authenticate` runs again on the replay and reads the renewed token.
-        const replay = yield* inner
-            .execute(request)
-            .pipe(Effect.catchTag("ResponseTooLarge", (failure) => options?.challengeMaxBytes !== undefined && responseRequest(failure)?.status === 401
+        const replay = yield* inner.execute(request).pipe(Effect.tapErrorTag("ResponseTooLarge", observeOversized), Effect.catchTag("ResponseTooLarge", (failure) => options?.challengeMaxBytes !== undefined && responseRequest(failure)?.status === 401
             ? grant.rejected
             : Effect.fail(failure)));
+        if (grant.observe && (replay.status === 401 || (replay.status >= 200 && replay.status < 300)))
+            yield* grant.observe(sentToken(replay.request), replay.status === 401 ? "refused" : "accepted");
         if (replay.status !== 401)
             return replay;
         if (options?.replayRejection === "answer") {

package/dist/index.js

@@ -92,14 +92,16 @@ function warnInsecureConfig(config) {
                 : "") +
             "Configure Clerk, Cloudflare Access on Workers, or accessTokens(storage) to gate access.");
     }
-    // Unset publicUrl with OAuth connectors: the downstream redirect_uri is
-    // derived per-request from the attacker-influenced inbound Host header.
-    if (oauthConnectors.length > 0 && !config.publicUrl) {
-        logger.warn("[connecta] publicUrl is unset while OAuth connectors are configured: " +
-            "the downstream OAuth redirect_uri is derived per-request from the " +
-            "inbound Host header, so an attacker who controls that header can point " +
-            "it at their own host and capture the authorization code. Set " +
-            "`publicUrl` to a fixed https origin.");
+    // Unset publicUrl: everything built from the deployment's own URL follows the
+    // inbound request, whose Host (and X-Forwarded-Proto on Node) the caller
+    // chooses. Clerk without any publicUrl has already refused construction.
+    if (!config.publicUrl && (oauthConnectors.length > 0 || inboundAuth.length > 0)) {
+        logger.warn("[connecta] publicUrl is unset: the URLs this deployment hands out, including " +
+            "protected-resource metadata, authorization handoffs and the downstream OAuth " +
+            "redirect_uri, are derived per-request from the inbound Host header (and " +
+            "X-Forwarded-Proto on Node). A caller who controls those can point them at " +
+            "their own host and, with OAuth connectors, capture the authorization code. " +
+            "Set `publicUrl` to a fixed https origin.");
     }
     // Branding URLs that failed their scheme gate. Rendering silently falls back
     // (a bad URL must not take the page down), so this warning is the only way an
@@ -156,19 +158,6 @@ function warnInsecureConfig(config) {
             `action and POST /ui/credentials/${connector.id}/test answers 400 ` +
             "until the matching hook is implemented.");
     }
-    // A vault written before seal/open existed encrypts credentials but cannot
-    // seal downstream OAuth state, so tokens stay plaintext at rest beside them.
-    const vault = config.vault;
-    if (vault && (typeof vault.seal !== "function" || typeof vault.open !== "function")) {
-        for (const connector of config.connectors) {
-            if (!connector.startAuth)
-                continue;
-            logger.warn(`[connecta] connector "${connector.id}" stores its downstream OAuth ` +
-                "tokens, client registration, and PKCE verifier as plaintext: the " +
-                "configured vault implements no `seal`/`open`. Use " +
-                "encryptedCredentialVault(...) or add both methods to seal them.");
-        }
-    }
     // OAuth connectors whose callback cannot perform a state/CSRF check. The
     // public route refuses every callback for these connectors rather than hand
     // an unverified code to finishAuth, so this warning explains why auth cannot

package/dist/invocation-failure.js

@@ -0,0 +1,28 @@
+import { keepErrorName } from "./redaction-identity.js";
+export class InvocationFailure extends Error {
+    details;
+    code;
+    retryable;
+    retryAfterMs;
+    connector;
+    operation;
+    recovery;
+    nextAction;
+    retry;
+    data;
+    constructor(details) {
+        super(details.message);
+        this.details = details;
+        this.name = "InvocationFailure";
+        this.code = details.code;
+        this.retryable = details.retryable;
+        this.retryAfterMs = details.retryAfterMs;
+        this.connector = details.connector;
+        this.operation = details.operation;
+        this.recovery = details.recovery;
+        this.nextAction = details.nextAction;
+        this.retry = details.retry;
+        this.data = details;
+    }
+}
+keepErrorName(InvocationFailure, "InvocationFailure");

package/dist/invocation.js

@@ -1,3 +1,5 @@
+import { utilityRecovery } from "./utility-recovery.js";
+import { traceFor } from "./timing-trace.js";
 import { routePhrases } from "./agent-routes.js";
 import { authCall, registerAuthMethod } from "./auth/native.js";
 import { withAuthorizationHandoffEffect } from "./authorization-handoff.js";
@@ -16,11 +18,10 @@ import { recoveryRecord, recordRecoveryFacts } from "./call-recovery.js";
 import { callFromContext, contextView, viewServices, Credentials } from "./runtime/call.js";
 import { chargeCallBudget } from "./runtime/call-admission.js";
 import { callEntry } from "./runtime/call-entry.js";
-import { forgetProviderFailure, isKnownProviderFailure, isSettledWrite, keyProtectsCall, knownCallFailure, onlyAuxiliaryRequests, knownProviderFailure, openLogicalCall, } from "./provider-call.js";
+import { forgetProviderFailure, isKnownProviderFailure, isSettledWrite, keyProtectsCall, knownCallFailure, refusalRequest, onlyAuxiliaryRequests, knownProviderFailure, openLogicalCall, } from "./provider-call.js";
 import { classifyWriteOutcome, settleWrite, settleWriteResult } from "./write-outcome.js";
 import { classificationDigest, recordAuthFailure, recordCallEntry, replayClassificationDigest, resolveInvocationAuthEffect, } from "./invocation-auth.js";
 import { downstreamContinuation, recordDownstreamArgumentEcho, isDownstreamInputResult, assertDownstreamOutputSafe, } from "./downstream-input-context.js";
-import { keepErrorName } from "./redaction-identity.js";
 function defined(values) {
     return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
 }
@@ -115,33 +116,7 @@ function answeredFailure(error, write, call) {
         return error instanceof DownstreamToolError || isKnownProviderFailure(error);
     return knownCallFailure(call, error);
 }
-export class InvocationFailure extends Error {
-    details;
-    code;
-    retryable;
-    retryAfterMs;
-    connector;
-    operation;
-    recovery;
-    nextAction;
-    retry;
-    data;
-    constructor(details) {
-        super(details.message);
-        this.details = details;
-        this.name = "InvocationFailure";
-        this.code = details.code;
-        this.retryable = details.retryable;
-        this.retryAfterMs = details.retryAfterMs;
-        this.connector = details.connector;
-        this.operation = details.operation;
-        this.recovery = details.recovery;
-        this.nextAction = details.nextAction;
-        this.retry = details.retry;
-        this.data = details;
-    }
-}
-keepErrorName(InvocationFailure, "InvocationFailure");
+export { InvocationFailure } from "./invocation-failure.js";
 const withoutExample = ({ example: _example, ...stated }) => stated;
 /**
  * Shared downstream invocation engine. Address/catalog resolution is delegated
@@ -244,7 +219,9 @@ export class InvocationService {
             };
             const enrich = (error, target, settled) => {
                 if (!target)
-                    return error;
+                    return ["unavailable", "catalog_lookup_failed", "unsupported_capability"].includes(error.code)
+                        ? { ...error, nextAction: error.nextAction ?? utilityRecovery(error.code, error.message).nextAction }
+                        : error;
                 const recovery = recoveryState.facts;
                 const enteredWrite = dispatchedToConnector &&
                     ((resolved !== undefined && resolved.definition.classification !== "read") || sentSourceWrite());
@@ -288,10 +265,13 @@ export class InvocationService {
                 }
                 if (mayHaveWritten &&
                     (error.code === "auth_required" || error.code === "downstream_oauth_required") &&
-                    !logicalCall?.sent.some((request) => request.dispatched)) {
+                    !logicalCall?.sent.some((request) => request.dispatched) &&
+                    !(answered && refusalRequest(error)?.dispatched === false)) {
                     // An empty resource ledger cannot settle this auth failure. Keep
                     // actual resource-refusal provenance, but withdraw an empty ledger's
                     // known mark before composing advice and counting program writes.
+                    // A boundary-owned physical pre-dispatch refusal is positive proof;
+                    // its private provenance cannot be supplied by error fields.
                     answered = false;
                     forgetProviderFailure(error);
                 }
@@ -300,7 +280,16 @@ export class InvocationService {
                 // retryable, and no advice below may tell the agent to retry it.
                 const unknownWrite = mayHaveWritten && classifyWriteOutcome({ ok: false, dispatched: true, answered, error }) === "unknown";
                 if (unknownWrite)
-                    error = { ...error, retryable: false, writeOutcome: "unknown" };
+                    error = {
+                        ...error,
+                        retryable: false,
+                        writeOutcome: "unknown",
+                        ...(!recovery && error.retry === undefined
+                            ? {
+                                retry: "No safe replay action exists. Re-read the target to reconcile whether the write took effect.",
+                            }
+                            : {}),
+                    };
                 // The failure's advice to send it again was kept apart until now, and
                 // joins its message only where the outcome allows it: never on a write
                 // whose outcome is unknown, whatever redaction did to the message.
@@ -331,9 +320,22 @@ export class InvocationService {
                     error = { ...error, code: "downstream_oauth_required" };
                 }
                 switch (error.code) {
+                    case "unsupported_capability":
+                        return unknownWrite
+                            ? error
+                            : {
+                                ...error,
+                                nextAction: utilityRecovery(error.code, "The requested capability is unsupported.").nextAction,
+                            };
                     case "input_required_unsupported":
                         if (context.processInputRequired)
-                            return error;
+                            return unknownWrite
+                                ? error
+                                : {
+                                    ...error,
+                                    nextAction: error.nextAction ??
+                                        utilityRecovery(error.code, "The requested input capability is unsupported.").nextAction,
+                                };
                         // Resending could apply the write twice: reconcile first.
                         if (unknownWrite)
                             return {
@@ -404,8 +406,13 @@ export class InvocationService {
                             retry: "Ask the provider's resource owner or administrator to grant the required permission or scope, then retry. Repeating the call or reconnecting alone will not grant access.",
                         };
                     case "invalid_args":
-                        if (!error.validation || error.writeOutcome === "unknown")
+                        if (error.writeOutcome === "unknown")
                             return error;
+                        if (!error.validation)
+                            return {
+                                ...error,
+                                nextAction: this.catalog.searchRecovery({ query: target.toolName, connector: target.connector.id }, "Inspect the current input schema and correct the arguments before a fresh call."),
+                            };
                         return {
                             ...error,
                             // An example comes only from the published schema, never a connector's copy of the
@@ -424,6 +431,27 @@ export class InvocationService {
                             }, "Inspect the current input shape if the validation findings are not sufficient."),
                             retry: `Correct the listed arguments and retry ` + `${target.connector.id}.${target.toolName}.`,
                         };
+                    case "not_found":
+                        if (unknownWrite)
+                            return error;
+                        return {
+                            ...error,
+                            retry: "No automatic retry action exists. Verify the resource id, account and visibility with a read before a fresh call.",
+                        };
+                    case "unavailable":
+                    case "catalog_lookup_failed":
+                        if (unknownWrite)
+                            return error;
+                        // The continuation nonce is spent. Let the input boundary supply
+                        // its fresh-call action instead of generic availability advice.
+                        if (context.source !== "execute_code" &&
+                            downstreamContinuation(this.catalog.requestScope, target.connector.id, `${target.connector.id}.${target.toolName}`))
+                            return error;
+                        return {
+                            ...error,
+                            nextAction: error.nextAction ?? utilityRecovery(error.code, error.message).nextAction,
+                            retry: "No immediate repair action exists on this endpoint. Ask the operator to check connector availability; a read can be tried again after recovery.",
+                        };
                     default:
                         return error;
                 }
@@ -443,6 +471,13 @@ export class InvocationService {
                     }
                 }
                 const diagnostics = timing();
+                const trace = traceFor(this.catalog.requestScope);
+                if (trace) {
+                    trace.record("catalog", diagnostics.catalogMs);
+                    trace.record("admission", diagnostics.admissionMs);
+                    trace.record("connector", diagnostics.connectorMs);
+                    trace.record("result", diagnostics.resultProcessingMs, resultBytes ?? 0);
+                }
                 const target = resolved ?? activityTarget;
                 if (target && (error.code === "auth_required" || error.code === "downstream_oauth_required")) {
                     recordAuthFailure(this.catalog.requestScope, target.connector.id, (resolved !== undefined && !isWriteLike(resolved.definition) && resolved.classificationFresh === true) ||
@@ -559,7 +594,7 @@ export class InvocationService {
                 const connectorReadOnly = target.connector.readOnly === true;
                 const refusal = writeRefusal(target.definition.classification, context.source, context.readOnly || connectorReadOnly);
                 if (refusal === "read_only_endpoint") {
-                    return framingError("read_only_endpoint", `Tool "${canonicalAddress}" is a write, and ${connectorReadOnly ? `connector "${target.connector.id}"` : "this endpoint"} is read-only. Nothing here can send it.`);
+                    return framingError("read_only_endpoint", `Tool "${canonicalAddress}" is a write, and ${connectorReadOnly ? `connector "${target.connector.id}"` : "this endpoint"} is read-only. No write route exists ${connectorReadOnly ? "for this connection" : "on this endpoint"}. Ask the operator for a writable connection if writes are required.`);
                 }
                 if (refusal === "destructive_tool_requires_approval") {
                     return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is a write. ${routePhrases(context).writeNeedsApproval}`);
@@ -804,6 +839,13 @@ export class InvocationService {
             try {
                 const value = sentSecrets.redact(processed.value, "envelope");
                 const diagnostics = timing();
+                const trace = traceFor(this.catalog.requestScope);
+                if (trace) {
+                    trace.record("catalog", diagnostics.catalogMs);
+                    trace.record("admission", diagnostics.admissionMs);
+                    trace.record("connector", diagnostics.connectorMs);
+                    trace.record("result", diagnostics.resultProcessingMs, resultBytes ?? 0);
+                }
                 const friction = context.activityFriction?.(value);
                 record("success", friction ? { friction } : {});
                 return {

package/dist/membership.d.ts

@@ -26,7 +26,7 @@ export interface ResolvedPool {
     members: readonly Member[];
     /** Trimmed `owner`: the Workspace address agents in this pool act as. */
     owner?: string;
-    /** Trimmed `description`, appended to this pool's MCP instructions. */
+    /** Trimmed `description`, placed before this pool's MCP routing instructions. */
     description?: string;
     /** Present for a native pool; absent is the six meta-tools. */
     native?: {