@jini-ai/agent-plugins 0.6.17 → 0.6.19

package/google-workspace/form-destinations/sheets.mjs

@@ -0,0 +1,202 @@
+/**
+ * @file Form destination `google-sheets` (push only): appends each accepted form submission as one
+ * row of the tab its binding names, through the same Google client the Sheets tools use.
+ *
+ * Exists to turn one frozen delivery job (form, submission, binding config, all fixed when the
+ * submission was planned) into at most one spreadsheet row, and to report the outcome in the forms
+ * delivery contract's vocabulary. Per attempt it: refuses while the Sheets product is off; finds
+ * the tab by its numeric sheet id (renames are safe); matches columns by their field markers and
+ * headers (`mapping.mjs`); scans the `_tovu_submission_id` column for this submission
+ * (`dedupe.mjs`) and stops as delivered when the row is already there (more than one such row is
+ * reported as delivered, never appended again; its "review" note is dropped by the ledger); in one atomic batch grows the
+ * grid, writes the new headers and tags new field columns; appends the row with RAW values. An append whose answer was lost is never replayed: the column is scanned again,
+ * and when the row is not found the job reports `outcome-unknown`, so the next attempt scans before
+ * appending. Delivery is at-least-once with best-effort dedupe; nothing here claims exactly-once.
+ *
+ * Binding config (non-secret, frozen per job):
+ * `{ spreadsheetId: string, tabs: { [formSlug]: { sheetId: number } } }`. Which column holds which
+ * field lives in the sheet itself (column markers), not in the binding.
+ */
+import { columnName, parseA1Range, tabRange } from '../lib/sheets-a1.mjs';
+import { googleClientFor, sheetsUrl } from '../lib/sheets-client.mjs';
+import { isProductEnabled } from '../lib/product-state.mjs';
+import { GoogleWorkspaceError } from '../lib/request-policy.mjs';
+import { findSubmissionRows } from './dedupe.mjs';
+import { DeliveryRefusal, failureResult, resultForError } from './delivery-result.mjs';
+import { FIELD_MARKER_KEY, buildMapping, buildRow, planColumns, readMarkers } from './mapping.mjs';
+
+/** Per-request cap passed to the host kit; a request that runs past it counts as a lost answer. */
+export const DELIVERY_REQUEST_TIMEOUT_MS = 15_000;
+const TAB_FIELDS = 'sheets.properties(sheetId,title,gridProperties(rowCount,columnCount))';
+
+const configurationInvalid = () => new DeliveryRefusal({ code: 'configuration-invalid', retryable: false });
+
+/**
+ * The spreadsheet and tab this form's rows go to, from the frozen binding config.
+ * @throws {DeliveryRefusal} `configuration-invalid` when the config does not name them properly.
+ * @complexity O(1).
+ */
+function targetFor({ binding, form }) {
+  const { spreadsheetId, tabs } = binding.config ?? {};
+  const tab = tabs && Object.hasOwn(tabs, form.slug) ? tabs[form.slug] : undefined;
+  if (typeof spreadsheetId !== 'string' || !Number.isInteger(tab?.sheetId) || tab.sheetId < 0) throw configurationInvalid();
+  return { spreadsheetId, tab };
+}
+
+const a1 = (title, cells) => tabRange({ title, cells });
+
+/**
+ * The Sheets requests one delivery makes, over the shared Google client.
+ * @complexity O(1) to build; each call is one request (plus the client's retries).
+ */
+function sheetsRequests({ client, connectionRef, spreadsheetId }) {
+  const send = (request) => client.request({ connectionRef, ...request });
+  const valuesUrl = (range, method) => sheetsUrl({ spreadsheetId }, { segments: ['values', range], ...(method ? { method } : {}) });
+  return {
+    async tab(sheetId) {
+      const body = await send({ kind: 'read', url: sheetsUrl({ spreadsheetId }), query: { fields: TAB_FIELDS } });
+      const properties = (body?.sheets ?? []).map((sheet) => sheet?.properties).find((entry) => entry?.sheetId === sheetId);
+      // The tab was deleted (or never existed): the person picks the tab again.
+      if (typeof properties?.title !== 'string') throw configurationInvalid();
+      const grid = properties.gridProperties ?? {};
+      return { sheetId, title: properties.title, rowCount: grid.rowCount ?? 0, columnCount: grid.columnCount ?? 0 };
+    },
+    async rows(range) {
+      return (await send({ kind: 'read', url: valuesUrl(range), query: { majorDimension: 'ROWS' } }))?.values ?? [];
+    },
+    async markers(sheetId) {
+      const lookup = { metadataKey: FIELD_MARKER_KEY, locationType: 'COLUMN', metadataLocation: { sheetId }, locationMatchingStrategy: 'INTERSECTING_LOCATION' };
+      // A search changes nothing: `read` lets the client retry it.
+      const body = await send({ kind: 'read', method: 'POST', url: sheetsUrl({ spreadsheetId }, { segments: ['developerMetadata'], method: ':search' }), body: { dataFilters: [{ developerMetadataLookup: lookup }] } });
+      return readMarkers({ matches: Array.isArray(body?.matchedDeveloperMetadata) ? body.matchedDeveloperMetadata : [], sheetId });
+    },
+    async batch(changes) {
+      // Adds columns and metadata, so a replay could apply twice: a `write`, never replayed when its outcome is unknown.
+      await send({ kind: 'write', method: 'POST', url: sheetsUrl({ spreadsheetId }, { method: ':batchUpdate' }), body: { requests: changes } });
+    },
+    async append(range, row) {
+      const body = await send({ kind: 'write', method: 'POST', url: valuesUrl(range, ':append'), query: { valueInputOption: 'RAW', insertDataOption: 'INSERT_ROWS' }, body: { range, majorDimension: 'ROWS', values: [row] } });
+      return body?.updates?.updatedRange;
+    },
+  };
+}
+
+/** The rows of `tab` holding the submission id, in the id column at `idColumn`. @complexity see `findSubmissionRows`. */
+function scanFor(requests, tab, idColumn, submissionId) {
+  const column = columnName({ index: idColumn });
+  return findSubmissionRows({ rowCount: tab.rowCount, submissionId, readColumn: ({ from, to }) => requests.rows(a1(tab.title, `${column}${from}:${column}${to}`)) });
+}
+
+/**
+ * Success, naming where the row is (sheet id and row numbers only: no titles, no values). More than
+ * one row with this submission id (another writer, or a late append) is still delivered, never
+ * appended again. The reference names the rows for review, but the forms ledger keeps only `ok`
+ * (the contract has no reviewable success), so today no person sees it; see the README.
+ * @complexity O(rows).
+ */
+function delivered(sheetId, rows) {
+  if (rows.length === 0) return { ok: true, reference: `sheet ${sheetId}` };
+  if (rows.length === 1) return { ok: true, reference: `sheet ${sheetId} row ${rows[0]}` };
+  return { ok: true, reference: `sheet ${sheetId} rows ${rows.join(', ')} (duplicate submission id: review)` };
+}
+
+/** `updateCells` writing the new headers into row 1 as text (a header can never become a formula). @complexity O(headers). */
+function headerCells(sheetId, newHeaders) {
+  const values = newHeaders.map(({ header }) => ({ userEnteredValue: { stringValue: header } }));
+  return { updateCells: { start: { sheetId, rowIndex: 0, columnIndex: newHeaders[0].index }, rows: [{ values }], fields: 'userEnteredValue' } };
+}
+
+/** `createDeveloperMetadata` tagging one column with the field id it holds. @complexity O(1). */
+function markerRequest(sheetId, { field, index }) {
+  const location = { dimensionRange: { sheetId, dimension: 'COLUMNS', startIndex: index, endIndex: index + 1 } };
+  return { createDeveloperMetadata: { developerMetadata: { metadataKey: FIELD_MARKER_KEY, metadataValue: field, visibility: 'DOCUMENT', location } } };
+}
+
+/**
+ * Before the row that needs them: grows the grid, writes new headers and tags untagged field
+ * columns, in ONE atomic batch, so a half-prepared tab can never be left behind.
+ * @complexity O(new headers + untagged columns).
+ */
+async function prepareColumns(requests, tab, layout) {
+  const changes = [
+    ...(layout.width > tab.columnCount ? [{ appendDimension: { sheetId: tab.sheetId, dimension: 'COLUMNS', length: layout.width - tab.columnCount } }] : []),
+    ...(layout.newHeaders.length > 0 ? [headerCells(tab.sheetId, layout.newHeaders)] : []),
+    ...layout.untagged.map((column) => markerRequest(tab.sheetId, column)),
+  ];
+  if (changes.length > 0) await requests.batch(changes);
+}
+
+/**
+ * After an append whose answer was lost: scan again (the tab may have grown). Found → delivered.
+ * Not found, or the scan itself failed → `outcome-unknown`, retryable: the next attempt scans
+ * before it appends, which also gives a late append time to land.
+ * @complexity see `findSubmissionRows`.
+ */
+async function confirmUncertainAppend(requests, sheetId, idColumn, submissionId) {
+  try {
+    const rows = await scanFor(requests, await requests.tab(sheetId), idColumn, submissionId);
+    if (rows.length > 0) return delivered(sheetId, rows);
+  } catch {
+    // A failed re-scan proves nothing either way; the outcome stays unknown.
+  }
+  return failureResult({ code: 'outcome-unknown', retryable: true, outcome: 'unknown' });
+}
+
+const isUncertain = (error) => error instanceof GoogleWorkspaceError && error.code === 'uncertain-outcome';
+
+/** Appends the row once; a lost answer is re-checked, never replayed. @complexity O(1) requests plus a re-scan. */
+async function appendOnce(requests, tab, layout, row, submissionId) {
+  try {
+    const updatedRange = await requests.append(a1(tab.title, 'A1'), row);
+    const startRow = parseA1Range({ range: updatedRange })?.startRow;
+    return delivered(tab.sheetId, startRow === undefined ? [] : [startRow]);
+  } catch (error) {
+    if (!isUncertain(error)) throw error;
+    return confirmUncertainAppend(requests, tab.sheetId, layout.columns[0], submissionId);
+  }
+}
+
+/** The product this destination belongs to (`products.json`). */
+const SHEETS_PRODUCT = 'sheets';
+
+/** One delivery attempt; throws for every failure (mapped by the caller). @complexity O(rowCount / chunk) requests. */
+async function deliverRow(required, optional) {
+  // Retryable, but not a pause: the forms retry policy re-tries it (about 8 attempts over about a
+  // day) and then marks the job failed.
+  // Off unless the plugin's own settings say Sheets is on: no state reader never enables delivery.
+  if (!(await isProductEnabled({ state: optional.state, productId: SHEETS_PRODUCT }))) throw new DeliveryRefusal({ code: 'adapter-unavailable', retryable: true });
+  const { spreadsheetId, tab: tabConfig } = targetFor(required);
+  // One token read per Google request when the host offers it (OAuth: budgets count every request
+  // and the job's frozen account is re-checked); a plain credential carries just `token`.
+  const { credential } = required;
+  const connections = { getAccessToken: () => (credential.getAccessToken ? credential.getAccessToken() : Promise.resolve(credential.token)) };
+  const client = googleClientFor({ capabilities: { http: { fetch: ({ url }, init) => required.kit.fetch(url, init, { timeoutMs: DELIVERY_REQUEST_TIMEOUT_MS }) }, connections } });
+  const requests = sheetsRequests({ client, connectionRef: required.binding.connectionRef, spreadsheetId });
+  const tab = await requests.tab(tabConfig.sheetId);
+  const mapping = buildMapping({ form: required.form });
+  const headerRow = (await requests.rows(a1(tab.title, '1:1')))[0] ?? [];
+  const layout = planColumns({ mapping, headerRow, markers: await requests.markers(tab.sheetId) });
+  const existing = await scanFor(requests, tab, layout.columns[0], required.submission.id);
+  if (existing.length > 0) return delivered(tab.sheetId, existing);
+  await prepareColumns(requests, tab, layout);
+  return appendOnce(requests, tab, layout, buildRow({ mapping, ...layout, submission: required.submission }), required.submission.id);
+}
+
+export default {
+  /**
+   * The forms delivery contract's `deliver`. Never throws: every failure is a contract result.
+   * @param {{ kit: { fetch(url: string, init: RequestInit, options: { timeoutMs: number }): Promise<Response> }, credential: { token: string, getAccessToken?: () => Promise<string> }, form: { slug: string, fields: readonly { name: string, label?: string }[] }, submission: { id: string, answers: Readonly<Record<string, unknown>>, submittedAt: string }, binding: { connectionRef: string, config: Readonly<Record<string, unknown>> }, idempotencyKey?: string }} required
+   * @param {{ state?: { get(input: { key: string }): Promise<unknown> } }} [optional]
+   *   `state`: the host's read-only reader of this plugin's settings, the same store and gate the
+   *   tools use (`isProductEnabled`); absent = Sheets off. Quotas are the host's budgets, charged
+   *   on every token read (`credential.getAccessToken`).
+   * @returns {Promise<{ ok: true, reference?: string } | { ok: false, error: { code: string, retryable: boolean, retryAfterMs?: number, outcome?: 'not-applied' | 'unknown' } }>}
+   */
+  async deliver(required, optional = {}) {
+    try {
+      return await deliverRow(required, optional);
+    } catch (error) {
+      return resultForError({ error });
+    }
+  },
+};

