@zackbart/connecta 0.36.0 → 0.36.2

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to this package are documented here.
 
+## 0.36.2 — 2026-10-27
+
+Connecta 0.36.2 makes Google's hosted MCP servers, such as BigQuery, usable through generic `remoteMcp()` connections. The new `@zackbart/connecta/google` entry mints Google service-account tokens for request-local auth, so agent pools can share a service-account connection without a browser consent. The service account acts as itself, or as a Workspace user when a delegation subject is given. A rejected token is dropped and re-minted for the next request; dispatched writes are never replayed.
+
+Remote MCP OAuth connections can now add browser-only authorization parameters with `auth.authorizationParams`. Personal Google connections set `access_type: "offline"` and `prompt: "consent"` to receive refresh tokens. Protocol and security fields are reserved, and changing the parameters requires reconnecting. API OAuth keeps its existing `authorizationParams` validation.
+
+Both additions are opt-in. Deployments that do not use them need no configuration change. The root bundle cap rises to 403,500 B gzip to fit the new validation. Live Google sign-in and BigQuery calls have not been exercised with deployment credentials.
+
+### Added
+
+- Mint Google service-account tokens for generic remote MCP request auth through `@zackbart/connecta/google`, with optional Workspace delegation and rejected-token cache invalidation.
+- Let remote MCP OAuth connections configure browser-only authorization parameters, including Google's offline-access and consent settings. Protocol and security fields, including `response_mode`, are reserved in every case variant; changing remote MCP authorization parameters requires reconnecting. API OAuth keeps its existing `authorizationParams` validation.
+
+## 0.36.1 — 2026-10-27
+
+Connecta 0.36.1 adds read-only Granola workspace API access and lets Eve agents select a pool before each model call. Pool changes keep guidance caches separate and prevent replay of parked calls against a different pool. Existing static-pool configuration and public provider tools keep their behavior.
+
+The contributor checks now center on real Node/Workers, browser, persistence and installed-package journeys. Every PR runs browser, audit, Eve and Docker package checks. This patch requires no deployment configuration migration. Granola operators supply a workspace key; Eve pool selectors are optional.
+
+QuickBooks invoice updates remain unavailable while their delivery contract is unresolved. The workload validation recipe is reproducible locally; live validation requires separate authorization and is not claimed by this release.
+
+### Added
+
+- Let the Eve helper choose a pool before each model call with an app-owned selector, fence parked calls after pool changes, and cache instructions and failure backoff per endpoint. Instruction requests also accept a custom client name.
+- Add a read-only Granola workspace API provider for meeting notes, details, paginated transcripts, folders and spaces, with encrypted shared credentials and the standard operation search/details/read surface.
+
+### Changed
+
+- Add a locally reproducible Eve 0.84 workload fixture with independently verified audience-exchange controls and retained server cancellation receipts, and clarify that custom-audience workload tokens are refused. Live validation still requires separate authorization for disposable resources. Verify the standard 2 GiB Fluid resource preset and require confirmed cleanup even when evidence persistence fails.
+- Replace invariant/spec test-title bookkeeping with executable evidence file
+  references and the existing stateful behavior journeys. Require installed-package,
+  generated-deployment and Docker smoke in the shared CI build job, with browser,
+  audit and real Eve compatibility on every PR. Remove the path classifier,
+  duplicate package workflow and completed migration's cross-commit exemption guard.
+  Keep focused runtime probes, provider contracts, build/declaration checks and the
+  single fail-closed `check` status.
+- Remove completed provider-migration exemptions, legacy generator fixtures and
+  unused internal list/guide adapters. Consolidate contributor provider and release
+  workflows around the current standard without changing public tools or guides.
+- Replace lower-layer operator, configuration and storage test mirrors with real browser, SQLite restart and deployed Node/Workers persistence journeys. Preserve focused SQL rollback, expiry, isolation, secrecy and cancellation probes.
+- Replace redundant auth, write, privacy and runtime test matrices with real HTTP/MCP identity, one-send recovery, secrecy and socket-cancellation journeys. Require prompt downstream closure and admission release after client cancellation, before the ordinary request deadline. Retain focused security and lifetime fault probes without changing runtime behavior or public APIs.
+- Clarify why QuickBooks invoice updates remain unavailable: sparse field preservation and request IDs do not establish email suppression for existing send-ready invoices. Record the authoritative contract gaps and a proposed unsent-only update for further review; no accounting write surface is added.
+- Replace the remaining catalog-wide provider failure sweep and redundant
+  provider/HTTP agreement checks with shared stateful outcomes and real HTTP
+  failure/recovery journeys. Retain vendor-specific privacy, MIME, ownership,
+  revision, physical-send and lifetime fault probes; remove five internal paging
+  helpers used only by the retired tests and private exports hidden by the old
+  source scan. Require successful, complete delivered reconciliation data for the
+  Tithe.ly cancellation journey; failed, empty, malformed and incomplete replies
+  cannot establish recovery. Public provider behavior is unchanged.
+
+### Fixed
+
+- Use permanently unreachable loopback port zero for native transport-failure probes so later test servers cannot answer them. Verify each platform's native connection error while preserving Node/Workers write-outcome, retry, reset and abort assertions.
+
 ## 0.36.0 — 2026-10-27
 
 Connecta 0.36.0 adds a maintained QuickBooks Online Accounting provider for one fixed sandbox or production company per connector. It offers company identity, bounded record searches, individual records and hierarchical financial reports, with contact details and payment credentials withheld. Deployments can opt into customer creation, sparse customer naming updates and unsent US service-invoice creation by setting `readOnly: false` on the connector. Writes need a stable request ID and are never replayed automatically; the API hatch stays read-only, and invoice updates remain unavailable. See [QuickBooks Online](https://github.com/zackbart/connecta/blob/v0.36.0/documentation/providers.md#quickbooks-online).

package/README.md

@@ -24,7 +24,7 @@ Connecta supplies the service credentials, so the agent doesn't need them.
 
 ## What you can connect
 
-Maintained connections: <!-- providers:start -->Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Overflow, Planning Center, QuickBooks Online, Stripe, Tithe.ly, and Vercel<!-- providers:end -->.
+Maintained connections: <!-- providers:start -->Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Granola, Overflow, Planning Center, QuickBooks Online, Stripe, Tithe.ly, and Vercel<!-- providers:end -->.
 
 Maintained API providers pair reviewed vendor contracts with tools built by
 Connecta. See the [API sources and tool inventory](./documentation/providers.md#api-sources-and-tool-inventory)

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.36.0";
+export const CONNECTA_VERSION = "0.36.2";

package/dist/auth/downstream-oauth.js

@@ -1972,6 +1972,9 @@ export class KvOAuthProvider {
                     return;
                 if (!this.allowAuthorization)
                     throw this.authorizationRefused();
+                for (const [name, value] of this.clientOptions?.authorizationParams ?? []) {
+                    authorizationUrl.searchParams.set(name, value);
+                }
                 this.assertCredentialFree(authorizationUrl.toString(), (yield authInvoke(this, "boundGrant", [])).body, true);
                 const state = this.consent.state ?? authorizationUrl.searchParams.get("state");
                 if (!state)

package/dist/auth/oauth-authorization-params.js

@@ -0,0 +1,52 @@
+import { ConfigError } from "../config-schema.js";
+/**
+ * Protocol and security fields cannot be supplied through remote MCP extensions.
+ * `response_mode` stays reserved: callbacks arrive only as GET query parameters.
+ */
+const RESERVED = new Set([
+    "response_type",
+    "response_mode",
+    "client_id",
+    "client_secret",
+    "redirect_uri",
+    "state",
+    "code_challenge",
+    "code_challenge_method",
+    "scope",
+    "resource",
+    "request",
+    "request_uri",
+]);
+/** Validate and snapshot non-secret browser-only parameters at construction. */
+export function authorizationParamsFor(value, path) {
+    if (value === undefined)
+        return [];
+    const invalid = (detail) => {
+        throw new ConfigError(`${path} ${detail}`);
+    };
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        invalid("must be a plain string map.");
+    const entries = Object.entries(value);
+    if (entries.length > 32)
+        invalid("must contain at most 32 parameters.");
+    const names = new Set();
+    return entries
+        .map(([name, entry]) => {
+        if (!/^[A-Za-z0-9_.-]{1,128}$/.test(name))
+            invalid("names must be 1–128 ASCII letters, digits, dots, underscores or hyphens.");
+        const lower = name.toLowerCase();
+        if (RESERVED.has(lower))
+            invalid(`may not set "${name}"; the authorization request owns it.`);
+        if (names.has(lower))
+            invalid("must not contain case-variant duplicate names.");
+        names.add(lower);
+        if (typeof entry !== "string" ||
+            !entry.trim() ||
+            entry.length > 2048 ||
+            Array.from(entry).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) {
+            invalid("values must be non-empty strings of at most 2048 code units without control characters.");
+        }
+        return [name, entry];
+    })
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}

package/dist/auth/static-oauth.js

@@ -222,7 +222,7 @@ class StaticOAuthProvider extends KvOAuthProvider {
         super(connectorId, ctx.storage, `${ctx.baseUrl}/oauth/callback/${connectorId}`, coordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx), viewSignal(ctx, requestOwned), 
         // No client binding: the client is configuration, so there is no
         // registration for a restart to carry forward or discard.
-        undefined, (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), undefined, settings.scope, undefined, { secrets: sentSecretsFor(ctx) });
+        undefined, (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), undefined, settings.scope, undefined, { secrets: sentSecretsFor(ctx), authorizationParams: settings.authorizationParams });
         this.settings = settings;
     }
     /**
@@ -341,9 +341,6 @@ class StaticOAuthProvider extends KvOAuthProvider {
         }, StaticOAuthProvider.prototype.validateResourceURL);
         registerAuthMethod(StaticOAuthProvider.prototype, "redirectToAuthorization", function (authorizationUrl) {
             return authFlow(function* () {
-                for (const [name, value] of this.settings.authorizationParams) {
-                    authorizationUrl.searchParams.set(name, value);
-                }
                 if (!this.settings.pkce) {
                     authorizationUrl.searchParams.delete("code_challenge");
                     authorizationUrl.searchParams.delete("code_challenge_method");

package/dist/connectors/option-shapes.js

@@ -22,6 +22,7 @@ export const REMOTE_MCP_AUTH = variants("type", {
     }).shape,
     oauth: optionsOf()({
         ...keys("type", "clientMetadataUrl", "scope"),
+        authorizationParams: strings(),
         client: optionsOf()(keys("issuer", "clientId", "clientSecret", "tokenEndpointAuthMethod")),
     }).shape,
 });

package/dist/connectors/remote-mcp.d.ts

@@ -1,6 +1,7 @@
 import { type RemoteOAuthClient } from "../auth/downstream-client-metadata.js";
 import type { FetchLike, Transport } from "@modelcontextprotocol/client";
 import { ConnectorCallError } from "../errors.js";
+import type { RequestToken } from "../request-token.js";
 import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorCredentialConfig, ConnectorUsageGuide, Logger } from "../types.js";
 /**
  * A static downstream credential supplied through the connection in the
@@ -37,7 +38,7 @@ interface RemoteMcpCredentialAuth {
 export type RemoteMcpAuth = {
     type: "request";
     /** Resolve a Bearer token inside this request. Never persisted or described. */
-    token: (ctx: ConnectorContext) => Promise<string>;
+    token: RequestToken;
     /** Static protocol/catalog headers, never Authorization. */
     headers?: Record<string, string>;
 } | {
@@ -51,6 +52,8 @@ export type RemoteMcpAuth = {
     client?: RemoteOAuthClient;
     /** Space-separated default scopes when the resource server does not advertise them. */
     scope?: string;
+    /** Non-secret browser authorization parameters; protocol fields are reserved. Changes require reconnect. */
+    authorizationParams?: Record<string, string>;
 };
 export type RemoteMcpRedirectPolicy = "none" | "same-origin";
 export interface RemoteMcpOptions {

package/dist/connectors/remote-mcp.js

@@ -1,3 +1,4 @@
+import { authorizationParamsFor } from "../auth/oauth-authorization-params.js";
 import { authView } from "../auth/native-call.js";
 import { authFlow, authCall, authInvoke, authValue, authMethod, authCatch } from "../auth/native.js";
 import { isOAuthCredentialRequest } from "../auth/oauth-token-response.js";
@@ -1101,6 +1102,7 @@ export function remoteMcp(id, opts) {
     const clientMetadataUrl = opts.auth?.type === "oauth" ? opts.auth.clientMetadataUrl : undefined;
     const oauthScope = opts.auth?.type === "oauth" ? opts.auth.scope : undefined;
     assertOAuthScope(id, oauthScope);
+    const authorizationParams = authorizationParamsFor(opts.auth?.type === "oauth" ? opts.auth.authorizationParams : undefined, `remoteMcp(${JSON.stringify(id)}).auth.authorizationParams`);
     const staticClient = opts.auth?.type === "oauth" && opts.auth.client ? { ...opts.auth.client } : undefined;
     assertRemoteOAuthClient(id, staticClient);
     if (staticClient && clientMetadataUrl !== undefined)
@@ -1722,6 +1724,7 @@ export function remoteMcp(id, opts) {
             url: new URL(opts.url).href,
             redirectUri,
             clientMetadata: downstreamClientMetadata(redirectUri, oauthScope, ctx.oauthClientName, staticClient ? remoteClientAuthMethod(staticClient) : "none"),
+            ...(authorizationParams.length ? { authorizationParams } : {}),
             authScope: opts.authScope ?? "shared",
             versionNegotiation: opts.versionNegotiation ?? "auto",
             redirects: opts.redirects ?? "none",
@@ -1735,7 +1738,7 @@ export function remoteMcp(id, opts) {
                     },
                 }
                 : {}),
-        }), (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), metadataUrl, oauthScope, undefined, { name: ctx.oauthClientName, client: staticClient, secrets: sentSecretsFor(ctx) });
+        }), (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), metadataUrl, oauthScope, undefined, { name: ctx.oauthClientName, client: staticClient, secrets: sentSecretsFor(ctx), authorizationParams });
         if (state)
             state.provider = provider;
         return provider;
