@oomol-lab/open-connector 1.8.0 → 1.9.0

package/assets/open-connector/migrations/0018_connection_retirement.sql

@@ -0,0 +1,17 @@
+create table connection_retirements (
+  service text not null,
+  connection_name text not null,
+  generation text not null,
+  primary key (service, connection_name)
+);
+
+-- Unfenced local consent must restart; stored credentials remain intact.
+delete from oauth_states;
+alter table oauth_states add column service text;
+alter table oauth_states add column connection_name text;
+create index oauth_states_connection on oauth_states (service, connection_name);
+alter table connection_requests add column connection_name text;
+create index connection_requests_connection on connection_requests (service, connection_name);
+update connection_requests set phase = 'completed', status = 'failed', value = null,
+  error_code = 'authorization_fence_required', error_message = 'Restart authorization after upgrading.'
+  where kind = 'local' and phase <> 'completed';

package/assets/open-connector/migrations/postgresql/0018_connection_retirement.sql

@@ -0,0 +1,17 @@
+create table connection_retirements (
+  service text not null,
+  connection_name text not null,
+  generation text not null,
+  primary key (service, connection_name)
+);
+
+-- Unfenced local consent must restart; stored credentials remain intact.
+delete from oauth_states;
+alter table oauth_states add column service text;
+alter table oauth_states add column connection_name text;
+create index oauth_states_connection on oauth_states (service, connection_name);
+alter table connection_requests add column connection_name text;
+create index connection_requests_connection on connection_requests (service, connection_name);
+update connection_requests set phase = 'completed', status = 'failed', value = null,
+  error_code = 'authorization_fence_required', error_message = 'Restart authorization after upgrading.'
+  where kind = 'local' and phase <> 'completed';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-connector",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Embeddable Open Connector runtime for Node.js and Bun.",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,33 +15,34 @@
     }
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1111.0",
+    "@aws-sdk/client-s3": "^3.1151.0",
     "@cfworker/json-schema": "^4.1.1",
-    "@hono/node-server": "^2.0.10",
-    "@modelcontextprotocol/client": "^2.0.0",
-    "@modelcontextprotocol/server": "^2.0.0",
-    "@scalar/hono-api-reference": "^0.11.7",
+    "@hono/node-server": "^2.1.5",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/server": "^2.3.1",
+    "@scalar/hono-api-reference": "^0.12.12",
     "ali-oss": "^6.23.0",
     "busboy": "^1.6.0",
-    "fast-xml-builder": "^1.3.0",
-    "fast-xml-parser": "^5.10.1",
-    "fast-xml-validator": "^1.4.1",
-    "hono": "^4.13.5",
-    "imapflow": "^1.7.8",
-    "jose": "^6.2.3",
-    "mailparser": "^3.9.28",
-    "mdast-util-from-markdown": "^2.0.3",
+    "fast-xml-builder": "^1.3.1",
+    "fast-xml-parser": "^5.11.2",
+    "fast-xml-validator": "^1.4.2",
+    "hono": "^4.13.13",
+    "iconv-lite": "^0.7.3",
+    "imapflow": "^2.4.0",
+    "jose": "^6.2.12",
+    "mailparser": "^3.9.38",
+    "mdast-util-from-markdown": "^2.1.0",
     "mdast-util-gfm": "^3.1.0",
-    "mdast-util-to-markdown": "^2.1.2",
+    "mdast-util-to-markdown": "^2.2.0",
     "micromark-extension-gfm": "^3.0.0",
     "minisearch": "^7.2.0",
-    "mqtt": "^5.15.2",
-    "nodemailer": "^9.1.1",
-    "pg": "^8.23.0",
-    "pino": "^10.3.1",
+    "mqtt": "^5.16.0",
+    "nodemailer": "^10.1.0",
+    "pg": "^8.23.1",
+    "pino": "^10.4.0",
     "rss-parser": "^3.13.0",