package/google-workspace/lib/auth.mjs

@@ -0,0 +1,81 @@
+/**
+ * @file The Google Workspace sign-in hooks (the `lib/auth.mjs` module `tovu-connections.json`
+ * names): which scopes a sign-in requests, who signed in, and how a grant is revoked at Google.
+ *
+ * Exists because the host's OAuth engine is provider-neutral: Google's endpoints live in
+ * `tovu-connections.json`, and everything Google-specific the engine must call back into lives
+ * here. The engine handles state, PKCE, the code exchange, refresh and token storage.
+ *
+ * Revocation honesty: `revoke` resolves only when Google answered 200, or answered `invalid_token`
+ * (the token is already revoked: a retry after a lost answer resends a token Google already
+ * revoked, and the host's engine requires that to count as success). Both clients request offline
+ * access, so the engine hands over the refresh token, whose `invalid_token` means the grant is gone;
+ * only a credential stored without a refresh token could see it for a merely expired access token.
+ * Anything else throws, so the host shows "Disconnected locally; Google revocation pending", keeps
+ * the disabled sealed credential for a retry, and the person can remove access at
+ * {@link GOOGLE_ACCOUNT_ACCESS_PAGE}. The thrown error's `code` is the host engine's classification:
+ * `provider-unreachable` (no answer: network failure, timeout, 5xx) or `provider-refused` (an
+ * answer that was not a confirmation); its message is a fixed sentence, never Google's text.
+ */
+import { readAccount } from './drive-files.mjs';
+import { createGoogleClient } from './http.mjs';
+import { scopesFor } from './product-state.mjs';
+
+export const GOOGLE_REVOCATION_ENDPOINT = 'https://oauth2.googleapis.com/revoke';
+/** Where a person removes this site's access themselves ("Third-party apps & services"). */
+export const GOOGLE_ACCOUNT_ACCESS_PAGE = 'https://myaccount.google.com/connections';
+
+const REVOCATION_PENDING = 'Google did not confirm the revocation. Disconnected locally; Google revocation pending. Retry, or remove access at https://myaccount.google.com/connections.';
+
+/** The revoke hook's failure: the engine records only `code`, and the message is fixed. @complexity O(1). */
+function revocationFailure(code, cause) {
+  return Object.assign(new Error(REVOCATION_PENDING, cause === undefined ? undefined : { cause }), { code });
+}
+
+/**
+ * Asks Google to revoke the grant behind `token` (the refresh token when there is one, which ends
+ * the whole grant). Throws unless Google confirmed, or said the token is already revoked.
+ * @throws {Error} `code: 'provider-unreachable'` (no answer, timeout, 5xx) or `'provider-refused'`.
+ * @complexity O(1): one request.
+ */
+async function revokeAtGoogle(http, token) {
+  let response;
+  try {
+    response = await http.fetch({ url: GOOGLE_REVOCATION_ENDPOINT }, {
+      method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ token }).toString(),
+    });
+  } catch (cause) {
+    throw revocationFailure('provider-unreachable', cause);
+  }
+  if (response.status === 200 || (await alreadyRevoked(response))) return;
+  // A 5xx is Google failing to answer, not Google refusing: a retry may well confirm.
+  throw revocationFailure(response.status >= 500 ? 'provider-unreachable' : 'provider-refused');
+}
+
+/** Google's "this token is already revoked" answer (400 `invalid_token`); an unreadable body is not it. */
+async function alreadyRevoked(response) {
+  if (response.status !== 400) return false;
+  const body = await response.json().catch(() => null);
+  return body?.error === 'invalid_token';
+}
+
+/**
+ * The hooks the host's API-connection service calls (`ApiConnectionHooks`).
+ * @param {{ http: { fetch(target: { url: string }, init?: RequestInit): Promise<Response> } }} required
+ *   The host's guarded HTTP capability (the same one tools get).
+ * @complexity O(1) to build; each hook is at most one request.
+ */
+export function createHooks(required, _optional = {}) {
+  const { http } = required;
+  return {
+    async resolveScopes({ scopeSetIds }) { return scopesFor({ productIds: scopeSetIds }); },
+    async readAccount({ accessToken }) {
+      // A freshly issued token, not a stored connection yet: the client asks for no budget.
+      const client = createGoogleClient({ http, connections: { getAccessToken: async () => accessToken } });
+      return readAccount({ client, connectionRef: 'sign-in' });
+    },
+    async revoke({ token }) { await revokeAtGoogle(http, token); },
+  };
+}
+
+export default { createHooks };

