@zackbart/connecta 0.40.0 → 0.41.0

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";
@@ -20,7 +22,6 @@ import { forgetProviderFailure, isKnownProviderFailure, isSettledWrite, keyProte
 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());
@@ -303,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.
@@ -334,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 {
@@ -407,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
@@ -427,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;
                 }
@@ -446,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) ||
@@ -562,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}`);
@@ -807,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?: {

package/dist/meta-tools.js

@@ -1,3 +1,6 @@
+import { operationActivity } from "./operation-activity.js";
+import { SkillLookupError } from "./skills.js";
+import { skillLookupRecovery, utilityRecovery } from "./utility-recovery.js";
 import { META_ROUTES } from "./agent-routes.js";
 import { toolError } from "./tool-error.js";
 import { upwardStep } from "./upward.js";
@@ -38,6 +41,9 @@ export function jsonResult(obj, text = JSON.stringify(obj)) {
 function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
+function resultError(message) {
+    return toolError(utilityRecovery("invalid_args", message));
+}
 function discoveryErrorResult(error) {
     return toolError({ code: error.code, message: error.message, retryable: false });
 }
@@ -558,6 +564,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     }
     const sentSecrets = sentSecretsForRequest(requestScope);
     const skills = new SkillsRegistry(registry, baseUrl, {
+        readOnly: opts.readOnly,
         requestScope,
         requestSignal: opts.requestSignal,
         probeTimeoutMs,
@@ -731,7 +738,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             };
         });
     });
-    return {
+    const methods = {
         skills: authMethod((args = {}) => authFlow(function* () {
             try {
                 if (!args.name) {
@@ -751,7 +758,9 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 return { content: [{ type: "text", text }], structuredContent: { name: args.name, format: "text", text } };
             }
             catch (error) {
-                return errorResult(error instanceof ConnectorCallError ? error.message : "Skills are unavailable.");
+                if (error instanceof SkillLookupError)
+                    return toolError(skillLookupRecovery(error.message));
+                return toolError(utilityRecovery(error instanceof ConnectorCallError ? error.code : "unavailable", "Skills are unavailable.", error instanceof ConnectorCallError && error.retryable));
             }
         })),
         searchTools: authMethod((args) => authFlow(function* () {
@@ -781,25 +790,21 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             // Defense for in-process callers too: guest paging validates these domains
             // before calling here, while internal consumers may call readResult directly.
             if (args.maxBytes !== undefined && !isValidMaxResultBytes(args.maxBytes)) {
-                return errorResult(`Invalid maxBytes ${args.maxBytes}: must be a whole number of bytes ` +
+                return resultError(`Invalid maxBytes ${args.maxBytes}: must be a whole number of bytes ` +
                     `>= ${MIN_MAX_RESULT_BYTES}. Omit it to use the deployment default.`);
             }
             if (args.offset !== undefined && !isValidResultOffset(args.offset)) {
-                return errorResult(`Invalid offset ${args.offset}: must be a whole number of bytes ` +
+                return resultError(`Invalid offset ${args.offset}: must be a whole number of bytes ` +
                     `>= ${MIN_RESULT_OFFSET}. Omit it to start at the beginning.`);
             }
             if (args.page !== undefined &&
                 (!Number.isSafeInteger(args.page) || args.page < 0 || args.offset !== undefined)) {
-                return errorResult("Use a whole page >= 0, without offset.");
+                return resultError("Use a whole page >= 0, without offset.");
             }
             const results = registry.resultsStorage();
             const unavailableResult = () => ({
                 ...jsonResult({
-                    error: {
-                        code: "unavailable",
-                        message: "Result paging storage is unavailable.",
-                        retryable: true,
-                    },
+                    error: utilityRecovery("unavailable", "Result paging storage is unavailable.", true),
                 }),
                 isError: true,
             });
@@ -825,9 +830,9 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             if (stored === false)
                 return unavailableResult();
             if (stored === null) {
-                return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+                return toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
             }
-            const denied = () => errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+            const denied = () => toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
             const header = RESULT_ENVELOPE_V4_HEADER.exec(stored);
             if (!header)
                 return denied();
@@ -941,7 +946,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     if (encoded === null) {
                         // A chunk expired or was evicted under its own header; the id can no
                         // longer serve this range, and inventing U+0000 filler would be worse.
-                        return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+                        return toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
                     }
                     const chunkStart = index * chunkBytes;
                     // Both bounds are chunk-local. `from` inherits `start`'s three-byte
@@ -999,6 +1004,15 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             }
         })),
     };
+    if (!opts.activity?.recordOperation)
+        return methods;
+    const track = (name, method) => authMethod((...args) => operationActivity(opts.activity, registry, name, authCall(method, args)));
+    return {
+        ...methods,
+        skills: track("skill", methods.skills),
+        searchTools: track("search", methods.searchTools),
+        readResult: track("result", methods.readResult),
+    };
 }
 // Each description states only its own tool's scope; the full routing rule
 // lives once in the server instructions. A client that drops instructions

package/dist/module-contracts.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectaBranding } from "./types.js";
-import type { ActivityStore, ActivityReadGate, recordToolActivity, recordCatalogChangeActivity } from "./activity.js";
+import type { ActivityStore, ActivityReadGate, recordToolActivity, recordCatalogChangeActivity, recordOperationActivity } from "./activity.js";
 import type { RouteContext } from "./routes/shared.js";
 /** Construction-time UI contract. Core never imports the implementation. */
 export interface OperatorSurface {
@@ -10,6 +10,8 @@ export interface OperatorSurface {
 }
 /** Optional recording and reading callbacks supplied by /activity. */
 export interface ActivityModule {
+    readonly operations?: boolean;
+    readonly recordOperation?: typeof recordOperationActivity;
     readonly store: ActivityStore;
     readonly deploymentId?: string;
     readonly readGate?: ActivityReadGate;