@zackbart/connecta 0.39.0 → 0.41.0

package/dist/config.js

@@ -189,7 +189,7 @@ function assertFlag(value, path) {
     if (typeof value !== "boolean")
         throw new ConfigError(`${path} must be true or false.`);
 }
-/** Longest pool `description`, in characters, after trimming. */
+/** Longest pool `description`, in UTF-16 code units, after trimming. */
 const MAX_POOL_DESCRIPTION_LENGTH = 500;
 /**
  * A pool description is one line of prose for the model. C0 and C1 controls
@@ -209,9 +209,9 @@ function assertPoolDescription(value, path) {
     const trimmed = typeof value === "string" ? value.trim() : undefined;
     if (trimmed === undefined ||
         trimmed.length === 0 ||
-        [...trimmed].length > MAX_POOL_DESCRIPTION_LENGTH ||
+        trimmed.length > MAX_POOL_DESCRIPTION_LENGTH ||
         hasLineBreakOrControlCharacter(trimmed)) {
-        throw new ConfigError(`${path} must be text of 1 to ${MAX_POOL_DESCRIPTION_LENGTH} characters after trimming, with no line breaks or control characters.`);
+        throw new ConfigError(`${path} must be text of 1 to ${MAX_POOL_DESCRIPTION_LENGTH} UTF-16 code units after trimming, with no line breaks or control characters.`);
     }
 }
 /** Shape only; each reference resolves against auth and agents in createConnecta. */