package/google-workspace/lib/drive-files.mjs

@@ -0,0 +1,54 @@
+/**
+ * @file Drive helpers shared by every Google Workspace product: who the connection is signed in as
+ * and whole-file copy (`files.copy`, used by `sheets_copy`). File metadata reads (`files.get`) stay
+ * with their callers (Picker verification, `sheets_open_existing`) and share `DRIVE_FILES_URL` here.
+ *
+ * Exists so identity costs no extra permission: Drive `about.get` answers under `drive.file`, so
+ * the sign-in never adds `openid`, `email` or `profile` scopes just to learn the account.
+ * `permissionId` is the account's stable Drive id; the email is only for display.
+ */
+import { pathSegment } from './http.mjs';
+import { GoogleWorkspaceError } from './request-policy.mjs';
+
+export const DRIVE_ABOUT_URL = 'https://www.googleapis.com/drive/v3/about';
+export const DRIVE_FILES_URL = 'https://www.googleapis.com/drive/v3/files';
+const COPY_FIELDS = 'id,name,mimeType,webViewLink';
+
+/**
+ * The signed-in account: `{ accountId, displayName }`.
+ * @param {{ client: { request(input: object, options?: object): Promise<unknown> }, connectionRef: string }} required
+ * @param {{ signal?: AbortSignal }} [optional]
+ * @throws {GoogleWorkspaceError} `unexpected-response` when Google's answer names no account.
+ * @complexity O(1): one request.
+ */
+export async function readAccount(required, optional = {}) {
+  const body = await required.client.request({
+    connectionRef: required.connectionRef, url: DRIVE_ABOUT_URL, kind: 'read',
+    query: { fields: 'user(displayName,emailAddress,permissionId)' },
+  }, optional);
+  const user = body?.user;
+  if (typeof user?.permissionId !== 'string' || user.permissionId === '') throw new GoogleWorkspaceError({ code: 'unexpected-response' });
+  const label = [user.emailAddress, user.displayName].find((value) => typeof value === 'string' && value !== '');
+  return { accountId: user.permissionId, displayName: label ?? 'Google account' };
+}
+
+/**
+ * Copies one file the connection can open (`files.copy`); the copy is created by the site, so
+ * `drive.file` grants it automatically. A copy is not idempotent: an unknown outcome is
+ * `uncertain-outcome` and is never replayed (the shared client's `write` kind).
+ * @param {{ client: { request(input: object, options?: object): Promise<unknown> }, connectionRef: string, fileId: string, name: string }} required
+ * @param {{ parentId?: string, signal?: AbortSignal }} [optional] `parentId`: a folder the connection can open.
+ * @returns {Promise<{ fileId: string, name: string, mimeType: string, url: string | undefined }>}
+ * @throws {GoogleWorkspaceError} `unexpected-response` when Google's answer names no file id.
+ * @complexity O(1): one request.
+ */
+export async function copyFile(required, optional = {}) {
+  const body = await required.client.request({
+    connectionRef: required.connectionRef, kind: 'write', method: 'POST',
+    url: `${DRIVE_FILES_URL}/${pathSegment({ value: required.fileId })}/copy`,
+    query: { fields: COPY_FIELDS, supportsAllDrives: 'true' },
+    body: { name: required.name, ...(optional.parentId === undefined ? {} : { parents: [optional.parentId] }) },
+  }, optional.signal ? { signal: optional.signal } : {});
+  if (typeof body?.id !== 'string' || body.id === '') throw new GoogleWorkspaceError({ code: 'unexpected-response', outcome: 'unknown' });
+  return { fileId: body.id, name: body.name, mimeType: body.mimeType, url: body.webViewLink };
+}

