@zackbart/connecta 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this package are documented here.
 
+## 0.31.0 — 2026-10-09
+
+Connecta 0.31.0 lets the auth mode choose how Stripe, Notion, Cloudflare and Vercel connect (#801). `auth: { type: "oauth" }` connects the vendor's hosted MCP server, OAuth only. A key connects Connecta's own REST connector with an operator-managed credential: Stripe `apiKey`, Notion `token`, Cloudflare `apiToken` or `globalApiKey`, and Vercel `token`. Each implementation is now complete on its own. This replaces the 0.29 split, in which the hosted server owned writes and the REST surface refused them, so a Cloudflare API token could not change a DNS record. Decision record 0005 explains the choice. Deployments that use none of these four providers need no changes.
+
+The timing comes from Stripe. Its hosted MCP server stops accepting `sk_` secret keys and untagged `rk_` restricted keys on 2026-10-31, so a deployment that sends one of those keys to `mcp.stripe.com` loses Stripe on that date. Upgrade before then. Stripe still documents agent-tagged restricted keys for its MCP server, but Connecta's hosted Stripe connection is now OAuth only, and every Stripe key, tagged or not, uses the REST connector. For these four providers, Connecta no longer sends a bearer key, literal header or operator credential to the hosted MCP server. Other hosted providers, such as RevenueCat, Mixpanel and GitHub, are unchanged.
+
+Every key connector serves the same four tools. `<vendor>_api_search` and `<vendor>_api_details` read an operation index compiled from the vendor's pinned OpenAPI document. `<vendor>_api_read` and `<vendor>_api_write` check each call's path and parameters against that index before sending it, and return `{ status, data, page? }`. The read tool admits GET plus reviewed read-only POSTs such as Stripe's invoice preview, Cloudflare analytics and Vercel observability queries. Each vendor keeps a few named tools. Stripe POST writes send the caller's `idempotencyKey`, or a generated one, as `Idempotency-Key` and return it; DELETE writes send none. When a deadline interrupts one of those POST writes, or its outcome is otherwise unknown, `uncertainCall.recovery` carries the generated key, or a caller-supplied key of at most 128 characters. A longer caller key is still sent to Stripe but not echoed there, since the caller already has it. Every Stripe request, v1 and v2, sends `Stripe-Version: 2026-09-30.endive`, the pinned index's version, whatever the account's default API version. Response shapes and accepted parameters follow that version, so check the fields programs rely on with `stripe_api_details`. Stripe's `connectedAccount` now works with an operator-managed key. `npm run providers:check` reports when a pinned index falls behind the vendor's live document.
+
+Most existing configurations of these providers need edits. `auth` is now required, with no default, and omitting it throws an error that lists the valid types. `surface` is removed from Notion, Vercel and Cloudflare, along with Cloudflare `authentication` and its `credential` override. Stripe loses literal `headers` auth and hosted `credential` auth. Cloudflare bearer-token auth to `mcp.cloudflare.com` is removed, so those deployments move to `apiToken` and its REST tools. A credential stored under the same connector id carries over; run its Test action after upgrading.
+
+Tool names change on the key paths. Cloudflare's `cloudflare_api_get` and `cloudflare_api_mutate` become `cloudflare_api_read` and `cloudflare_api_write`. `verify_api_token` and `verify_global_api_key` become `verify_credential`. Cloudflare's 23 hand-written reads give way to `cloudflare_api_read`, which returns unprojected results. Vercel's `vercel_api_get` and `vercel_api_mutate` become `vercel_api_read` and `vercel_api_write`, and `verify_project_domain`, `remove_project_domain` and `delete_deployment` are removed. Notion's token connector drops eight `integration_*` tools in favor of the generic ones. Stripe keeps its tool names with Connecta's contracts, but natural-language Sigma, metrics, docs search, the planner, reports and feedback exist only on the OAuth connection.
+
+Several exports are removed. Cloudflare loses `CloudflareApiOptions`, `CloudflareMcpOptions`, `CloudflareConnectionOptions` and `CloudflareAuthentication`, plus `CLOUDFLARE_DNS_RECORD_TYPES` and `CLOUDFLARE_CONTENT_DNS_RECORD_TYPES`. Notion and Vercel lose their `ApiOptions`, `McpOptions` and `ConnectionOptions` types, and Stripe loses `StripeHeaderOptions`. Each `<Vendor>Options` is now a union of per-auth types, such as `StripeApiKeyOptions`, `NotionTokenOptions`, `VercelTokenOptions` and `CloudflareGlobalApiKeyOptions`.
+
+A Cloudflare Global API Key reaches every account and zone its user can reach. `auth: { type: "globalApiKey" }` therefore requires `pin: { accountIds, zoneIds }` unless the configuration states `unpinned: true`. It never writes `/user` or `/memberships`. Pins deny by default and also apply to GraphQL tags and list results. An operation that names no account or zone is refused unless it was reviewed as safe. Pins are optional for scoped API tokens. A Global API Key cannot reach R2.
+
+Every key connector applies one reviewed value-safety table. No REST tool response, success or error, returns a credential that grants access to the vendor or a third party, or a stored secret value. Operations that mint or hand out credentials are refused before they are sent. Stored secrets read as `"[redacted]"`. URLs that act as capabilities keep only their scheme and host, or lose their signing parameters. Reviewed operations withhold the vendor's error text unless their review keeps it. Results therefore lose fields they used to return. Stripe withholds client secrets, webhook signing secrets, Issuing card numbers and CVCs, and Checkout Session URLs other than those of guest payment sessions. Notion strips the signatures from pre-signed file URLs, so a returned file URL no longer downloads. Vercel returns `"[redacted]"` for environment values and header rule values. Cloudflare redacts Hyperdrive passwords, dispatch binding values and transform-rule header values. The guarantee assumes an honest vendor server and covers only the REST key connectors. Secrets that people type into free text, names or identifiers are out of scope. Hosted OAuth connections fall outside it: they return what the vendor's server returns, under Connecta's existing credential and `writeOnly` redaction.
+
+The four provider entries now carry both transports and a pinned index. Measured gzip, Stripe grows from 171 KB to 243 KB, Notion from 191 KB to 216 KB, Vercel from 190 KB to 231 KB and Cloudflare from 193 KB to 338 KB, all within their stated caps. Vercel admits only reviewed and approved MCP clients to its hosted server. If it refuses authorization for that reason, the deployment needs Vercel's approval or a token connector. Vercel's hosted connection now lists its four environment variable tools. The two that can return decrypted values are classified as writes. Cloudflare's hosted `execute` is always a write, so a read-only pool on a Cloudflare OAuth connector reaches only `search`. Use an API token for read-only API access. Agent evals against fake vendors for all four providers are planned. `documentation/provider-auth-migration.md` gives the step-by-step migration for each provider.
+
+### Changed
+
+- **Breaking:** `cloudflare()` now requires `auth`, which selects the implementation. `auth: { type: "oauth" }` connects Cloudflare's hosted MCP server (`search` and `execute`), OAuth only; bearer-token and credential auth to `mcp.cloudflare.com` are removed. `auth: { type: "apiToken" }` and `auth: { type: "globalApiKey" }` connect Connecta's own REST connector to the v4 API with an operator-managed credential: `cloudflare_api_search` and `cloudflare_api_details` read a pinned Cloudflare API index (3,336 operations, deprecated ones dropped), `cloudflare_api_read` (GET plus 47 reviewed read-only POSTs such as analytics, Analytics Engine and Log Explorer SQL, and KV bulk get) and `cloudflare_api_write` check every call against that index before sending it and return `{ status, data, page? }` with the envelope unwrapped, and the named tools are `verify_credential`, `list_accounts`, `list_zones`, `graphql_query` (read-only, refuses mutations), and `cloudflare_api_upload`. `accountId` and `zoneId` fill path placeholders; `pin: { accountIds, zoneIds }` restricts every call by default deny (an operation naming no account or zone is refused unless reviewed safe), including GraphQL tags and list results, and is required for a Global API Key unless `unpinned: true`. A reviewed value-safety table derived from the pinned spec gives every credential-bearing operation a verdict: credential producers (API tokens, Access service tokens, R2 temporary credentials, signing keys, direct-upload URLs, and more) and payment secrets are refused, stored and embedded secrets and environment and plain-text binding values are redacted on every method and tool, and operations that take or return credentials withhold vendor error text; URL Scanner captures are refused; a pinned connector's GraphQL documents hold one query and only fragments it uses, and a key-name, typed-secret, and URL-credential heuristic backs it up; a Global API Key never writes `/user` or `/memberships`. `surface`, `authentication`, `credential` overrides, the API-token mutation refusals, `verify_api_token`, `verify_global_api_key` (now `verify_credential`), `cloudflare_api_get`, `cloudflare_api_mutate`, the 23 hand-written reads from `get_zone` and `list_dns_records` to `list_pages_domains` (use `cloudflare_api_read`), `CLOUDFLARE_DNS_RECORD_TYPES`, `CLOUDFLARE_CONTENT_DNS_RECORD_TYPES`, and the `CloudflareApiOptions`, `CloudflareMcpOptions`, `CloudflareConnectionOptions`, and `CloudflareAuthentication` types are removed. See the provider auth migration guide.
+- Record that the auth mode selects the provider implementation: OAuth uses the vendor's hosted MCP and keys use a Connecta REST connector, superseding the hosted MCP ownership rule for Stripe, Vercel, Cloudflare and Notion (decision record 0005). Each provider's change is its own entry.
+- **Breaking:** `notion()` now requires `auth`, which selects the implementation, and `surface` is removed. `auth: { type: "oauth" }` connects Notion's hosted MCP server as the signed-in user, OAuth only, with the same reviewed catalog. `auth: { type: "token" }` connects Connecta's REST connector to `api.notion.com` as an internal integration with an operator-managed token: `notion_api_search`, `notion_api_details`, `notion_api_read`, and `notion_api_write` reach every operation in a pinned Notion API index (with the sent `Notion-Version` pinned to it), check each call against it before sending, admit Notion's read-only POST queries on the read tool, and return `{ status, data, page? }`, where `page.in: "body"` marks a body-borne cursor, `page.path` names a view query's continuation, and `hasMore` without `next` marks a cursorless cut-off such as meeting notes' limit. The token connector keeps `integration_search`, `integration_get_page`, `integration_get_page_content`, `integration_get_data_source_schema`, `integration_query_data_source`, `integration_create_page`, and `integration_append_blocks` (which now also takes `checklist`); `integration_get_page_property`, `integration_get_database`, `integration_list_users`, `integration_get_self`, `integration_list_comments`, `integration_update_page_properties`, `integration_trash_page`, and `integration_add_comment` are removed in favor of the generic tools. Notion's OAuth token endpoints and multipart file sends are refused. Notion's reconciliation table is retired. `npm run providers:spec` accepts `options.versionHeader` for documents that carry their API version in a header parameter. See the provider auth migration guide.
+- **Breaking:** `stripe()` now requires `auth`, which selects the implementation. `auth: { type: "oauth" }` connects Stripe's hosted MCP server exactly as before, OAuth only. `auth: { type: "apiKey" }` with `mode` (and optional `connectedAccount`) connects Connecta's own REST connector to `api.stripe.com` with an operator-managed secret or restricted key: `stripe_api_search` and `stripe_api_details` read a pinned Stripe API index, `stripe_api_read` and `stripe_api_write` check every call against that index before sending it, form-encode v1 bodies, send v2 bodies as JSON, send `Stripe-Version: 2026-09-30.endive` (the pinned index's version) on every v1 and v2 request whatever the account's default API version, so response shapes and accepted parameters follow it (check them with `stripe_api_details`), return `{ status, data, page? }` with optional `select`, and on every POST write send the caller's `idempotencyKey` or a generated one as `Idempotency-Key` and return it (DELETE sends none); `get_stripe_account_info` and `get_balance_summary` are named reads. A key whose prefix contradicts `mode` is refused before any request, and `connectedAccount` now works with an operator-managed key. Literal `headers` and hosted `credential` auth are removed; omitting `auth` is refused with the valid types. Providers gain the `"dual"` kind, `variants()` accepts a nested discriminant such as `["auth", "type"]`, the operator UI shows whether a provider connector uses hosted MCP or REST, and `npm run providers:spec` compiles pinned OpenAPI documents into operation indexes that `check:providers-generated` checks offline and `providers:check` compares with the live document. A POST write's key also reaches the caller when the response body is lost or the call deadline interrupts it: `write_outcome_unknown` now carries `uncertainCall.recovery` with the generated key, or a caller-supplied key of at most 128 characters (a longer caller key is still sent to Stripe but not echoed, since the caller already has it). See the provider auth migration guide.
+- **Breaking:** `vercel()` now requires `auth`, which selects the implementation, and `surface` is removed. `auth: { type: "oauth" }` connects Vercel's hosted MCP server as before, OAuth only; it now also lists `filter_project_envs`, `get_project_env`, `create_project_env`, and `edit_project_env`, with the two value-returning reads reviewed as writes. `auth: { type: "token" }` with optional `teamId` and `baseUrl` connects Connecta's own REST connector to `api.vercel.com` with an operator-managed access token, complete on its own: `vercel_api_search` and `vercel_api_details` read Vercel's OpenAPI document pinned by content hash, `vercel_api_read` (GET plus reviewed read-only POSTs such as `POST /v2/observability/query`) and `vercel_api_write` check every call against that index before sending it, apply the default team to operations that accept one (`teamId: null` for the personal account), and return `{ status, data, page? }` with `until` or `cursor` pagination. Named tools are `list_teams`, the value-safe environment variable tools, `get_deployment_build_logs`, `get_runtime_logs` (bounded by `waitMs` and `maxRows`), and `vercel_api_upload` for octet-stream operations. Value safety follows a reviewed per-operation table derived from the pinned spec (`scripts/value-safety.mjs` flags every operation whose response may carry a credential or secret value; a test fails on any without a verdict): credential minting, Connect authorization, project transfer requests, decrypted environment values, Global Config items and tokens, a domain move-out, KMS signing, and domain transfer codes are refused; environment values, protection-bypass secrets, deploy hook URLs, drain and webhook headers, signing secrets, and destination URLs beyond their origin, external route and redirect destinations beyond their origin, the args and values of every header, cookie, and query rule (route transforms and conditions, firewall conditions), team invite codes, synced Global Config items, and URL credentials are redacted on every path; a key-name heuristic covers the rest; and secret-family failures carry fixed messages. The 0.29 ownership refusals, reconciliation tables, `vercel_api_get`, `vercel_api_mutate`, `verify_project_domain`, `remove_project_domain`, `delete_deployment`, and the no-op `defaultPageSize` option are removed. See the provider auth migration guide.
+
+### Security
+
+- **Breaking:** Every key connector (Stripe, Notion, Cloudflare, Vercel) now applies one reviewed value-safety mechanism: one detector over each pinned spec (the union of the former Cloudflare and Vercel detectors), one per-vendor table of `refuse`, `redact`, and `safe` verdicts, one redaction engine on every result, and one error policy. Stripe refuses operations that hand out a credential (ephemeral keys, Terminal connection tokens and onboarding links, v1 and v2 account links, login links, account, customer, and billing portal sessions, file link creation, Financial Connections session creation, and the meter event session), refuses Issuing `number` and `cvc` expansions on every Issuing path, and redacts client secrets, webhook and event destination signing secrets, Apps secret payloads, app-install authorization codes, Terminal Wi-Fi passwords, forwarded header values, and Issuing card numbers and CVCs; webhook, file link, and pre-signed import URLs keep only their origin. Resource rules keyed on Stripe's `object` apply these wherever an object appears (expansions, lists, events and their `previous_attributes`). Identity verification URLs are unchanged; a Checkout Session's URL is returned whole only for a provably guest payment session (no `customer`, `customer_account`, customer creation, or saved payment method options) and otherwise keeps only its origin. Notion withholds the signature parameters of pre-signed file URLs and refuses its OAuth endpoints through the table. Cloudflare's review grows by 259 operations, newly redacting Hyperdrive passwords, RealtimeKit storage credentials, transform-rule header values, dispatch binding values, and webhook destinations beyond their origin. Vercel replaces environment values with `"[redacted]"` instead of dropping them, and redacts audit-event invite codes, integration drain headers, and route header values. Where the former engines differed the stricter rule holds: a credential-named field loses its whole value, and every reviewed operation (or one whose request takes a credential-named field) withholds the vendor's error text unless its review keeps it. `providers:spec` (now run under tsx) checks every reviewed path against the pinned response schema. `RestVendor.valueSafety` is required and the `redact` hook is removed; Cloudflare's generated index no longer carries `secrets`. See the provider auth migration guide.
+
 ## 0.30.0 — 2026-10-09
 
 Connecta 0.30.0 makes large results, sign-in and rich output dependable for agents, on both direct calls and programs. The six-tool surface from 0.29.0 stays. We measured the alternative, folding everything into `execute_code`, against it on Sonnet 5.5 and GPT-6-Luna (#765). The code-only surface scored lower and made a duplicate billable write, so it was not adopted.

package/README.md

@@ -67,9 +67,12 @@ operations each caller can reach.
 
 Connecta includes maintained connections for <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Infisical, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, and Vercel<!-- providers:end -->.
 Each connection has its own setup guide.
-Notion, Vercel, and Cloudflare offer hosted MCP connections and selected HTTP
-API capabilities. You can also connect other remote MCP servers or define the
-operations you need from an HTTP API.
+Stripe, Notion, Cloudflare, and Vercel use their hosted MCP servers when you
+sign in with OAuth, and Connecta's own API connections when you use an API key,
+a Cloudflare API token or Global API Key, a Notion integration token, or a
+Vercel access token. You can also
+connect other remote MCP servers or define the operations you need from an
+HTTP API.
 
 Google Workspace connections use the account your deployment assigns to each
 signed-in person. A Workspace administrator authorizes them for your domain.

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.30.0";
+export const CONNECTA_VERSION = "0.31.0";

package/dist/call-recovery.js

@@ -0,0 +1,25 @@
+const MAX_FACTS = 4;
+const MAX_TEXT = 128;
+const NAME = /^[A-Za-z][A-Za-z0-9]*$/;
+const facts = new WeakMap();
+/**
+ * Record facts that let the caller reconcile or safely retry this call's
+ * write. Bounded: at most four string facts with short camelCase names; a fact
+ * outside the bound is dropped rather than truncated.
+ */
+export function recordRecovery(ctx, recovery) {
+    const kept = { ...facts.get(ctx) };
+    for (const [name, value] of Object.entries(recovery)) {
+        if (Object.keys(kept).length >= MAX_FACTS && !Object.hasOwn(kept, name))
+            break;
+        if (!NAME.test(name) || name.length > 32 || typeof value !== "string" || value.length > MAX_TEXT)
+            continue;
+        kept[name] = value;
+    }
+    facts.set(ctx, Object.freeze(kept));
+}
+/** The facts a connector recorded on this call's context, if any. */
+export function recoveryFor(ctx) {
+    const recorded = ctx ? facts.get(ctx) : undefined;
+    return recorded && Object.keys(recorded).length > 0 ? recorded : undefined;
+}

package/dist/config-schema.d.ts

@@ -25,9 +25,13 @@ type AnyField = Field<any, any, boolean>;
 export type Shape = {
     readonly [key: string]: AnyField;
 };
-/** A discriminated union of closed objects: `cases[value[key]]`, else `cases[otherwise]`. */
+/**
+ * A discriminated union of closed objects: `cases[value[key[0]][key[1]]…]`,
+ * else `cases[otherwise]`. Each case is the whole object's shape, including
+ * the nested objects on the key path.
+ */
 interface Variants {
-    readonly key: string;
+    readonly key: readonly string[];
     readonly cases: Readonly<Record<string, Shape>>;
     readonly otherwise?: string;
 }
@@ -116,13 +120,16 @@ export declare function instance<F extends AnyField>(field: F): F & {
 };
 /**
  * A closed object whose allowed keys depend on a discriminant, such as
- * `remoteMcp({ auth: { type: "headers", headers } })`. An omitted
+ * `remoteMcp({ auth: { type: "headers", headers } })`. The discriminant may
+ * be nested: `variants(["auth", "type"], cases)` selects the whole options
+ * shape from `options.auth.type`, so `{ auth: { type: "apiKey" }, mode }` and
+ * `{ auth: { type: "oauth" } }` accept different top-level keys. An omitted
  * discriminant selects `otherwise` when given; an omitted one without it, an
- * unrecognized one, or a value that is not an object throws with its path and
- * the valid values, so no union falls through to "no case". Only the walk
- * reads variants; the factory validates the remaining values itself.
+ * unrecognized one, or a value on the path that is not an object throws with
+ * its path and the valid values, so no union falls through to "no case". Only
+ * the walk reads variants; the factory validates the remaining values itself.
  */
-export declare function variants(key: string, cases: Readonly<Record<string, Shape>>, otherwise?: string): Field<unknown, unknown, true>;
+export declare function variants(key: string | readonly string[], cases: Readonly<Record<string, Shape>>, otherwise?: string): Field<unknown, unknown, true>;
 /**
  * A closed object for the unknown-key walk only: each named key may hold
  * anything, which its factory validates. For the options of a built-in

package/dist/config-schema.js

@@ -183,16 +183,22 @@ export function instance(field) {
 }
 /**
  * A closed object whose allowed keys depend on a discriminant, such as
- * `remoteMcp({ auth: { type: "headers", headers } })`. An omitted
+ * `remoteMcp({ auth: { type: "headers", headers } })`. The discriminant may
+ * be nested: `variants(["auth", "type"], cases)` selects the whole options
+ * shape from `options.auth.type`, so `{ auth: { type: "apiKey" }, mode }` and
+ * `{ auth: { type: "oauth" } }` accept different top-level keys. An omitted
  * discriminant selects `otherwise` when given; an omitted one without it, an
- * unrecognized one, or a value that is not an object throws with its path and
- * the valid values, so no union falls through to "no case". Only the walk
- * reads variants; the factory validates the remaining values itself.
+ * unrecognized one, or a value on the path that is not an object throws with
+ * its path and the valid values, so no union falls through to "no case". Only
+ * the walk reads variants; the factory validates the remaining values itself.
  */
 export function variants(key, cases, otherwise) {
+    const path = typeof key === "string" ? [key] : [...key];
+    if (path.length === 0)
+        throw new Error("variants() requires a discriminant key.");
     return {
         ...opaque(),
-        variants: { key, cases, ...(otherwise !== undefined ? { otherwise } : {}) },
+        variants: { key: path, cases, ...(otherwise !== undefined ? { otherwise } : {}) },
     };
 }
 /**
@@ -309,14 +315,27 @@ function inspectRecord(value, path, field) {
  * is never echoed.
  */
 function selectShape(inspected, path, variants) {
-    const at = `${path}.${variants.key}`;
+    const at = `${path}.${variants.key.join(".")}`;
     const valid = Object.keys(variants.cases)
         .map((name) => JSON.stringify(name))
         .join(", ");
-    const descriptor = inspected.own.find(([key]) => key === variants.key)?.[1];
-    if (descriptor && isAccessor(descriptor))
-        fail(`${at} must be a plain value, not a getter or setter.`);
-    const discriminant = descriptor?.value;
+    // Walk the key path one plain object at a time, reading descriptors only.
+    let holder = inspected;
+    let discriminant;
+    for (const [depth, key] of variants.key.entries()) {
+        const step = `${path}.${variants.key.slice(0, depth + 1).join(".")}`;
+        const descriptor = holder.own.find(([own]) => own === key)?.[1];
+        if (descriptor && isAccessor(descriptor))
+            fail(`${step} must be a plain value, not a getter or setter.`);
+        discriminant = descriptor?.value;
+        if (depth === variants.key.length - 1 || discriminant === undefined)
+            break;
+        if (typeof discriminant !== "object" || discriminant === null || isArrayAt(discriminant, step)) {
+            fail(`${step} must be an object.`);
+        }
+        holder = inspectRecord(discriminant, step, OPAQUE);
+        discriminant = undefined;
+    }
     if (discriminant === undefined) {
         if (variants.otherwise !== undefined)
             return variants.cases[variants.otherwise];

package/dist/connectors/guarded-fetch.d.ts

@@ -1,6 +1,6 @@
 import type { ConnectorContext } from "../types.js";
 /** The methods a hand-written provider surface actually uses. */
-type GuardedMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type GuardedMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
 export interface GuardedRequest {
     method: GuardedMethod;
     /**
@@ -21,6 +21,14 @@ export interface GuardedRequest {
      * shadow it.
      */
     headers?: Record<string, string | undefined>;
+    /**
+     * Headers whose values the tool returns to its caller by contract, such as
+     * an idempotency key. They are added after the request's sent secrets are
+     * registered, so a name like `Idempotency-Key` does not mark the value a
+     * credential and redact it from the result that must carry it. They may not
+     * collide with any other header.
+     */
+    visibleHeaders?: Record<string, string>;
     /** JSON request body. Serialized here, with the `Content-Type` to match. */
     body?: unknown;
     /**

package/dist/connectors/guarded-fetch.js

@@ -343,6 +343,13 @@ export function guardedFetch(options) {
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
             };
             sentSecretsFor(ctx).request(url, init);
+            for (const [name, value] of Object.entries(request.visibleHeaders ?? {})) {
+                const shadow = hasHeader(headers, name);
+                if (shadow) {
+                    throw new ConnectorCallError("invalid_args", `A ${provider} request sets the ${shadow} header twice.`);
+                }
+                headers[name] = value;
+            }
             response = await send(url.toString(), init, ctx);
         }
         catch (cause) {
@@ -356,8 +363,13 @@ export function guardedFetch(options) {
         }
         const declared = Number(response.headers.get("content-length"));
         // A prefix read takes only what it was asked for, so a long body is not
-        // a reason to refuse it; the ceiling still bounds what is read.
-        if (Number.isFinite(declared) && declared > limit && !(request.prefixOnly && response.ok)) {
+        // a reason to refuse it; the ceiling still bounds what is read. A HEAD
+        // response has no body: its Content-Length describes the GET
+        // representation, which is exactly what a HEAD asks about.
+        if (Number.isFinite(declared) &&
+            declared > limit &&
+            request.method !== "HEAD" &&
+            !(request.prefixOnly && response.ok)) {
             await response.body?.cancel().catch(() => { });
             throw oversized(provider, limit, `a declared ${declared} bytes`);
         }

package/dist/errors.d.ts

@@ -282,6 +282,8 @@ export interface CallErrorDetails extends Partial<AuthorizationHandoff> {
         args?: unknown;
         argsOmitted?: true;
         argsRedacted?: true;
+        /** Facts the connector recorded before dispatch, such as a generated `idempotencyKey`. */
+        recovery?: Readonly<Record<string, string>>;
     };
     /** Explicit retry guidance; recovery never retries or mutates by itself. */
     retry?: string;

package/dist/invocation.js

@@ -10,6 +10,8 @@ import { splitAddress } from "./registry.js";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { validateCatalogToolInput } from "./validate.js";
 import { sentSecretsFor, sentSecretsForRequest, trackCredentialReads } from "./sent-secrets.js";
+import { recoveryFor } from "./call-recovery.js";
+import { classifyWriteOutcome } from "./write-outcome.js";
 import { classificationDigest, recordAuthFailure, recordCallEntry, replayClassificationDigest, resolveInvocationAuth, } from "./invocation-auth.js";
 import { downstreamContinuation, recordDownstreamArgumentEcho, isDownstreamInputResult, assertDownstreamOutputSafe, } from "./downstream-input-context.js";
 function defined(values) {
@@ -166,6 +168,9 @@ export class InvocationService {
             let attempts = 0;
             let resultBytes;
             let dispatchedToConnector = false;
+            // The context a dispatched call ran with, read for recovery facts the
+            // connector recorded before an interrupting deadline (call-recovery.ts).
+            let dispatchContext;
             let preInvocationAuthFailure = false;
             let answered = false;
             const sentSecrets = sentSecretsForRequest(this.catalog.requestScope);
@@ -217,6 +222,10 @@ export class InvocationService {
             const enrich = (error, target) => {
                 if (!target)
                     return error;
+                const recovery = recoveryFor(dispatchContext);
+                const recoveryRetry = recovery?.["idempotencyKey"]
+                    ? " A deliberate retry with uncertainCall.recovery.idempotencyKey and the exact original arguments cannot repeat the write while the vendor retains that key (Stripe keeps v1 keys at least 24 hours); after that, look the object up before retrying."
+                    : "";
                 if (isTimeoutFailure(error) && dispatchedToConnector && resolved?.definition.classification === "write") {
                     const echoed = argumentEcho;
                     return {
@@ -230,8 +239,10 @@ export class InvocationService {
                             address: `${target.connector.id}.${target.toolName}`,
                             ...echoed,
                             ...("args" in echoed ? {} : { argsOmitted: true }),
+                            ...(recovery ? { recovery } : {}),
                         },
                         retry: "Do not retry automatically. Check whether the write took effect first." +
+                            recoveryRetry +
                             (echoed.argsRedacted
                                 ? " Sensitive fields are omitted; use the original arguments if reconciliation requires another call."
                                 : "args" in echoed
@@ -239,6 +250,26 @@ export class InvocationService {
                                     : " The arguments could not be echoed safely; use the exact arguments you sent."),
                     };
                 }
+                // Any other dispatched write whose outcome is unknown (a lost response
+                // body, a 5xx, an unreadable reply) keeps the facts its connector
+                // recorded before dispatch, here and through program write accounting.
+                if (recovery &&
+                    !error.uncertainCall &&
+                    dispatchedToConnector &&
+                    resolved?.definition.classification === "write" &&
+                    classifyWriteOutcome({ ok: false, dispatched: true, answered, error }) === "unknown") {
+                    const echoed = argumentEcho;
+                    error = {
+                        ...error,
+                        uncertainCall: {
+                            address: `${target.connector.id}.${target.toolName}`,
+                            ...echoed,
+                            ...("args" in echoed ? {} : { argsOmitted: true }),
+                            recovery,
+                        },
+                        retry: error.retry ?? `Do not retry automatically. Check whether the write took effect first.${recoveryRetry}`,
+                    };
+                }
                 if (error.code === "auth_required" && target.connector.startAuth) {
                     error = { ...error, code: "downstream_oauth_required" };
                 }
@@ -464,6 +495,7 @@ export class InvocationService {
                     const connectorContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs, defer: this.catalog.defer }));
                     trackCredentialReads(connectorContext);
                     sentSecrets.include(sentSecretsFor(connectorContext));
+                    dispatchContext = connectorContext;
                     try {
                         if (target.connector.credential) {
                             if (!connectorContext.credential) {