@@ -263,7 +263,7 @@ const pool = {
      * What this pool is for, in plain words for the model: appended to the MCP
      * `initialize` instructions at `/mcp/<name>` and `/agent/<name>`, so a
      * caller learns its scope ("Team tier: shared tools only."). Trimmed, 1 to
-     * 500 characters, no line breaks or control characters. It grants and hides nothing; plain
+     * 500 UTF-16 code units, no line breaks or control characters. It grants and hides nothing; plain
      * `/mcp` never shows it.
      */
     description: opaque({ check: assertPoolDescription }),
@@ -396,8 +396,9 @@ const connectaConfig = {
         resolve: (value) => value ?? memoryStorage(),
     }),
     /**
-     * Public base URL. Defaults to the request origin per-request. Configuring an
-     * HTTPS URL also redirects matching inbound HTTP requests to HTTPS.
+     * Public base URL. Defaults to the request origin per-request, except that
+     * clerkAuth requires it here or as its own `publicUrl`. Configuring an HTTPS
+     * URL also redirects matching inbound HTTP requests to HTTPS.
      */
     publicUrl: opaque({ check: httpUrl }),
     /**
@@ -419,7 +420,10 @@ const connectaConfig = {
             }
         },
     }),
-    /** Replaceable owner-partitioned credential storage. Omit for config-owned secrets. */
+    /**
+     * Replaceable owner-partitioned credential storage. Omit for config-owned
+     * secrets. With any OAuth connector it must implement `seal` and `open`.
+     */
     vault: opaque({
         check: (value) => {
             if (!hasMethods(value, ["get", "getAll", "set", "setAll", "metadata", "delete"]) ||
@@ -464,6 +468,14 @@ const connectaConfig = {
      * saturation.
      */
     admission: object(admission),
+    /** Payload-free request timing logs; 0 disables tracing, 1 samples every MCP request. */
+    timingTraceSampleRate: opaque({
+        check: (value, path) => {
+            if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1)
+                throw new ConfigError(`${path} must be a finite number between 0 and 1.`);
+        },
+        resolve: (value) => value ?? 0,
+    }),
     /** Diagnostic output. Use "silent" to disable all diagnostic logging. */
     logger: opaque({
         check: (value, path) => {
@@ -528,10 +540,21 @@ function assertCoherent(config) {
         config.discovery.catalogMaxTtlSeconds > 86_400) {
         throw new ConfigError("ConnectaConfig.discovery requires catalogMinTtlSeconds <= catalogMaxTtlSeconds <= 86400.");
     }
+    const { vault } = config;
+    const oauth = config.connectors.find((connector) => connector.startAuth);
+    if (oauth && vault && (typeof vault.seal !== "function" || typeof vault.open !== "function")) {
+        throw new ConfigError(`ConnectaConfig.vault must implement both seal and open: connector "${oauth.id}" stores downstream OAuth ` +
+            "tokens, client registration and PKCE verifiers through it. Use encryptedCredentialVault(storage, key) " +
+            "from @zackbart/connecta/credentials, or add both methods.");
+    }
     if (config.agents.some((agent) => !agent.vercel) && !config.accessTokens) {
         throw new ConfigError("ConnectaConfig.agents needs accessTokens: accessTokens(storage) from @zackbart/connecta/auth/access-tokens " +
             "holds each agent's token slot.");
     }
+    if (!config.publicUrl && config.auth.some((provider) => provider.requiresPublicUrl)) {
+        throw new ConfigError("ConnectaConfig.publicUrl is required with clerkAuth, which checks tokens and sessions against it: " +
+            "set it, or clerkAuth({ publicUrl }), to this deployment's URL, http://localhost:<port> for local development.");
+    }
 }
 /**
  * Validate a configuration and apply every default. Unknown keys are refused

package/dist/connectors/remote-mcp/call.js

@@ -55,7 +55,7 @@ export function remoteMcpCall(rt) {
                     }
                     : state.toolDefinitions.get(name);
                 if (toolDefinition?.execution?.taskSupport === "required") {
-                    throw new ConnectorCallError("connector_call_failed", `Tool "${name}" requires task-based execution, which Connecta does not support.`);
+                    throw new ConnectorCallError("unsupported_capability", `Tool "${name}" requires task-based execution, which Connecta does not support.`);
                 }
                 let output;
                 const outputError = (code, message) => rt.atMcpBoundary(ctx, new ProtocolError(code, message), "tools/call", client.transport, [ctx.signal]);

package/dist/connectors/remote-mcp/connection.js

@@ -12,7 +12,7 @@ import { Deferred, Effect, Exit, Scope } from "effect";
 import { KvOAuthProvider, refreshCoordinatorsByPartition } from "../../auth/downstream-oauth.js";
 import { trackOAuthStartReset } from "../../auth/oauth-start-reset.js";
 import { sentSecretsFor } from "../../sent-secrets.js";
-import { catalogClientOptions, observeCatalogChange } from "../../catalog-cache.js";
+import { catalogClientOptions, prefetchCatalog, observeCatalogChange } from "../../catalog-cache.js";
 import { ConnectorCallError, resendAdvice } from "../../errors.js";
 import { carryFailureFacts, failureRecord, logFailure } from "../../operator-record.js";
 import { CONNECTA_VERSION } from "../../version.js";
@@ -23,11 +23,42 @@ import { downstreamInputCapabilities } from "../../downstream-input-context.js";
 import { detach, runEdge } from "../../runtime/run.js";
 import { requestPrincipalFor } from "../../request-principal.js";
 import { callerOf } from "../../connector-caller.js";
+import { negotiationKeys } from "../../storage/keys.js";
 import { forgetNegotiation, readNegotiation, storeNegotiation } from "../negotiation-cache.js";
 import { carriesIllegalHeaderChar, credentialHeaderValue } from "./config.js";
 import { AUTH_OR_THROTTLE, promised, recordWireErrors, requiresAuthorization } from "./errors.js";
 import { MAX_TOOL_PAGES } from "./catalog.js";
 import { SKILLS_EXTENSION } from "./resources.js";
+/** Retain every abandoned lease release until the final scope close joins it. */
+export function retainCleanup(state, release) {
+    const pending = detach(release);
+    state.cleanup.add(pending);
+    if (state.closing)
+        state.closing = Promise.all([state.closing, pending]).then(() => { });
+    // Register at the release itself as well: a late connect can acquire a
+    // session after the owner's first close has already settled.
+    try {
+        state.defer?.(pending);
+    }
+    catch {
+        // Runtime hooks are best-effort; the bounded cleanup is already running.
+    }
+    void pending.then(() => state.cleanup.delete(pending));
+    return pending;
+}
+/** Scope.closeUnsafe returns nothing on a second close, even during release. */
+export function closeConnectionScope(state) {
+    if (!state.closing) {
+        const release = Scope.closeUnsafe(state.scope, Exit.void);
+        if (release)
+            retainCleanup(state, release);
+        state.closing = (async () => {
+            while (state.cleanup.size)
+                await Promise.all(state.cleanup);
+        })();
+    }
+    return state.closing;
+}
 /** One connector's connection states, credential reads and connect attempts. */
 export function remoteMcpConnection(rt) {
     const { requestAuth, forwarding, id, staticClient, clientMetadataUrl, opts, oauthScope, authorizationParams, destination, isOauth, extraHeaders, credentialHeader, credentialScheme, skillsEnabled, principalPolicy, credentialAuth, } = rt;
@@ -103,6 +134,9 @@ export function remoteMcpConnection(rt) {
         if (!state) {
             state = {
                 scope: Scope.makeUnsafe(),
+                closing: null,
+                cleanup: new Set(),
+                defer: ctx.defer,
                 lease: null,
                 client: null,
                 transport: null,
@@ -118,10 +152,8 @@ export function remoteMcpConnection(rt) {
             states.set(key, state);
             const owned = state;
             owner.own(() => {
-                const closing = Scope.closeUnsafe(owned.scope, Exit.void);
+                void closeConnectionScope(owned);
                 reset(owned);
-                if (closing)
-                    detach(closing);
             });
         }
         return state;
@@ -189,7 +221,7 @@ export function remoteMcpConnection(rt) {
         reset(state);
         const release = lease && Scope.closeUnsafe(lease, Exit.void);
         if (release)
-            detach(release);
+            retainCleanup(state, release);
     };
     const waitForConnection = (attempt, signal) => runEdge(Deferred.await(attempt), signal ? { signal } : {});
     const oauthConfigFor = (ctx) => isOauth
@@ -272,6 +304,7 @@ export function remoteMcpConnection(rt) {
         try {
             let epoch = "";
             let identity;
+            let pinnedIdentity;
             if (isOauth) {
                 // Read-only grant snapshots: no in-place sealing, epoch binding or
                 // refresh. Every identity check during cache acceptance re-reads the
@@ -282,6 +315,7 @@ export function remoteMcpConnection(rt) {
                 epoch = snapshot.epoch;
                 if (provider.isOperatorDisconnectedEpoch(epoch) || !snapshot.tokens)
                     return preread;
+                pinnedIdentity = yield authCall(secretDigest, [ctx, JSON.stringify(snapshot.tokens)]);
                 const bound = epoch;
                 identity = authMethod(() => authFlow(function* () {
                     const current = (yield authInvoke(provider, "peekGrant", []));
@@ -293,6 +327,17 @@ export function remoteMcpConnection(rt) {
             }
             if (opts.versionNegotiation !== "legacy") {
                 const digest = (yield authCall(negotiationKey, [ctx, credentialDigest, epoch]));
+                // Both reads only locate cached data. Acceptance and dispatch keep
+                // their fresh generation and credential checks.
+                yield authCall(prefetchCatalog, [
+                    ctx,
+                    id,
+                    (yield authCall(catalogConfigFor, [ctx])),
+                    JSON.stringify([epoch, credentialDigest]),
+                    catalogSharing,
+                    pinnedIdentity,
+                    negotiationKeys.verdict(digest),
+                ]);
                 const prior = (yield authCall(readNegotiation, [ctx, digest]));
                 preread.negotiation = { digest, prior };
                 if (prior?.kind === "modern")
@@ -633,13 +678,13 @@ export function remoteMcpConnection(rt) {
                         state.authRequired = true;
                     const release = Scope.closeUnsafe(lease, Exit.void);
                     if (release)
-                        detach(release);
+                        retainCleanup(state, release);
                 }
                 else {
                     // Whoever abandoned this attempt closed the lease already, while
                     // the connect was in flight. A session it acquired after that
                     // close still owes its DELETE.
-                    detach(rt.closeConnection(held.client, held.transport, ctx.logger));
+                    retainCleanup(state, rt.closeConnection(held.client, held.transport, ctx.logger));
                 }
                 if (err instanceof UnauthorizedError) {
                     return Effect.fail(carryFailureFacts(err, rt.authRequiredError(ctx)));

package/dist/connectors/remote-mcp/oauth.js

@@ -1,5 +1,6 @@
 // The downstream OAuth surface: bounded SDK flows, early renewal before a
 // call, unchallenged consent starts, and the connector's auth operations.
+import { retainCleanup } from "./connection.js";
 import { authView } from "../../auth/native-call.js";
 import { authFlow, authCall, authInvoke, authMethod } from "../../auth/native.js";
 import { viewSignal } from "../../runtime/call.js";
@@ -10,7 +11,6 @@ import { byteReadResponse } from "../../byte-read-response.js";
 import { requestSentSecrets, sentSecretsFor } from "../../sent-secrets.js";
 import { ConnectorCallError, resendAdvice, WithheldTextError } from "../../errors.js";
 import { attachFailureFacts, carryFailureFacts, OAUTH_ERROR_CODES } from "../../operator-record.js";
-import { detach } from "../../runtime/run.js";
 import { retryAfterMs } from "../../http-policy.js";
 import { sendCredentialPost } from "../../guarded-transport.js";
 import { UnboundOAuthFlowsError, downstreamCallError, errorKind, hasSdkPayload, ownAbortReason, requiresAuthorization, startMessage, withheldAs, } from "./errors.js";
@@ -376,7 +376,7 @@ export function remoteMcpOAuth(rt) {
                 ]));
             }
             finally {
-                detach(rt.closeConnection(null, t, ctx.logger));
+                retainCleanup(state, rt.closeConnection(null, t, ctx.logger));
             }
         })), true));
         connector.verifyState = authMethod((oauthState, ctx) => authFlow(function* () {
@@ -399,6 +399,10 @@ export function remoteMcpOAuth(rt) {
         connector.startAuth = authMethod((ctx, startOpts) => authFlow(function* () {
             ctx = authorizingContext(ctx);
             const state = rt.stateFor(ctx);
+            // A passive tokenless handshake was refused locally. An explicit
+            // start gets its own challenge-capable connection attempt.
+            if (state.authRequired && !state.client)
+                rt.closeHalf(state);
             state.provider = null;
             const p = rt.newProvider(ctx, state);
             if (ctx.signal?.aborted)

package/dist/connectors/remote-mcp/resources.js

@@ -345,8 +345,11 @@ export function remoteMcpResources(rt) {
             if (client.getProtocolEra() !== "modern" ||
                 !skillObject(capabilities?.resources) ||
                 !skillObject(extension) ||
+                // The released Beta specification defines no revision setting.
+                // Never enable a future breaking revision under the same ID.
+                extension.revision !== undefined ||
                 (extension.directoryRead !== undefined && typeof extension.directoryRead !== "boolean")) {
-                throw new ConnectorCallError("connector_call_failed", "The downstream did not declare a valid Skills extension and resources capability.");
+                throw new ConnectorCallError("unsupported_capability", "The downstream did not declare a valid Skills extension and resources capability.");
             }
             const result = (yield authCall(run, [client, state]));
             skillScopeOpen(ctx, state);
@@ -415,7 +418,7 @@ export function remoteMcpResources(rt) {
             rt.listingContexts.set(options, ctx);
             try {
                 if (!client.getServerCapabilities()?.resources)
-                    throw unadvertisedResource();
+                    throw new ConnectorCallError("unsupported_capability", "The downstream did not declare resources support.");
                 const resources = (yield authInvoke(client, "listResources", [undefined, options]));
                 const templates = (yield authInvoke(client, "listResourceTemplates", [
                     undefined,

package/dist/connectors/remote-mcp/transport.js

@@ -18,8 +18,8 @@ import { learnedUrlRefusal } from "../../url-safety.js";
 import { RequestScope } from "../../runtime/request-scope.js";
 import { Context } from "effect";
 import { downstreamWriteContinuation } from "../../downstream-input-context.js";
-import { guardedTransport, sendGuarded, sendCredentialPost } from "../../guarded-transport.js";
-import { dispatchProviderRequest, recordProviderResponse, providerRequest, renewedAfterUnauthorized, } from "../../provider-call.js";
+import { learnedDestination, guardedTransport, sendGuarded, sendCredentialPost, } from "../../guarded-transport.js";
+import { dispatchProviderRequest, recordProviderResponse, knownProviderFailure, providerRequest, renewedAfterUnauthorized, } from "../../provider-call.js";
 import { recordRequestField } from "../../provider-call-facts.js";
 import { AUTH_OR_THROTTLE, errorBodyText, jsonRpcErrorBody, keepsModernVerdict, promised } from "./errors.js";
 import { MAX_SKILL_READ_RPC_BYTES, boundedSkillResponse, skillObject } from "./resources.js";
@@ -128,11 +128,25 @@ labelErrorClass(RemoteMcpDestinationError, "RemoteMcpDestinationError");
  */
 export function learnedUrlSafeFetch(connectorId, configured, baseFetch) {
     return authMethod((input, init) => authFlow(function* () {
-        const reason = learnedUrlRefusal(configured, new URL(input));
-        if (reason !== undefined) {
-            throw new RemoteMcpDestinationError(connectorId, reason);
+        let target = new URL(input);
+        for (let hop = 0; hop < 10; hop++) {
+            const reason = learnedUrlRefusal(configured, target);
+            if (reason !== undefined)
+                throw new RemoteMcpDestinationError(connectorId, reason);
+            const marked = { ...init, redirect: "manual", [learnedDestination]: configured };
+            const response = (yield authCall(baseFetch, [target, marked]));
+            if (!REDIRECT_STATUSES.has(response.status) ||
+                !response.headers.has("location") ||
+                (init?.method ?? "GET").toUpperCase() !== "GET")
+                return byteReadResponse(response);
+            const location = response.headers.get("location");
+            void response.body?.cancel().catch(() => { });
+            const redirected = new URL(location, target);
+            if (redirected.origin !== target.origin)
+                throw new RemoteMcpDestinationError(connectorId, "cross-origin redirect refused");
+            target = redirected;
         }
-        return byteReadResponse((yield authCall(baseFetch, [input, init])));
+        throw new RemoteMcpDestinationError(connectorId, "redirect limit exceeded");
     }));
 }
 /**
@@ -273,12 +287,27 @@ export function remoteMcpTransport(rt) {
             if (toolCall && !flight && !untrackedRead(toolCall.params))
                 throw missingDispatch();
             const credentialPost = isOauth && (init?.method ?? "GET").toUpperCase() === "POST" && (!skillObject(rpc) || rpc.jsonrpc !== "2.0");
+            // OAuth discovery, registration and exchange share this fetch, but do
+            // not use the resource credential. Guard the assembled MCP request,
+            // after the SDK token read and before dispatch bookkeeping or fetch.
+            // OAuth is required on passive paths regardless of which provider
+            // read the grant. Only an explicit authorization start may probe the
+            // resource anonymously for an SDK challenge, never a tools/call.
+            if (isOauth && !credentialPost && new URL(input).href === url.href) {
+                const authorization = new Headers(init?.headers).get("authorization");
+                if ((provider?.allowAuthorization !== true || toolCall) && !authorization)
+                    throw knownProviderFailure(rt.authRequiredError(ctx), flight?.sent ? undefined : (flight?.request?.entry ?? providerRequest(ctx, true, id)));
+            }
             // A custom transport reaches only the configured origin; redirects are
             // already same-origin, and OAuth cannot be combined with it.
             if (customFetch && new URL(input instanceof Request ? input.url : String(input)).origin !== destination.origin)
                 throw new ConnectorCallError("connector_call_failed", `Connector "${id}" refused a request outside its origin; nothing was sent.`, { retryable: false });
             // The deployment's fetch owns the wire: each write is handed over once.
-            const sender = flight?.write ? (customSender ?? guardedTransport(true)) : undefined;
+            const sender = flight?.write
+                ? (customSender ?? guardedTransport(true))
+                : init?.[learnedDestination]
+                    ? guardedTransport(false)
+                    : undefined;
             if (flight?.write) {
                 if (flight.sent) {
                     if (flight.request && flight.authorization)
@@ -410,7 +439,7 @@ export function remoteMcpTransport(rt) {
                 }
             })));
         if (opts.auth?.type === "oauth") {
-            const oauthProvider = provider ?? rt.newProvider(ctx, undefined, signal);
+            const oauthProvider = (provider ??= rt.newProvider(ctx, undefined, signal));
             // The session/provider belong to the request. A renewal belongs to the
             // exact call whose HTTP response challenged it, until claim submission.
             // Carry that ownership on the response the SDK passes to onUnauthorized;

package/dist/connectors/remote-mcp.js

@@ -5,7 +5,7 @@ import { authFlow, authCall, authInvoke, authValue, authMethod, authCatch } from
 import { viewServices, viewSignal } from "../runtime/call.js";
 import { declareSelfHostedClient } from "../auth/downstream-client-metadata.js";
 import { isInputRequiredResult } from "@modelcontextprotocol/client";
-import { Duration, Effect, Exit, Scope } from "effect";
+import { Duration, Effect } from "effect";
 import { byteReadResponse } from "../byte-read-response.js";
 import { redactSentSecrets, requestSentSecrets, sentSecretsFor } from "../sent-secrets.js";
 import { closeCatalogCacheScope } from "../catalog-cache.js";
@@ -28,7 +28,7 @@ import { providerBoundary } from "../provider-call.js";
 import { downstreamCallError, hasSdkPayload, payloadFree, remoteMcpErrors } from "./remote-mcp/errors.js";
 import { LOCAL_CLOSE_BUDGET_MS, REDIRECT_STATUSES, remoteMcpTransport } from "./remote-mcp/transport.js";
 import { remoteMcpConfig } from "./remote-mcp/config.js";
-import { remoteMcpConnection } from "./remote-mcp/connection.js";
+import { closeConnectionScope, remoteMcpConnection } from "./remote-mcp/connection.js";
 import { remoteMcpOAuth } from "./remote-mcp/oauth.js";
 import { remoteMcpCatalog } from "./remote-mcp/catalog.js";
 import { remoteMcpResources } from "./remote-mcp/resources.js";
@@ -267,11 +267,11 @@ export function remoteMcp(id, opts) {
             // Revocation and all finalizers start before any caller guard. Cleanup
             // retains its own bounded settlement even after the request has closed.
             const state = entryFor(ctx);
-            const release = Scope.closeUnsafe(state.scope, Exit.void);
+            const release = closeConnectionScope(state);
             const cacheClosing = closeCatalogCacheScope(ctx, id, cacheOwner);
             reset(state);
             const closing = runEdge(Effect.all([
-                release ?? Effect.void,
+                Effect.promise(() => release),
                 cacheClosing
                     ? Effect.raceAllFirst([
                         Effect.promise(() => cacheClosing),
@@ -481,9 +481,12 @@ export function remoteMcp(id, opts) {
             const provider = newProvider(ctx, stateFor(ctx));
             if ((yield authInvoke(provider, "operatorDisconnected", [])))
                 throw operatorDisconnectedError();
+            // Keep this separate from the disconnect read: invalidation and
+            // refresh can remove or replace tokens without changing the epoch.
+            // The SDK may otherwise send anonymously when its tokens() is empty.
             if (!(yield authInvoke(provider, "tokens", [])))
                 throw authRequiredError(ctx);
-            // That read decides whether the token is about to expire.
+            // That read also decides whether the token is about to expire.
             const due = provider.renewalDue();
             if (due !== undefined)
                 (yield authCall(renewBeforeCall, [ctx, due]));

package/dist/credential-contract.d.ts

@@ -39,7 +39,9 @@ export interface CredentialVault {
      * Encrypt downstream OAuth state (tokens, a registered client, a PKCE
      * verifier) before it enters storage. `purpose` is the storage key the value
      * is written under, so the result is bound to one connector, owner, and key.
-     * Without both `seal` and `open`, that state is stored as plaintext.
+     * Construction refuses a vault without both `seal` and `open` when any
+     * connector has `startAuth`, so that state is never left plaintext beside
+     * credentials this vault encrypts.
      */
     seal?(connectorId: string, purpose: string, plaintext: string, owner?: string): Promise<string>;
     /** Sign browser OAuth handoffs with a purpose-specific key; nothing is stored. */

package/dist/describe-config.d.ts

@@ -151,6 +151,7 @@ export interface ConnectaConfigDescription {
         };
         activity: {
             enabled: boolean;
+            operations?: true;
             readable?: boolean;
             deploymentId?: string;
             store?: {

package/dist/describe-config.js

@@ -269,6 +269,7 @@ export function describeConfig(input) {
                 ? {
                     enabled: true,
                     readable: typeof config.activity.store.list === "function",
+                    ...(config.activity.operations ? { operations: true } : {}),
                     ...(str(config.activity.deploymentId) !== undefined ? { deploymentId: config.activity.deploymentId } : {}),
                     store: {
                         kind: storeKind(activityStore),

package/dist/downstream-input.js

@@ -316,12 +316,21 @@ export class DownstreamElicitation {
                     // The nonce is spent even when the downstream failure would normally
                     // allow a retry. Preserve write reconciliation and auth prerequisites.
                     const echoed = downstreamArgumentEcho(self.options.requestScope);
+                    const recoveryError = { ...error };
+                    const freshRead = state.tool === "call_tool" &&
+                        error.code !== "provider_permission_denied" &&
+                        error.nextAction === undefined &&
+                        error.recovery === undefined &&
+                        error.writeOutcome !== "unknown" &&
+                        error.uncertainCall === undefined;
+                    if (freshRead)
+                        delete recoveryError.retry;
                     const structuredContent = {
                         ...result.structuredContent,
                         error: {
-                            ...error,
+                            ...recoveryError,
                             retryable: false,
-                            ...(state.tool === "call_tool" && error.nextAction === undefined && error.retry === undefined
+                            ...(freshRead
                                 ? {
                                     nextAction: {
                                         tool: state.tool,

package/dist/errors.d.ts

@@ -24,7 +24,7 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "downstream_o
  * change, and retries with the base `current` reports — repeating the same
  * call can never succeed, and waiting will not help either.
  */
- | "conflict" | "resource_template_ambiguous" | "resource_match_budget_exceeded" | "input_required_unsupported" | "input_required_invalid" | "input_required_limit" | "connector_call_failed";
+ | "conflict" | "resource_template_ambiguous" | "resource_match_budget_exceeded" | "unsupported_capability" | "input_required_unsupported" | "input_required_invalid" | "input_required_limit" | "connector_call_failed";
 /**
  * Every classification code connecta assigns: a connector's typed codes, the
  * executor's admission codes, and the refusals connecta frames itself.
@@ -285,6 +285,13 @@ export interface CallErrorDetails extends Partial<AuthorizationHandoff> {
     writeOutcome?: "unknown";
     /** The single model-facing entry point for every credential class. */
     nextAction?: {
+        tool: "skills";
+        arguments: Record<string, never>;
+        purpose: string;
+    } | {
+        action: "reconnect_host" | "contact_operator" | "inspect_capabilities" | "recover_result";
+        purpose: string;
+    } | {
         tool: "authorize_connector";
         arguments: {
             connector: string;

package/dist/errors.js

@@ -15,6 +15,7 @@ const CLASSIFICATION_CODE_TABLE = {
     conflict: true,
     resource_template_ambiguous: true,
     resource_match_budget_exceeded: true,
+    unsupported_capability: true,
     input_required_unsupported: true,
     input_required_invalid: true,
     input_required_limit: true,
@@ -337,6 +338,7 @@ const RETRYABLE_BY_CODE = {
     conflict: false,
     resource_template_ambiguous: false,
     resource_match_budget_exceeded: false,
+    unsupported_capability: false,
     input_required_unsupported: false,
     input_required_invalid: false,
     input_required_limit: false,

package/dist/execute.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, routeNames } from "./agent-routes.js";
 import { authCall, authFlow, authInvoke, authMethod } from "./auth/native.js";
 import { nativeRecovery } from "./native-recovery.js";
@@ -342,7 +345,9 @@ function serializedDiagnosticBytes(value) {
     }
 }
 function guestFailure(code, message, retryable = false) {
-    return new InvocationFailure({ code, message, retryable });
+    return new InvocationFailure(["unavailable", "unsupported_capability", "input_required_unsupported"].includes(code)
+        ? utilityRecovery(code, message, retryable)
+        : { code, message, retryable });
 }
 /**
  * E1/X11: bound typed host failure metadata, including JSON escapes, before transport.
@@ -724,7 +729,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 if (typeof id !== "string" ||
                     (!options && options !== undefined) ||
                     (options !== undefined && (typeof options !== "object" || Array.isArray(options)))) {
-                    throw guestFailure("invalid_args", "Use connecta.result(handleOrId, { page?, offset?, maxBytes? }).");
+                    throw new InvocationFailure(utilityRecovery("invalid_args", "Use connecta.result(handleOrId, { page?, offset?, maxBytes? })."));
                 }
                 const args = { ...(options ?? {}) };
                 if (Object.keys(args).some((key) => !["page", "offset", "maxBytes"].includes(key)) ||
@@ -737,7 +742,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                         (typeof args.offset !== "number" || !Number.isSafeInteger(args.offset) || args.offset < 0)) ||
                     (args.maxBytes !== undefined &&
                         (typeof args.maxBytes !== "number" || !Number.isSafeInteger(args.maxBytes) || args.maxBytes < 1))) {
-                    throw guestFailure("invalid_args", "Use connecta.result(handleOrId, { page?, offset?, maxBytes? }) with whole page/offset >= 0 and maxBytes >= 1; page and offset are mutually exclusive.");
+                    throw new InvocationFailure(utilityRecovery("invalid_args", "Use connecta.result(handleOrId, { page?, offset?, maxBytes? }) with whole page/offset >= 0 and maxBytes >= 1; page and offset are mutually exclusive."));
                 }
                 // A page must fit every shipped bridge even when the connector cap is raised.
                 args.maxBytes = Math.min(args.maxBytes ?? PROGRAM_RESULT_PAGE_BYTES, PROGRAM_RESULT_PAGE_BYTES);
@@ -768,6 +773,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 if (typeof skillName !== "string")
                     throw guestFailure("invalid_args", 'Use connecta.skill("usage") or connecta.skill("connector:<id>") with an exact skill name; the skills tool lists names.');
                 const skills = new SkillsRegistry(registry, baseUrl, {
+                    readOnly: limits.readOnly,
                     requestScope,
                     requestSignal: utilitySignal ?? hostAccessSignal,
                     onRead: (connector, source) => limits.resultDependencies?.push({
@@ -780,7 +786,11 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 });
                 return { name: skillName, format: "text", text: await skills.text(skillName) };
             },
-            catch: (err) => err instanceof ConnectorCallError ? guestFailure(err.code, err.message, err.code === "unavailable") : err,
+            catch: (err) => err instanceof SkillLookupError
+                ? new InvocationFailure(skillLookupRecovery(err.message))
+                : err instanceof ConnectorCallError
+                    ? guestFailure(err.code, "Skills are unavailable.", err.retryable)
+                    : err,
         }),
         read: (uri) => Effect.suspend(() => {
             const started = Date.now();
@@ -923,7 +933,10 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                             timeoutError: guestFailure("timeout", `connecta.${name} timed out.`),
                         })
                         : invoke;
-                    const settled = runEdge(guarded.pipe(Effect.catch((error) => {
+                    const operationEffect = activity?.recordOperation && ["search", "describe", "result", "skill"].includes(name)
+                        ? operationActivity(activity, registry, name, guarded)
+                        : guarded;
+                    const settled = runEdge(operationEffect.pipe(Effect.catch((error) => {
                         if (deadline && hostAccessSignal?.aborted)
                             return typedFailure(guestFailure("cancelled", `connecta.${name} was cancelled because the run ended.`));
                         if (deadline && error instanceof InvocationFailure && error.code === "timeout") {
@@ -1230,7 +1243,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             }
             return play(normalizeProgramSource(code), diagnostics, options.signal, requestScope, hostCalls, programWrites);
         });
-        return response.pipe(Effect.provideService(RequestScope, owner), Effect.map((unfinished) => {
+        return operationActivity(activity, registry, "program", response.pipe(Effect.provideService(RequestScope, owner), Effect.map((unfinished) => {
             // Every response, including intake refusals, crosses accounting and
             // exactly one envelope check at this operation boundary.
             const result = redactAgentOutput(sentSecrets, programWrites.finish(unfinished));
@@ -1241,7 +1254,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             if (result.content[0]?.type === "text")
                 result.content[0].text = JSON.stringify(result.structuredContent);
             return result;
-        }), Effect.catchDefect(Effect.fail), Effect.mapError((error) => redactAgentOutput(sentSecrets, error)));
+        }), Effect.catchDefect(Effect.fail), Effect.mapError((error) => redactAgentOutput(sentSecrets, error))), () => ({ ...hostCalls, failed: hostCalls.attempted - hostCalls.succeeded }));
     }));
 }
 /** An execution that never produced an ExecuteResult, as the model sees it. */

package/dist/executor-result.js

@@ -1,4 +1,4 @@
-import { META_ROUTES } from "./agent-routes.js";
+import { META_ROUTES } from "./route-names.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { msg } from "./errors.js";
 /** ~6k tokens. Sandbox code should filter data down before returning. */

package/dist/executors/quickjs-child.js

@@ -1,5 +1,5 @@
 import { prepareExecuteResultForTransport } from "../executor-result.js";
-import { InvocationFailure } from "../invocation.js";
+import { InvocationFailure } from "../invocation-failure.js";
 import { msg } from "../errors.js";
 import { MAX_QUICKJS_IPC_BYTES, MAX_QUICKJS_RESULT_BYTES, QUICKJS_RESULT_CHUNK_CHARS, MAX_QUICKJS_HOST_RPC_BYTES, serializedBytes, stringifyBounded, } from "./quickjs-protocol.js";
 import { executeQuickJs, prepareQuickJs } from "./quickjs-runtime.js";

package/dist/executors/quickjs-runtime.js

@@ -9,7 +9,7 @@ import { utf8Length } from "../bytes.js";
 // continuations from a host-side loop. Values cross the boundary as JSON, so
 // provider args/results must be JSON-serializable.
 import { getQuickJS } from "quickjs-emscripten";
-import { InvocationFailure } from "../invocation.js";
+import { InvocationFailure } from "../invocation-failure.js";
 import { msg } from "../errors.js";
 import { withoutProgramTerminator } from "../program-source.js";
 import { hostCallLabel, MAX_QUICKJS_LOG_TRANSPORT_BYTES, serializedBytes } from "./quickjs-protocol.js";

package/dist/executors/quickjs.js

@@ -18,7 +18,7 @@ import { fileURLToPath } from "node:url";
 import { Deferred, Duration, Effect, Exit, Schedule, Scope } from "effect";
 import { AdmissionController, ExecutorAdmissionError, ExecutorExecutionError } from "../executor-admission.js";
 import { msg } from "../errors.js";
-import { InvocationFailure } from "../invocation.js";
+import { InvocationFailure } from "../invocation-failure.js";
 import { brandExecutor } from "../executor-contract.js";
 import { MAX_EXECUTE_LOG_CHARS } from "../executor-result.js";
 import { admit } from "../runtime/admission.js";