package/google-workspace/lib/form-destination-settings.mjs

@@ -0,0 +1,72 @@
+/**
+ * @file The form destinations the destination panel saves: one host form-delivery binding per form
+ * (by its short name), for this plugin's Sheets adapter over its own connection, through the host's
+ * `deliveryBindings` capability. The binding config is what the Sheets destination reads
+ * (`{ spreadsheetId, accountId, tabs: { <formSlug>: { sheetId } } }`, see
+ * `form-destinations/README.md`) plus the spreadsheet and tab names the panels show.
+ *
+ * Exists so a saved choice IS the delivery binding: there is no second copy to keep in step, and the
+ * connection panel's account-switch screen lists exactly what delivery uses. Values are metadata
+ * only, never a token or a cell.
+ */
+import { CONNECTION_ID } from './surface-actions.mjs';
+
+/** This plugin's form-destination adapter id (`tovu-form-destinations.json`). */
+export const SHEETS_ADAPTER_ID = 'google-sheets';
+export const MAX_FORM_DESTINATIONS = 50;
+
+/** A form's short name: also a property name in the binding config, so no `__proto__`-style names. */
+export const FORM_SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/** The one form a binding saved here is for, or null for a binding this panel did not write. @complexity O(1). */
+function formSlugOf(binding) {
+  const slug = binding.formIds?.length === 1 ? binding.formIds[0] : null;
+  return slug !== null && FORM_SLUG_PATTERN.test(slug) ? slug : null;
+}
+
+/** The saved destination a binding holds, or null when its config is not in the shape `saveFormDestination` writes. @complexity O(1). */
+function destinationOf(binding, formSlug) {
+  const { spreadsheetId, accountId, tabs, title, tabTitle } = binding.config;
+  const sheetId = tabs?.[formSlug]?.sheetId;
+  const validIdentity = typeof spreadsheetId === 'string' && typeof accountId === 'string';
+  const valid = validIdentity && Number.isInteger(sheetId) && typeof title === 'string' && typeof tabTitle === 'string';
+  return valid ? { bindingId: binding.bindingId, enabled: binding.enabled, spreadsheetId, title, url: `https://docs.google.com/spreadsheets/d/${spreadsheetId}/edit`, sheetId, tabTitle, accountId } : null;
+}
+
+/**
+ * The saved destinations, keyed by form slug: this plugin's Sheets bindings that name one form;
+ * any other binding of the adapter is left out (and left alone).
+ * @param {{ deliveryBindings: { list(): Promise<readonly { bindingId: string, enabled: boolean, adapterId: string, formIds?: readonly string[], config: Record<string, unknown> }[]> } }} required
+ * @returns {Promise<Record<string, { bindingId: string, enabled: boolean, spreadsheetId: string, title: string, url: string, sheetId: number, tabTitle: string, accountId: string }>>}
+ * @complexity O(b), one host read.
+ */
+export async function readFormDestinations(required, _optional = {}) {
+  const entries = (await required.deliveryBindings.list()).flatMap((binding) => {
+    const formSlug = binding.adapterId === SHEETS_ADAPTER_ID ? formSlugOf(binding) : null;
+    const destination = formSlug === null ? null : destinationOf(binding, formSlug);
+    return destination === null ? [] : [[formSlug, destination]];
+  });
+  return Object.fromEntries(entries);
+}
+
+/**
+ * Saves one form's destination as its delivery binding (a new one, or the form's existing one).
+ * `accountId` is the account the spreadsheet was verified with: the host freezes it into every
+ * delivery job and refuses a job once the connection holds another account (an account switch never
+ * silently moves where rows go).
+ * @param {{ deliveryBindings: { save(draft: object): Promise<object> }, formSlug: string, destination: { spreadsheetId: string, title: string, sheetId: number, tabTitle: string, accountId: string } }} required
+ * @param {{ bindingId?: string, enabled?: boolean }} [optional] The existing binding id and enabled
+ *   state for reassignment; normal destination saves enable delivery by default.
+ * @complexity O(1), one host write.
+ */
+export async function saveFormDestination(required, optional = {}) {
+  const { formSlug, destination } = required;
+  await required.deliveryBindings.save({
+    ...(optional.bindingId === undefined ? {} : { bindingId: optional.bindingId }),
+    adapterId: SHEETS_ADAPTER_ID, connectionId: CONNECTION_ID, enabled: optional.enabled ?? true, formIds: [formSlug],
+    config: {
+      spreadsheetId: destination.spreadsheetId, accountId: destination.accountId, tabs: { [formSlug]: { sheetId: destination.sheetId } },
+      title: destination.title, tabTitle: destination.tabTitle,
+    },
+  });
+}