-    "yaml": "^2.9.0",
-    "zod": "^4.6.5"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
   },
   "engines": {
     "node": ">=22.18.0"

package/src/connection-service.d.ts

@@ -1,7 +1,8 @@
 import type { CatalogStore } from "./catalog-store.ts";
+import type { ProviderHttpDispatchOptions } from "./core/provider-http-dispatch.ts";
 import type { AuthType, CredentialProfile, ResolvedCredential, RuntimeLogger } from "./core/types.ts";
 import type { MarketplacePricing, MarketplaceService } from "./marketplace/marketplace-service.ts";
-import type { IOAuthCredentialRefresher } from "./oauth/oauth-credential-refresh-service.ts";
+import type { IOAuthCredentialRefresher, OAuthRevocationOutcome } from "./oauth/oauth-credential-refresh-service.ts";
 import type { IProviderLoader } from "./providers/provider-loader.ts";
 export declare const defaultConnectionName = "default";
 /**
@@ -13,6 +14,8 @@ export interface ConnectionSummary {
     connectionName: string;
     authType: AuthType | "marketplace";
     configured: boolean;
+    /** Known credential state; token expiry alone does not require new consent when refresh is available. */
+    status?: "active" | "reauth_required";
     virtual: boolean;
     default: boolean;
     profile: CredentialProfile;
@@ -40,6 +43,7 @@ export interface ConnectWithoutAuthInput {
     connectionName?: string;
 }
 export interface ConnectionServiceOptions {
+    providerHttpDispatch?: ProviderHttpDispatchOptions;
     catalog: CatalogStore;
     oauthCredentials?: IOAuthCredentialRefresher;
     providerLoader: IProviderLoader;
@@ -75,10 +79,22 @@ export interface StoredLocalConnection {
     connectionName: string;
     credential: ResolvedCredential;
 }
+export interface DisconnectOptions {
+    /**
+     * `true` also revokes the OAuth grant at the provider once the credential is
+     * deleted here, and the answer's `revoked` says how that went. Omitted or
+     * `false` (the default) deletes the credential alone and answers `skipped` —
+     * the right call when another connection of the same account shares the
+     * grant at the provider, where revoking would end the one that stays.
+     */
+    revoke?: boolean;
+}
 export interface DisconnectedConnectionSummary {
     service: string;
     connectionName: string;
     configured: false;
+    /** What the disconnect did about the grant at the provider; see {@link OAuthRevocationOutcome}. */
+    revoked: OAuthRevocationOutcome;
 }
 export type ExecutionConnection = LocalExecutionConnection | MarketplaceExecutionConnection | SaasExecutionConnection;
 interface LocalExecutionConnection {
@@ -100,6 +116,8 @@ interface SaasExecutionConnection {
  */
 export interface IConnectionStore {
     get(service: string, connectionName: string): Promise<StoredConnection | undefined>;
+    getRetirementGeneration(service: string, connectionName: string): Promise<string>;
+    setIfCurrentGeneration(service: string, connectionName: string, credential: ResolvedCredential, retirementGeneration: string): Promise<StoredLocalConnection | undefined>;
     set(service: string, connectionName: string, credential: ResolvedCredential): Promise<StoredLocalConnection>;
     updateCredential(input: StoredLocalConnection, refresh?: boolean): Promise<boolean>;
     delete(service: string, connectionName: string): Promise<void>;
@@ -115,6 +133,7 @@ type OAuthCredential = Extract<ResolvedCredential, {
  * run public actions without configuration.
  */
 export declare class ConnectionService {
+    private readonly providerHttpDispatch?;
     private readonly catalog;
     private readonly oauthCredentialRefreshes;
     private readonly oauthCredentials?;
@@ -152,7 +171,9 @@ export declare class ConnectionService {
     connectWithCustomCredential(service: string, input: ConnectWithCredentialInput): Promise<ConnectionSummary>;
     setOAuthCredential(service: string, credential: Extract<ResolvedCredential, {
         authType: "oauth2";
-    }>, connectionNameInput?: string, signal?: AbortSignal): Promise<ConnectionSummary>;
+    }>, connectionNameInput?: string, signal?: AbortSignal, retirementGeneration?: string): Promise<ConnectionSummary>;
+    /** Capture the durable disconnect fence before sending the user to the provider. */
+    getRetirementGeneration(service: string, connectionName?: string): Promise<string>;
     prepareOAuthCredential(service: string, credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredential>;
     private selectStoredConnection;
     getStoredConnection(id: string): Promise<StoredConnection>;
@@ -161,7 +182,16 @@ export declare class ConnectionService {
     private createManagedConnectionSummary;
     private saveCredential;
     private replaceCredential;
-    disconnect(service: string, connectionNameInput?: string): Promise<ConnectionSummary | DisconnectedConnectionSummary>;
+    disconnect(service: string, connectionNameInput?: string, options?: DisconnectOptions): Promise<(ConnectionSummary & {
+        revoked: OAuthRevocationOutcome;
+    }) | DisconnectedConnectionSummary>;
+    /**
+     * End the grant at the provider once its credential is deleted here, so a
+     * disconnected provider does not keep an app it no longer sees authorized.
+     * Best effort by design: a provider that refuses or cannot be reached is
+     * logged, and the connection the caller asked to remove is gone either way.
+     */
+    private revokeDeletedCredential;
     private createConfiguredConnectionSummary;
     private createStoredConnectionSummary;
     private createNoAuthConnectionSummary;

package/src/connection-service.js

@@ -1,6 +1,6 @@
 import { normalizeCredentialValues } from "./core/credential-fields.js";
 import { apiKeyCredentialFields } from "./core/provider-setup.js";
-import { providerFetch } from "./providers/provider-runtime.js";
+import { providerFetch, ProviderDispatchRequestError, withProviderHttpDispatchResult, } from "./providers/provider-runtime.js";
 export const defaultConnectionName = "default";
 const connectionNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
 /**
@@ -10,6 +10,7 @@ const connectionNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
  * run public actions without configuration.
  */
 export class ConnectionService {
+    providerHttpDispatch;
     catalog;
     oauthCredentialRefreshes = new Map();
     oauthCredentials;
@@ -18,6 +19,7 @@ export class ConnectionService {
     logger;
     marketplace;
     constructor(input) {
+        this.providerHttpDispatch = input.providerHttpDispatch;
         this.catalog = input.catalog;
         this.oauthCredentials = input.oauthCredentials;
         this.providerLoader = input.providerLoader;
@@ -211,12 +213,19 @@ export class ConnectionService {
         };
         return this.saveCredential(provider, credential, input);
     }
-    async setOAuthCredential(service, credential, connectionNameInput, signal) {
-        const storedCredential = await this.prepareOAuthCredential(service, credential, signal);
+    async setOAuthCredential(service, credential, connectionNameInput, signal, retirementGeneration) {
         const connectionName = normalizeConnectionName(connectionNameInput);
-        const stored = await this.store.set(service, connectionName, storedCredential);
+        const generation = retirementGeneration ?? (await this.store.getRetirementGeneration(service, connectionName));
+        const storedCredential = await this.prepareOAuthCredential(service, credential, signal);
+        const stored = await this.store.setIfCurrentGeneration(service, connectionName, storedCredential, generation);
+        if (!stored)
+            throw new ConnectionError("connection_retired", "The connection was disconnected during authorization.");
         return this.createStoredConnectionSummary(this.getAvailableProvider(service), stored.id, connectionName, storedCredential);
     }
+    /** Capture the durable disconnect fence before sending the user to the provider. */
+    async getRetirementGeneration(service, connectionName) {
+        return this.store.getRetirementGeneration(service, normalizeConnectionName(connectionName));
+    }
     async prepareOAuthCredential(service, credential, signal) {
         const provider = this.getAvailableProvider(service);
         if (!this.supportsAuth(provider, "oauth2")) {
@@ -267,9 +276,7 @@ export class ConnectionService {
             };
         const credential = stored.credential;
         return {
-            status: credential.authType === "oauth2" && !credential.refreshToken && isOAuthCredentialExpired(credential)
-                ? "reauth_required"
-                : "active",
+            status: "active",
             ...this.createConfiguredConnectionSummary(this.getProvider(stored.service), stored.id, stored.connectionName, credential),
             comment: credential.authType !== "no_auth" && typeof credential.metadata.connectionComment === "string"
                 ? credential.metadata.connectionComment
@@ -296,14 +303,62 @@ export class ConnectionService {
         }
         return { ...expected, credential };
     }
-    async disconnect(service, connectionNameInput) {
+    async disconnect(service, connectionNameInput, options = {}) {
         const connectionName = normalizeConnectionName(connectionNameInput);
+        // The credential is read before the delete and revoked after it: a delete the store
+        // refuses (a row bound to active Trigger subscriptions) then ends nothing at the provider,
+        // where revoking first would leave a dead grant behind a row that stays.
+        let stored;
+        let readFailed = false;
+        if (options.revoke === true) {
+            try {
+                stored = await this.store.get(service, connectionName);
+            }
+            catch (error) {
+                readFailed = true;
+                this.logger?.warn({ service, connectionName, error: describeError(error) }, "oauth token revocation skipped");
+            }
+        }
         await this.store.delete(service, connectionName);
+        const revoked = options.revoke !== true
+            ? "skipped"
+            : readFailed
+                ? "failed"
+                : await this.revokeDeletedCredential(service, connectionName, stored);
         const provider = this.catalog.providers.find((provider) => provider.service === service);
         if (provider && this.supportsAuth(provider, "no_auth")) {
-            return this.connectWithoutAuth(service, { connectionName });
+            return { ...(await this.connectWithoutAuth(service, { connectionName })), revoked };
+        }
+        return { service, connectionName, configured: false, revoked };
+    }
+    /**
+     * End the grant at the provider once its credential is deleted here, so a
+     * disconnected provider does not keep an app it no longer sees authorized.
+     * Best effort by design: a provider that refuses or cannot be reached is
+     * logged, and the connection the caller asked to remove is gone either way.
+     */
+    async revokeDeletedCredential(service, connectionName, stored) {
+        const refresher = this.oauthCredentials;
+        if (!refresher?.revoke) {
+            return "unsupported";
+        }
+        const logContext = { service, connectionName };
+        if (!stored || stored.source === "saas" || stored.credential.authType !== "oauth2") {
+            return "unsupported";
+        }
+        try {
+            const outcome = await refresher.revoke(service, stored.credential);
+            this.logger?.info({ ...logContext, revoked: outcome }, "oauth token revocation completed");
+            return outcome;
+        }
+        catch (error) {
+            this.logger?.warn({
+                ...logContext,
+                errorCode: error instanceof ConnectionError ? error.code : "oauth_token_revocation_failed",
+                error: describeError(error),
+            }, "oauth token revocation failed");
+            return "failed";
         }
-        return { service, connectionName, configured: false };
     }
     createConfiguredConnectionSummary(provider, id, connectionName, credential) {
         if (credential.authType === "no_auth") {
@@ -322,6 +377,11 @@ export class ConnectionService {
             connectionName,
             authType: credential.authType,
             configured: true,
+            status: credential.authType === "oauth2" &&
+                (credential.metadata.oauthReauthRequired === true ||
+                    (!credential.refreshToken && isOAuthCredentialExpired(credential)))
+                ? "reauth_required"
+                : "active",
             virtual: false,
             default: connectionName === defaultConnectionName,
             profile: credential.profile,
@@ -432,6 +492,9 @@ export class ConnectionService {
     }
     async resolveOAuthCredential(connection, credential) {
         const service = connection.service;
+        if (credential.metadata.oauthReauthRequired === true) {
+            throw new ConnectionError("oauth_reauth_required", `OAuth authorization is no longer valid. Reconnect ${service}.`);
+        }
         if (!isOAuthCredentialExpired(credential)) {
             return credential;
         }
@@ -459,7 +522,23 @@ export class ConnectionService {
     }
     async refreshOAuthCredential(connection, credential, refresher) {
         const { id, revision, service, connectionName } = connection;
-        const nextCredential = await refresher.refresh(service, credential);
+        let nextCredential;
+        try {
+            nextCredential = await withProviderHttpDispatchResult({ operation: "oauth", service, connectionId: id, connectionName }, () => refresher.refresh(service, credential), this.providerHttpDispatch);
+        }
+        catch (error) {
+            if (error instanceof ConnectionError && error.code === "oauth_reauth_required") {
+                // The revision fence prevents a late refusal from marking a replacement authorization as expired.
+                await this.store.updateCredential({
+                    id,
+                    revision,
+                    service,
+                    connectionName,
+                    credential: { ...credential, metadata: { ...credential.metadata, oauthReauthRequired: true } },
+                }, true);
+            }
+            throw error;
+        }
         const updated = await this.store.updateCredential({
             id,
             revision,
@@ -475,7 +554,7 @@ export class ConnectionService {
     async runCredentialValidator(service, validate, signal) {
         this.assertNotCancelled(signal);
         try {
-            const result = (await validate()) ?? {};
+            const result = (await withProviderHttpDispatchResult({ operation: "credential_validation", service }, validate, this.providerHttpDispatch)) ?? {};
             this.assertNotCancelled(signal);
             return result;
         }
@@ -483,6 +562,8 @@ export class ConnectionService {
             if (signal?.aborted) {
                 throw cancelledConnectionError();
             }
+            if (error instanceof ProviderDispatchRequestError)
+                throw error;
             throw new ConnectionError("credential_verification_failed", error instanceof Error ? error.message : `${service} credential verification failed.`);
         }
     }
@@ -595,6 +676,9 @@ export class ConnectionError extends Error {
         this.code = code;
     }
 }
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function cancelledConnectionError() {
     return new ConnectionError("connection_cancelled", "Credential validation was cancelled.");
 }

package/src/core/aws-sigv4.d.ts

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 /**
  * Access key material used by AWS Signature Version 4.
  */
@@ -72,3 +73,5 @@ export declare function buildCanonicalHeaders(headers: Headers): Record<string,
  * SHA-256 hex digest used by SigV4 payload and string-to-sign hashes.
  */
 export declare function sha256Hex(value: string | Uint8Array): string;
+/** Compute the hexadecimal HMAC-SHA256 signature of a UTF-8 message. */
+export declare function hmacHex(key: string | Buffer, value: string): string;

package/src/core/aws-sigv4.js

@@ -175,7 +175,8 @@ function signCanonicalRequest(secretAccessKey, scope, canonicalRequest) {
 function hmacSha256(key, value) {
     return createHmac("sha256", key).update(value).digest();
 }
-function hmacHex(key, value) {
+/** Compute the hexadecimal HMAC-SHA256 signature of a UTF-8 message. */
+export function hmacHex(key, value) {
     return createHmac("sha256", key).update(value).digest("hex");
 }
 function collapseHeaderWhitespace(value) {

package/src/core/cast.d.ts

@@ -108,11 +108,16 @@ export declare function optionalNumberLike(value: unknown): number | undefined;
 /**
  * Return an integer from a number or numeric string. Examples:
  * `integer("2", "count") => 2`, `integer("x", "count")` throws.
+ *
+ * A blank or whitespace-only string is rejected rather than parsed as zero.
  */
 export declare function integer(value: unknown, fieldName: string, createError?: CastErrorFactory): number;
 /**
  * Return an integer from a number or numeric string when present. Examples:
  * `optionalIntegerLike("2", "count") => 2`, `optionalIntegerLike("", "count") => undefined`.
+ *
+ * A blank or whitespace-only string is reported as missing rather than parsed, because
+ * `Number(" ")` is `0` and a blank field would otherwise surface as a real zero.
  */
 export declare function optionalIntegerLike(value: unknown, fieldName: string, createError?: CastErrorFactory): number | undefined;
 /**

package/src/core/cast.js

@@ -207,9 +207,11 @@ export function optionalNumberLike(value) {
 /**
  * Return an integer from a number or numeric string. Examples:
  * `integer("2", "count") => 2`, `integer("x", "count")` throws.
+ *
+ * A blank or whitespace-only string is rejected rather than parsed as zero.
  */
 export function integer(value, fieldName, createError = (message) => new CastError(message)) {
-    const parsed = typeof value === "number" ? value : typeof value === "string" && value !== "" ? Number(value) : NaN;
+    const parsed = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
     if (Number.isInteger(parsed)) {
         return parsed;
     }
@@ -218,9 +220,12 @@ export function integer(value, fieldName, createError = (message) => new CastErr
 /**
  * Return an integer from a number or numeric string when present. Examples:
  * `optionalIntegerLike("2", "count") => 2`, `optionalIntegerLike("", "count") => undefined`.
+ *
+ * A blank or whitespace-only string is reported as missing rather than parsed, because
+ * `Number(" ")` is `0` and a blank field would otherwise surface as a real zero.
  */
 export function optionalIntegerLike(value, fieldName, createError = (message) => new CastError(message)) {
-    if (value == null || value === "") {
+    if (value == null || (typeof value === "string" && value.trim() === "")) {
         return undefined;
     }
     return integer(value, fieldName, createError);

package/src/core/guarded-fetch.d.ts

@@ -1,3 +1,4 @@
+import type { GuardedHttpDispatcher } from "./provider-http-dispatch.ts";
 /**
  * Single resolved address returned by a DNS lookup, mirroring the shape of
  * `node:dns` `lookup(hostname, { all: true })` entries.
@@ -12,6 +13,8 @@ export interface ResolvedAddress {
  */
 export type GuardedFetchDnsLookup = (hostname: string) => Promise<ResolvedAddress[]>;
 export interface GuardedFetchOptions {
+    /** Optional dispatcher at the screened raw-transport seam; every redirect hop passes through it. */
+    dispatchAttempt?: GuardedHttpDispatcher;
     /**
      * Base transport issuing the actual requests. Defaults to the global fetch,
      * resolved per call so test stubs installed later still apply.

package/src/core/guarded-fetch.js

@@ -77,6 +77,8 @@ export const crossOriginSafeHeaders = new Set([
 const bodyHeaders = ["content-encoding", "content-language", "content-length", "content-location", "content-type"];
 /** Base transport behind each guarded fetch (undefined = global fetch) so re-wrapping never stacks guards. */
 const guardedFetchBases = new WeakMap();
+/** Retain admission when a caller replaces the egress policy without stacking guards. */
+const guardedFetchDispatchers = new WeakMap();
 let defaultLookupOverridden = false;
 let defaultLookupOverride = null;
 let nodeDnsLookupPromise;
@@ -134,17 +136,33 @@ export function unwrapGuardedFetch(fetcher) {
  */
 export function createGuardedFetch(options = {}) {
     const baseFetch = unwrapGuardedFetch(options.fetch);
+    const dispatchAttempt = options.dispatchAttempt ?? (options.fetch && guardedFetchDispatchers.get(options.fetch));
     const createError = options.createError ?? ((message) => new TypeError(message));
     const maxRedirects = options.maxRedirects ?? defaultMaxRedirects;
     const guardedFetch = (async (input, init) => {
         const transport = baseFetch ?? globalThis.fetch;
+        const requestId = dispatchAttempt ? crypto.randomUUID() : "";
+        let redirectHop = 0;
         const fetchTransport = async (transportInput, transportInit) => {
-            try {
-                return await transport(transportInput, transportInit);
-            }
-            catch (error) {
-                throw options.mapTransportError?.(error) ?? error;
-            }
+            const send = async () => {
+                try {
+                    return await transport(transportInput, transportInit);
+                }
+                catch (error) {
+                    throw options.mapTransportError?.(error) ?? error;
+                }
+            };
+            const transportRequest = transportInput instanceof Request ? transportInput : undefined;
+            return dispatchAttempt
+                ? dispatchAttempt(Object.freeze({
+                    requestId,
+                    redirectHop,
+                    origin: url.origin,
+                    method: (transportInit?.method ?? transportRequest?.method ?? "GET").toUpperCase(),
+                }), transportInit?.signal ?? transportRequest?.signal ?? undefined, send, async () => {
+                    await guardHop(url.toString(), "request URL");
+                })
+                : send();
         };
         const allowPrivateNetwork = typeof options.allowPrivateNetwork === "function"
             ? options.allowPrivateNetwork()
@@ -166,12 +184,17 @@ export function createGuardedFetch(options = {}) {
         let url = await guardHop(request?.url ?? (input instanceof URL ? input.href : String(input)), "request URL");
         const redirectMode = init?.redirect ?? request?.redirect ?? "follow";
         if (redirectMode !== "follow") {
-            return fetchTransport(input, init);
+            // Keep the screened URL and method stable while admission is queued. A
+            // caller may otherwise mutate a URL or RequestInit before transport runs.
+            return dispatchAttempt
+                ? fetchTransport(request ?? (input instanceof URL ? new URL(url) : url.toString()), init ? { ...init } : init)
+                : fetchTransport(input, init);
         }
         let method = (init?.method ?? request?.method ?? "GET").toUpperCase();
         const headers = new Headers(init?.headers ?? request?.headers);
         let body = init?.body !== undefined ? init.body : request?.body;
         for (let redirects = 0;; redirects++) {
+            redirectHop = redirects;
             const response = redirects === 0
                 ? request
                     ? await fetchTransport(new Request(request, { ...init, redirect: "manual" }))
@@ -229,6 +252,7 @@ export function createGuardedFetch(options = {}) {
         }
     });
     guardedFetchBases.set(guardedFetch, baseFetch);
+    guardedFetchDispatchers.set(guardedFetch, dispatchAttempt);
     return guardedFetch;
 }
 /**

package/src/core/json-schema.js

@@ -207,7 +207,13 @@ export const jsonSchema = {
         return withOptions({ oneOf: schemas }, options);
     },
     nullable(schema) {
-        return { anyOf: [schema, { type: "null" }] };
+        const nullableSchema = { anyOf: [schema, { type: "null" }] };
+        // Tool schemas and the action guide read a property's description from the
+        // property schema itself, so surface the inner description on the wrapper.
+        if (typeof schema.description === "string") {
+            nullableSchema.description = schema.description;
+        }
+        return nullableSchema;
     },
     ref(ref, options = {}) {
         return withOptions({ $ref: ref }, options);

package/src/core/provider-http-dispatch.d.ts

@@ -0,0 +1,82 @@
+/** Runtime-owned identity. Never populate these fields from action input or HTTP headers. */
+export interface ProviderDispatchContext {
+    readonly operation: "runtime" | "action" | "proxy" | "trigger" | "credential_validation" | "oauth";
+    readonly service?: string;
+    readonly actionId?: string;
+    readonly executionId?: string;
+    readonly connectionId?: string;
+    /** Alias from the resolved stored connection, not the caller's requested alias. */
+    readonly connectionName?: string;
+}
+/** Opaque authority supplied by the embedding host, independently of provider credentials. */
+export interface ProviderDispatchAuthority {
+    readonly workspaceId?: string;
+    readonly connectionLineageId?: string;
+    readonly workClass?: string;
+}
+/** A screened HTTP hop. URLs, paths, queries, headers and bodies are deliberately absent. */
+export interface ProviderHttpAttempt {
+    readonly attemptId: string;
+    readonly requestId: string;
+    readonly redirectHop: number;
+    readonly method: string;
+    readonly origin: string;
+    readonly context: ProviderDispatchContext;
+    readonly authority: ProviderDispatchAuthority;
+}
+/** Transport failures may have reached the provider; they are never evidence for a credit refund. */
+export type ProviderHttpAttemptResult = {
+    readonly kind: "response";
+    readonly status: number;
+    readonly retryAfter?: string;
+} | {
+    readonly kind: "transport_error";
+} | {
+    readonly kind: "not_dispatched";
+    readonly reason: "cancelled" | "dispatch_failed";
+};
+export interface ProviderHttpPermit {
+    readonly allow: true;
+    /** Awaited immediately before transport. Persist dispatch commitment here; failures deny egress. */
+    readonly onDispatch?: () => void | Promise<void>;
+    /** Started exactly once after a permit is returned; never awaited before returning the transport outcome. */
+    readonly onResult?: (result: ProviderHttpAttemptResult) => void | Promise<void>;
+}
+export interface ProviderHttpDenial {
+    readonly allow: false;
+    /** Retry-After delay in whole seconds. */
+    readonly retryAfterSeconds?: number;
+}
+export interface ProviderHttpDispatchOptions {
+    /** Await admission to delay a request, or return a denial. Honour the signal while queued. */
+    readonly beforeAttempt: (attempt: ProviderHttpAttempt, signal: AbortSignal | undefined) => ProviderHttpPermit | ProviderHttpDenial | Promise<ProviderHttpPermit | ProviderHttpDenial>;
+    /** Resolve workspace/lineage authority from runtime identity, never request credentials. */
+    readonly bindAuthority?: (context: ProviderDispatchContext) => ProviderDispatchAuthority | Promise<ProviderDispatchAuthority>;
+    /** Feedback failure leaves the attempt spent/unknown. This observer cannot change the transport result. */
+    readonly onFeedbackError?: (attempt: ProviderHttpAttempt) => void | Promise<void>;
+}
+export interface GuardedHttpAttempt {
+    readonly requestId: string;
+    readonly redirectHop: number;
+    readonly method: string;
+    readonly origin: string;
+}
+export type GuardedHttpDispatcher = (attempt: GuardedHttpAttempt, signal: AbortSignal | undefined, transport: () => Promise<Response>, revalidate: () => Promise<void>) => Promise<Response>;
+/** Safe retryable denial, including hook/readiness failures; it contains no callback error details. */
+export declare class ProviderHttpDispatchError extends Error {
+    readonly retryAfterSeconds?: number;
+    constructor(retryAfterSeconds?: number);
+}
+/**
+ * Bind a hook to asynchronous provider work. Nested scopes inherit the configured hook;
+ * concurrent requests stay isolated. Standalone providerFetch users can opt in here too.
+ */
+export declare function withProviderHttpDispatch<T>(context: ProviderDispatchContext, run: () => T, options?: ProviderHttpDispatchOptions): T;
+/**
+ * A provider invocation boundary: retain the original denial even if provider code catches,
+ * replaces, or converts it to a result. Each invocation owns its marker, so a sibling's
+ * denial cannot override another invocation's successful retry or fallback.
+ */
+export declare function runWithProviderHttpDispatch<T>(context: ProviderDispatchContext, run: () => T | Promise<T>, options?: ProviderHttpDispatchOptions): Promise<T>;
+/** Called only at the screened raw-transport seam, once for every HTTP attempt and redirect hop. */
+export declare const dispatchProviderHttpAttempt: GuardedHttpDispatcher;