@@ -1856,6 +1859,11 @@ export function remoteMcp(id, opts) {
                     return response;
                 });
             }));
+            if (response.status === 401 && requestAuth?.token.invalidate && credentialValue !== null) {
+                // Invalidate the exact bytes this transport sent, never a newer token.
+                // Preserve the original 401 even if an operator hook fails. No replay.
+                (yield authCatch(authInvoke(requestAuth.token, "invalidate", [credentialValue, ctx]), () => { }));
+            }
             if (credentialPost && !isOAuthCredentialRequest(init) && REDIRECT_STATUSES.has(response.status)) {
                 (yield authCatch(authValue(() => response.body?.cancel()), () => { }));
                 throw new ConnectorCallError("connector_call_failed", "OAuth registration endpoint redirected; the request was not repeated.", { retryable: false });
@@ -2408,6 +2416,9 @@ export function remoteMcp(id, opts) {
                 : isOauth
                     ? {
                         mode: "oauth",
+                        ...(authorizationParams.length
+                            ? { authorizationParamNames: authorizationParams.map(([name]) => name) }
+                            : {}),
                         ...(oauthScope !== undefined ? { scope: oauthScope } : {}),
                         ...(describedClientMetadataUrl !== undefined ? { clientMetadataUrl: describedClientMetadataUrl } : {}),
                     }

package/dist/google.d.ts

@@ -0,0 +1,13 @@
+import type { RequestToken } from "./request-token.js";
+import { type GoogleServiceAccount } from "./providers/_shared/google/service-account.js";
+export type { GoogleServiceAccount } from "./providers/_shared/google/service-account.js";
+export interface GoogleServiceAccountTokenOptions {
+    /** The downloaded JSON key text, or its camelCase fields. Kept in deployment memory only. */
+    serviceAccount: GoogleServiceAccount | string;
+    /** Non-empty HTTPS OAuth scope URLs for the target API. */
+    scopes: readonly string[];
+    /** Optional Workspace user for domain-wide delegation; omitted means the account itself. */
+    subject?: string;
+}
+/** Mint Google OAuth access tokens for remoteMcp's shared request auth on Node or Workers. */
+export declare function googleServiceAccountToken(options: GoogleServiceAccountTokenOptions): RequestToken;

package/dist/google.js

@@ -0,0 +1,42 @@
+import { assertKnownOptions, ConfigError, keys, optionsOf } from "./config-schema.js";
+import { delegatedToken, forgetDelegatedToken, parseServiceAccount, } from "./providers/_shared/google/service-account.js";
+const OPTIONS = optionsOf()(keys("serviceAccount", "scopes", "subject"));
+const ACCOUNT = optionsOf()(keys("clientEmail", "privateKey", "clientId"));
+/** Mint Google OAuth access tokens for remoteMcp's shared request auth on Node or Workers. */
+export function googleServiceAccountToken(options) {
+    const opts = assertKnownOptions(options, "googleServiceAccountToken", OPTIONS);
+    let input = opts.serviceAccount;
+    if (typeof input === "object" && input !== null) {
+        input = assertKnownOptions(input, "googleServiceAccountToken.serviceAccount", ACCOUNT);
+    }
+    let account;
+    try {
+        account = parseServiceAccount("googleServiceAccountToken", input);
+    }
+    catch {
+        // The legacy Workspace parser may quote a JSON credential's type. Never
+        // reflect arbitrary credential-file fields through this public helper.
+        throw new ConfigError("googleServiceAccountToken.serviceAccount requires a valid Google service-account JSON key or { clientEmail, privateKey, clientId? } with a PKCS#8 RSA key of at least 2048 bits.");
+    }
+    if (!Array.isArray(opts.scopes) || opts.scopes.length === 0 || !Array.from(opts.scopes).every(validScope)) {
+        throw new ConfigError("googleServiceAccountToken.scopes must be a non-empty array of HTTPS OAuth scope URLs.");
+    }
+    if (opts.subject !== undefined && (typeof opts.subject !== "string" || !/^[^\s@]+@[^\s@]+$/.test(opts.subject))) {
+        throw new ConfigError("googleServiceAccountToken.subject must be a Workspace email address when provided.");
+    }
+    const request = { account, subject: opts.subject, scopes: [...new Set(opts.scopes)] };
+    const token = async (ctx) => await delegatedToken(request, ctx);
+    token.invalidate = async (rejected) => await forgetDelegatedToken(request, rejected);
+    return token;
+}
+function validScope(value) {
+    if (typeof value !== "string" || /\s/.test(value))
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && !url.username && !url.password && !url.hash;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/http/hatch-paging.js

@@ -1,5 +1,5 @@
-// Internal opt-in adapters for the standard hatch. No maintained provider opts
-// in until its separate step-2 migration. Inputs have crossed connection safety.
+// Internal opt-in adapters for the standard hatch. Inputs have crossed
+// connection safety.
 import { ConnectorCallError } from "../errors.js";
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};

package/dist/http/paging.js

@@ -1,29 +1,17 @@
 // Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
 //
-// Paging is a strategy plus one cursor codec. A strategy turns "the next page
-// after this cursor" into a vendor request and reads back rows and the next
-// vendor cursor; tools take one page, and `allRows` walks every page as a
-// Stream for programs and the hatch. The codec is the only place a cursor is
-// minted: `plain` hands the vendor's cursor through; `bound` ties it to the tool and its
-// arguments so a cursor from another call is refused instead of silently
-// reading the wrong list.
-import { Effect, Option, Schema, Stream } from "effect";
+// List tools take one page at a time. Lookahead detects an extra row; bound
+// cursors authenticate the tool, arguments, connection and credential owner.
+import { Effect, Schema } from "effect";
 import { ConnectorCallError } from "../errors.js";
 import { Refusal } from "./errors.js";
-import { confinementBase } from "../http-policy.js";
 import { canonicalJson } from "../canonical-json.js";
 import { ContinuationBinding, ContinuationStorage } from "../runtime/call.js";
 import { continuationKeys } from "../storage/keys.js";
-/** The `page` object every list tool returns. */
-export const PageInfo = Schema.Struct({
-    hasMore: Schema.Boolean,
-    nextCursor: Schema.NullOr(Schema.String),
-});
 /**
  * The standard `page` (decision 0011 S2): `nextCursor` is present exactly
  * when `hasMore` is true and continuation is safe. A hatch adapter can report
  * more data without a cursor when its continuation cannot be confined.
- * Step-1 lists keep `PageInfo` until their step 2.
  */
 export const StandardPage = Schema.Struct({
     hasMore: Schema.Boolean,
@@ -55,79 +43,6 @@ export function lookahead(options) {
         return { rows, page: { hasMore, nextCursor: id } };
     });
 }
-/** Vendor-supplied continuation, read only after the connection made its data safe. */
-export function token(options) {
-    return Effect.flatMap(Effect.suspend(options.fetch), ({ rows, hasMore, nextCursor }) => {
-        if (hasMore && !nextCursor)
-            return badPage("The vendor reported another page without a next cursor.");
-        return Effect.succeed({ rows, page: { hasMore, nextCursor: hasMore ? nextCursor : null } });
-    });
-}
-/** Offset paging advances by the rows actually returned, with a total when supplied. */
-export function offset(options) {
-    return Effect.gen(function* () {
-        yield* position(options.offset, 0);
-        yield* position(options.limit, 1);
-        return yield* Effect.map(options.fetch(options.offset, options.limit), ({ rows, total }) => {
-            const next = options.offset + rows.length;
-            const hasMore = rows.length > 0 && (total === undefined ? rows.length >= options.limit : next < total);
-            return { rows, page: { hasMore, nextCursor: hasMore ? String(next) : null } };
-        });
-    });
-}
-/** Page numbers from a vendor's safe body or headers, with full-page fallback. */
-export function page(options) {
-    return Effect.gen(function* () {
-        yield* position(options.page, 1);
-        yield* position(options.limit, 1);
-        return yield* Effect.map(options.fetch(options.page, options.limit), ({ rows, hasMore, totalPages }) => {
-            const more = hasMore ?? (totalPages === undefined ? rows.length >= options.limit : options.page < totalPages);
-            return { rows, page: { hasMore: more, nextCursor: more ? String(options.page + 1) : null } };
-        });
-    });
-}
-/** Extract only a cursor from a next URL confined to this connection's origin and path. */
-export function link(options) {
-    const base = confinementBase("Paging", options.baseUrl);
-    const prefix = base.pathname.replace(/\/+$/, "");
-    if (!options.param)
-        throw new Error("Link paging needs a cursor parameter.");
-    return Effect.flatMap(Effect.suspend(options.fetch), ({ rows, next }) => {
-        if (!next)
-            return Effect.succeed({ rows, page: { hasMore: false, nextCursor: null } });
-        let url;
-        try {
-            url = new URL(next, base);
-        }
-        catch {
-            return badPage("The vendor returned an invalid next-page URL.");
-        }
-        if (url.origin !== base.origin ||
-            !`${url.pathname}/`.startsWith(`${prefix}/`) ||
-            url.username ||
-            url.password ||
-            url.hash)
-            return badPage("The vendor returned a next-page URL outside this connection.");
-        const cursors = url.searchParams.getAll(options.param);
-        if (cursors.length !== 1 || !cursors[0])
-            return badPage("The vendor returned no unique next-page cursor.");
-        return Effect.succeed({ rows, page: { hasMore: true, nextCursor: cursors[0] } });
-    });
-}
-function position(value, minimum) {
-    return Number.isSafeInteger(value) && value >= minimum
-        ? Effect.void
-        : Effect.fail(new Refusal({
-            error: new ConnectorCallError("invalid_args", "Paging positions and limits must be whole numbers within their bounds."),
-        }));
-}
-function badPage(message) {
-    return Effect.fail(new Refusal({ error: new ConnectorCallError("connector_call_failed", message, { retryable: false }) }));
-}
-/** Every row of every page, fetched as the stream is pulled. */
-export function allRows(fetchPage) {
-    return Stream.paginate(undefined, (cursor) => Effect.map(fetchPage(cursor), ({ rows, page }) => [rows, Option.fromNullishOr(page.hasMore ? page.nextCursor : null)]));
-}
 const STRAY_CURSOR = "This cursor belongs to a different call. Pass back the nextCursor from the previous page of this same call, with the same arguments.";
 /** Resolved, nonextractable keys only: no request promise is retained between calls. */
 const signingKeys = new WeakMap();

package/dist/http/provider.js

@@ -191,8 +191,7 @@ export function defineApiProvider(definition) {
             // The declared fact the Writes convention states must match what the write builders send.
             if (idempotencyKey !== undefined && [...builtTools, ...hatchTools].some(takesIdempotencyKey) !== idempotencyKey)
                 throw new Error(`${metadata.title} declares idempotencyKey: ${idempotencyKey}, but its write tools ${idempotencyKey ? "send no" : "send an"} idempotency key.`);
-            const usageGuide = guide(options);
-            const renderedGuide = "content" in usageGuide ? usageGuide : provider.usageGuide(usageGuide);
+            const renderedGuide = provider.usageGuide(guide(options));
             const connector = tracksEveryRequest(api(id, {
                 ...(defaultCallAdmission
                     ? {

package/dist/http/tools.js

@@ -22,7 +22,7 @@ import { causeError, runEdge } from "../runtime/run.js";
 import { recordUnauthorized, Refusal, RequestRefused, toConnectorCallError, withheldDefect, } from "./errors.js";
 import { fieldsInput, fieldsProblem, selectFields } from "./fields.js";
 import { catalogSchema, Integer } from "./json-schema.js";
-import { boundCursor, Cursor, PageInfo, StandardPage } from "./paging.js";
+import { boundCursor, Cursor, StandardPage } from "./paging.js";
 import { Classification, Dispatches, IdempotencyKey, Recovery, ReadTool, WriteCapacity, writeRequestKey, fromConnectorContext, } from "./services.js";
 const inputs = new WeakMap();
 const keyed = new WeakSet();
@@ -118,28 +118,6 @@ export function get(connection, spec) {
 export function list(connection, spec) {
     if (spec.cursor !== undefined && spec.cursor !== "plain" && spec.cursor !== "bound")
         throw new Error('A list cursor must be "plain" or "bound".');
-    if (!("key" in spec))
-        return standardList(connection, spec);
-    if (!spec.key || spec.key === "page")
-        throw new Error("A list needs a row key distinct from page.");
-    return read(connection, {
-        ...spec,
-        output: Schema.Struct({ [spec.key]: Schema.Array(spec.row), page: PageInfo }),
-        run: (args) => Effect.gen(function* () {
-            const fields = args;
-            const supplied = typeof fields.cursor === "string" ? fields.cursor : undefined;
-            const cursor = supplied !== undefined && spec.cursor === "bound"
-                ? yield* boundCursor.decode(spec.name, fields, supplied)
-                : supplied;
-            const result = yield* spec.page(args, cursor);
-            const nextCursor = result.page.nextCursor !== null && spec.cursor === "bound"
-                ? yield* boundCursor.encode(spec.name, fields, result.page.nextCursor)
-                : result.page.nextCursor;
-            return { [spec.key]: result.rows, page: { ...result.page, nextCursor } };
-        }),
-    });
-}
-function standardList(connection, spec) {
     const { default: size, max } = spec.limit;
     if (spec.total !== undefined && spec.total !== true)
         throw new Error(`${spec.name} total must opt in with true for a vendor-stated exact count.`);

package/dist/program-writes.js

@@ -4,7 +4,6 @@ import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { Effect } from "effect";
 import { jsonResult } from "./meta-tools.js";
 import { classifyWriteOutcome } from "./write-outcome.js";
-export { classifyWriteOutcome } from "./write-outcome.js";
 /** Writes one program may send (`execute.maxWrites`), unless configured. */
 export const DEFAULT_MAX_WRITES = CONFIG_DEFAULTS.execute.maxWrites;
 /** What a dispatched write's outcome says about whether it landed. */

package/dist/providers/_shared/google/service-account.d.ts

@@ -35,7 +35,7 @@ export declare function parseServiceAccount(owner: string, input: unknown): Serv
 /** One delegated token request: whose account, acting as whom, for what. */
 export interface DelegatedTokenRequest {
     account: ServiceAccountKey;
-    subject: string;
+    subject?: string | undefined;
     scopes: readonly string[];
 }
 /**

package/dist/providers/_shared/google/service-account.js

@@ -1,8 +1,7 @@
 /**
- * A Google service account acting for Workspace users through domain-wide
- * delegation: the key, the signed JWT-bearer assertion, and the short-lived
- * access tokens it buys. Shared by every Workspace product provider; never its
- * own export.
+ * A Google service account acting as itself or for Workspace users through
+ * domain-wide delegation: the key, signed JWT-bearer assertions and short-lived
+ * access tokens. Shared by Workspace providers and the optional /google helper.
  *
  * Why not the vault. One key serves every Workspace connector a deployment
  * declares — Gmail, Drive, Docs — and it is a deployment secret in the same
@@ -300,9 +299,17 @@ function tokenAnswer(status, code) {
  * Map a refused token request to what fixes it. The codes are RFC 6749's and
  * Google documents what each means for a delegated assertion.
  */
-function tokenFailure(account, scopes, status, headers, payload) {
+function tokenFailure(account, scopes, status, headers, payload, subject) {
     const code = asRecord(payload)["error"];
     const said = tokenAnswer(status, code);
+    if (subject === undefined) {
+        if (code === "unauthorized_client" || code === "access_denied" || code === "invalid_scope" || status === 403) {
+            return new ConnectorCallError("provider_permission_denied", `Google refused a service-account token.${said} Check the requested OAuth scopes and the service account's IAM permissions for the target API and resources.`);
+        }
+        if (code === "invalid_grant") {
+            return resendAdvice(new ConnectorCallError("auth_required", `Google refused the service-account assertion.${said} The key may be deleted or disabled, or this host's clock may be minutes off. Check the key and clock.`), " before retrying");
+        }
+    }
     const client = account.clientId
         ? `client ID ${account.clientId} (${account.clientEmail})`
         : `the client ID of ${account.clientEmail}`;
@@ -325,7 +332,7 @@ function tokenFailure(account, scopes, status, headers, payload) {
     if (status === 403) {
         return new ConnectorCallError("provider_permission_denied", `Google refused domain-wide delegation.${said} Ask a Workspace super admin to review ${client} in the Admin console's Manage Domain Wide Delegation entry and grant exactly these scopes: ${scopes.join(",")}.`);
     }
-    return new ConnectorCallError("connector_call_failed", `Google's token endpoint refused the delegated assertion with HTTP ${status}.${said}`, { retryable: false });
+    return new ConnectorCallError("connector_call_failed", `Google's token endpoint refused the ${subject === undefined ? "service-account" : "delegated"} assertion with HTTP ${status}.${said}`, { retryable: false });
 }
 async function mint(account, subject, scopes, ctx) {
     const issuedAt = Date.now();
@@ -339,7 +346,7 @@ async function mint(account, subject, scopes, ctx) {
         const parsed = await response.jsonResult();
         const payload = "value" in parsed ? parsed.value : undefined;
         if (!response.ok) {
-            throw verdict(tokenFailure(account, scopes, response.status, response.headers, payload));
+            throw verdict(tokenFailure(account, scopes, response.status, response.headers, payload, subject));
         }
         const body = asRecord(payload);
         const accessToken = body["access_token"];
@@ -383,7 +390,12 @@ function keyIdentity(account) {
 }
 async function cacheKey({ account, subject, scopes }) {
     // Workspace addresses are case-insensitive; scope order is not a new grant.
-    return [account.clientEmail, await keyIdentity(account), subject.toLowerCase(), [...scopes].sort().join(" ")].join("\n");
+    return JSON.stringify([
+        account.clientEmail,
+        await keyIdentity(account),
+        subject?.toLowerCase() ?? null,
+        [...new Set(scopes)].sort(),
+    ]);
 }
 function remember(key, minted) {
     tokens.delete(key);

package/dist/providers/_shared/sensitive-fields.js

@@ -1,22 +1,6 @@
 // A provider's sensitive fields leave every result unless deployment code
 // returns them; no tool argument can. Shared by the providers whose raw rows
 // and hatches would otherwise reach what their projections drop.
-/** What `raw: true` and the hatches return, under the deployment's `sensitiveFields` choice. */
-export function unprojectedResults(sensitiveFields, names) {
-    if (sensitiveFields === "return")
-        return (body) => body;
-    const dropped = new Set(names);
-    const strip = (value) => {
-        if (Array.isArray(value))
-            return value.map(strip);
-        if (!value || typeof value !== "object")
-            return value;
-        return Object.fromEntries(Object.entries(value)
-            .filter(([name]) => !dropped.has(name))
-            .map(([name, entry]) => [name, strip(entry)]));
-    };
-    return (body) => strip(body);
-}
 /** Refuse anything but the two choices, at construction (INV-11). */
 export function sensitiveFieldsOption(provider, value) {
     if (value === undefined)

package/dist/providers/breeze/api.js

@@ -66,7 +66,7 @@ const PATH_PATTERN = /^(\/[a-z0-9_]+)+\/?$/;
  * which reads the calendar without a key, and its embed key. Neither hatch
  * returns them.
  */
-export function withoutCalendarFeeds(path, body) {
+function withoutCalendarFeeds(path, body) {
     if (path !== "/events/calendars/list")
         return body;
     const strip = (value) => {
@@ -80,7 +80,7 @@ export function withoutCalendarFeeds(path, body) {
     };
     return strip(body);
 }
-export function normalizedPath(raw) {
+function normalizedPath(raw) {
     const path = typeof raw === "string" ? raw : "";
     if (!PATH_PATTERN.test(path)) {
         throw new ConnectorCallError("invalid_args", "A Breeze path is relative to /api, begins with '/', and uses only lowercase letters, digits, underscores, and '/' — for example /tags/list_folders. No query string, host, or dot segments.");

package/dist/providers/ccb/api.js

@@ -238,7 +238,7 @@ export const CCB_INDEX = new OperationIndex({
 export const getMe = get("getMe", "/me", { success: Schema.Unknown });
 export const CcbApi = indexedVendor("CCB", CCB_INDEX, [getMe]);
 const safety = valueSafety(CCB_VALUE_SAFETY, () => CCB_INDEX);
-export const CCB_PAGE_HEADERS = ["x-page", "x-next-page", "x-total-pages", "x-total"];
+const CCB_PAGE_HEADERS = ["x-page", "x-next-page", "x-total-pages", "x-total"];
 export function ccbPageInfo(headers, page, size, rows) {
     const number = (name) => {
         const raw = headers[name];