package/google-workspace/lib/http.mjs

@@ -0,0 +1,168 @@
+/**
+ * @file The one Google HTTP client of the Google Workspace plugin: every Sheets and Drive call (chat
+ * tools, admin actions, form delivery) goes through `createGoogleClient(...).request(...)`.
+ *
+ * Exists so the rules that keep a person's data and sign-in safe live in one place:
+ * - the access token is fetched from the host immediately before each attempt and is never
+ *   returned, logged or put in an error;
+ * - quotas are the host's: it charges the budgets the connection declares (per account and per
+ *   instance) on every token read, so this client keeps no limiter of its own; a budget refusal
+ *   is a `quota-delay` like Google's 429;
+ * - a failure becomes a safe {@link GoogleWorkspaceError} (code, `retryable`, `retryAfterMs`,
+ *   `outcome`, next action); Google's message text is dropped because it can echo sheet contents;
+ * - only retryable failures are retried, with jittered backoff that honours Retry-After, and a
+ *   non-idempotent write whose outcome is unknown is never replayed;
+ * - a token can expire between the host's freshness check and Google's: a 401 gets one more token
+ *   read, and is retried only if that token differs; an unchanged token or second 401 requires reconnect.
+ * Redirects, HTTPS-only and response-size bounds are enforced by the host's guarded HTTP capability.
+ */
+import { GoogleWorkspaceError, backoffMs, capRetryAfterMs, classifyFailure, shouldRetryInline } from './request-policy.mjs';
+
+const INVALID_JSON = Symbol('invalid-json');
+
+/** Host connection refusals (Jini api-connections codes) → the plugin's safe codes. */
+const HOST_TOKEN_CODES = new Map([
+  ['reconnect-required', 'reconnect-required'], ['not-connected', 'not-connected'], ['connection-not-found', 'not-connected'],
+  ['revocation-pending', 'not-connected'], ['account-changed', 'account-changed'],
+  // The host's per-connection budget refused the token read: nothing was sent, so it is a quota wait.
+  ['rate-limited', 'quota-delay'],
+]);
+
+/** The host's wait, through the same cap as Google's Retry-After; dropped when unusable. @complexity O(1). */
+function hostRetryAfter(cause) {
+  const retryAfterMs = capRetryAfterMs({ ms: cause?.retryAfterMs });
+  return retryAfterMs === undefined ? {} : { retryAfterMs };
+}
+
+/**
+ * A fresh access token from the host, read right before the request that uses it. A host refusal
+ * becomes the matching safe error (`invalid_grant` surfaces here as `reconnect-required`; a form
+ * delivery then fails at once and stays listed as failed); any other host error passes through
+ * unchanged, since host errors never carry secrets.
+ * @complexity O(1) plus the host's token read.
+ */
+export async function accessTokenFor(required, _optional = {}) {
+  try {
+    return await required.connections.getAccessToken({ connectionRef: required.connectionRef });
+  } catch (cause) {
+    const code = HOST_TOKEN_CODES.get(cause?.code);
+    if (code) throw new GoogleWorkspaceError({ code }, { cause, ...hostRetryAfter(cause) });
+    throw cause;
+  }
+}
+
+function parseJson(text) {
+  try { return JSON.parse(text); } catch { return INVALID_JSON; }
+}
+
+/**
+ * One caller-supplied value as one encoded URL path segment.
+ * @throws {GoogleWorkspaceError} `invalid-input` for an empty, `.` or `..` segment: URL parsing
+ *   resolves those as dot segments and would move the request to another endpoint.
+ * @complexity O(n) characters.
+ */
+export function pathSegment(required, _optional = {}) {
+  const { value } = required;
+  if (typeof value !== 'string' || value === '' || value === '.' || value === '..') throw new GoogleWorkspaceError({ code: 'invalid-input' });
+  return encodeURIComponent(value);
+}
+
+/** `url` plus query parameters; an array value repeats the key (Sheets `ranges=`). @complexity O(q). */
+export function buildUrl(required, _optional = {}) {
+  const url = new URL(required.url);
+  for (const [name, value] of Object.entries(required.query ?? {})) {
+    for (const item of [value].flat()) url.searchParams.append(name, String(item));
+  }
+  return url.href;
+}
+
+function requestInit(request, token, signal) {
+  const headers = { authorization: `Bearer ${token}`, accept: 'application/json' };
+  const body = request.body === undefined ? {} : { body: JSON.stringify(request.body) };
+  if (request.body !== undefined) headers['content-type'] = 'application/json';
+  return { method: request.method ?? 'GET', headers, ...body, ...(signal ? { signal } : {}) };
+}
+
+/** A 2xx body as JSON (empty = null), or the failure a non-2xx or unreadable answer becomes. @complexity O(response). */
+async function readResponse(response, kind) {
+  const text = await response.text();
+  const body = text === '' ? null : parseJson(text);
+  if (response.ok && body !== INVALID_JSON) return { ok: true, value: body };
+  if (response.ok) return { ok: false, error: new GoogleWorkspaceError({ code: 'unexpected-response', outcome: kind === 'read' ? 'not-applied' : 'unknown' }) };
+  return { ok: false, error: classifyFailure({ kind, status: response.status, body: body === INVALID_JSON ? undefined : body, retryAfterHeader: response.headers.get('retry-after') }) };
+}
+
+/**
+ * Creates the client over the host capabilities a module received.
+ * @param {{ http: { fetch(target: { url: string }, init?: RequestInit): Promise<Response> }, connections: { getAccessToken(input: { connectionRef: string }): Promise<string> } }} required
+ * @param {{ sleep?: (ms: number) => Promise<void>, random?: () => number }} [optional]
+ * @complexity O(attempts); each attempt is one token read (where the host charges its budgets) and one request (two after a 401).
+ */
+export function createGoogleClient(required, optional = {}) {
+  const { http, connections } = required;
+  const sleep = optional.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+
+  /**
+   * The token, or the host budget's refusal as a failed attempt: that refusal happens before
+   * anything is sent, so it follows the same backoff rules as Google's 429 (even an append may
+   * wait and retry). Every other host refusal ends the call.
+   */
+  async function tokenOrRefusal(connectionRef) {
+    try {
+      return { token: await accessTokenFor({ connections, connectionRef }) };
+    } catch (error) {
+      if (error instanceof GoogleWorkspaceError && error.code === 'quota-delay') return { error };
+      throw error;
+    }
+  }
+
+  /** One token read and at most one request; never resend a rejected token. @complexity O(1) plus response parsing. */
+  async function attemptOnce(request, { signal, rejectedToken }) {
+    const { token, error } = await tokenOrRefusal(request.connectionRef);
+    if (error) return { ok: false, error, rejectedToken };
+    if (token === rejectedToken) return { ok: false, error: new GoogleWorkspaceError({ code: 'reconnect-required' }) };
+    let response;
+    try {
+      response = await http.fetch({ url: buildUrl(request) }, requestInit(request, token, signal));
+    } catch (cause) {
+      if (signal?.aborted) throw cause;
+      return { ok: false, error: classifyFailure({ kind: request.kind, cause }), rejectedToken };
+    }
+    return { ...(await readResponse(response, request.kind)), unauthorized: response.status === 401, rejectedToken: response.status === 401 ? token : rejectedToken };
+  }
+
+  /**
+   * One attempt, and one more with a different token when Google answered 401. Google refused a
+   * 401 before acting, so even a `write` is safe to send again; a second 401 is final. Jini exposes
+   * no plugin force-refresh option and can return a cached token, which must not be sent again.
+   * @complexity O(1) attempts, at most two token reads and two requests.
+   */
+  async function attemptWithFreshToken(request, { signal, rejectedToken }) {
+    const first = await attemptOnce(request, { signal, rejectedToken });
+    return first.unauthorized ? attemptOnce(request, { signal, rejectedToken: first.rejectedToken }) : first;
+  }
+
+  return {
+    /**
+     * One Google API call with the policy's retries. Resolves the parsed JSON body.
+     * @param {{ connectionRef: string, url: string, method?: string, query?: Record<string, string | number | boolean | readonly (string | number)[]>, body?: unknown, kind: 'read' | 'idempotent-write' | 'write' }} request
+     * @param {{ signal?: AbortSignal }} [options]
+     */
+    async request(request, options = {}) {
+      // One attempt, then (when the policy allows) a wait and the next attempt. Written as a bounded
+      // recursion rather than an endless `for (;;)`: `shouldRetryInline` caps the attempts, so every
+      // path ends in a return or a throw and there is no unreachable loop exit.
+      // A host quota wait must not let a later attempt reuse a token Google already rejected, so the
+      // rejected token is carried into the next attempt.
+      const attemptFrom = async (attempt, rejectedToken) => {
+        const result = await attemptWithFreshToken(request, { signal: options.signal, rejectedToken });
+        if (result.ok) return result.value;
+        const delayMs = backoffMs({ attempt, retryAfterMs: result.error.retryAfterMs }, optional.random ? { random: optional.random } : {});
+        if (!shouldRetryInline({ error: result.error, attempt, delayMs })) throw result.error;
+        await sleep(delayMs);
+        return attemptFrom(attempt + 1, result.rejectedToken);
+      };
+      return attemptFrom(0, undefined);
+    },
+  };
+}