@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/google-workspace/lib/picker-flow.mjs

@@ -0,0 +1,171 @@
+/**
+ * @file The server half of "Choose spreadsheet", shared by the Picker panel and the form-destination
+ * panel: the hosted Picker's bootstrap and its selection check, and the desktop native Picker's start
+ * and finish. Every path ends in `verifySelectedSpreadsheet` (`picker-selection.mjs`) before a
+ * selection is returned, so nothing a browser or a callback claims is saved unchecked.
+ *
+ * Hosted: the bootstrap opens a Picker session in the plugin's own settings (random id, the account
+ * the token belongs to, 15-minute expiry) and gives the surface ONLY a short-lived access token plus
+ * the public Picker config. A selection is accepted only for a live session of this surface, and
+ * only for that same account.
+ *
+ * Desktop: Google's native Picker runs in the system browser as a code + PKCE sign-in with
+ * `trigger_onepick` and the spreadsheet MIME filter. The pending attempt (the host's opaque attempt
+ * id plus the expected account) is kept in the plugin's settings, the frame polls `finish`, and the
+ * `picked_file_ids` callback field is read only through the host's consume-once inbox, which fills
+ * only after the sign-in's state and code checked out. A cancel returns no selection and changes
+ * nothing.
+ *
+ * Which path runs: the host says (`context.hostKind`), never the config. Desktop always uses the
+ * native Picker in the system browser; hosted uses the JS Picker, which needs a browser key and app
+ * id, so a hosted site without both is `unavailable` (`picker-not-configured`) rather than falling
+ * back to a flow built for the desktop app.
+ */
+import { DESKTOP_PICKER_START_PARAMS, parsePickedFileIds, verifySelectedSpreadsheet } from './picker-selection.mjs';
+import { GoogleWorkspaceError } from './request-policy.mjs';
+import { SHEETS_PRODUCT_ID } from './sheets-client.mjs';
+import { CONNECTION_ID, sheetsUnavailableReason, surfaceAccount, surfaceRefusal, surfaceSheetsClient } from './surface-actions.mjs';
+
+// The names keep their `TOVU_` prefix: sites already set them, and renaming would unconfigure them.
+/** Public config the hosted JS Picker needs; placeholders the operator sets, never secrets. */
+export const PICKER_CONFIG_NAMES = Object.freeze({ developerKey: 'TOVU_GOOGLE_PICKER_BROWSER_KEY', appId: 'TOVU_GOOGLE_PICKER_APP_ID' });
+
+/** Long enough to browse Drive in the Picker; short enough that a forgotten tab stops being usable. */
+export const PICKER_SESSION_TTL_MS = 15 * 60_000;
+
+const sessionKey = (surfaceId) => `picker-session:${surfaceId}`;
+const attemptKey = (surfaceId) => `picker-attempt:${surfaceId}`;
+
+/** What the frame and chat may see of a verified spreadsheet: metadata only. */
+export const metadataOf = ({ spreadsheetId, title, url }) => ({ spreadsheetId, title, url });
+
+/** Both hosted Picker values, or null when either is unset. @complexity O(1): two config reads. */
+async function hostedPickerConfig(publicConfig) {
+  const developerKey = await publicConfig.get({ name: PICKER_CONFIG_NAMES.developerKey });
+  const appId = await publicConfig.get({ name: PICKER_CONFIG_NAMES.appId });
+  return developerKey && appId ? { developerKey, appId } : null;
+}
+
+/** The bootstrap for a Picker that cannot run here: the safe code and its fixed sentence. @complexity O(1). */
+const unavailable = (reason) => ({ mode: 'unavailable', reason, message: new GoogleWorkspaceError({ code: reason }).message });
+
+/** A stored session that is this surface's, unexpired, and the one the frame names. @complexity O(1). */
+function isLiveSession(session, sessionId, nowMs) {
+  if (typeof session?.id !== 'string' || session.id !== sessionId) return false;
+  return typeof session.accountId === 'string' && typeof session.expiresAt === 'number' && session.expiresAt > nowMs;
+}
+
+/** A stored desktop attempt in the shape `start` wrote. @complexity O(1). */
+function isPendingAttempt(pending) {
+  return typeof pending?.attemptId === 'string' && typeof pending.accountId === 'string' && typeof pending.expiresAt === 'number';
+}
+
+/**
+ * Builds the Picker flow.
+ * @param {object} [_required]
+ * @param {{ now?: () => number, randomId?: () => string }} [optional] Clock and session-id source (tests).
+ * @returns {{ bootstrap: Function, verifyHosted: Function, startSystemBrowser: Function, finishSystemBrowser: Function }}
+ *   Each takes the handler call (`{ capabilities, context, input?, fail? }`); the verified results
+ *   are `{ spreadsheetId, title, url, accountId }` (the caller strips `accountId` before replying).
+ * @complexity O(1) to build; each step is a bounded number of host and Google calls.
+ */
+export function createPickerFlow(_required = {}, optional = {}) {
+  const now = optional.now ?? Date.now;
+  const randomId = optional.randomId ?? (() => globalThis.crypto.randomUUID());
+
+  /** Opens a hosted session: the account, the token, the public config. @complexity O(1): three requests. */
+  async function openHostedSession(capabilities, context, config) {
+    const account = await surfaceAccount({ capabilities });
+    const accessToken = await capabilities.connections.getAccessToken({ connectionId: CONNECTION_ID });
+    const session = { id: randomId(), accountId: account.accountId, expiresAt: now() + PICKER_SESSION_TTL_MS };
+    await capabilities.state.set({ key: sessionKey(context.surfaceId), value: session });
+    return { mode: 'hosted', accountLabel: account.displayName, picker: { accessToken, ...config, sessionId: session.id } };
+  }
+
+  return {
+    /**
+     * The surface's start data: `unavailable` (with the safe code and its fixed sentence), `system-browser`,
+     * or `hosted` with the Picker session. The one answer that carries an access token.
+     */
+    async bootstrap({ capabilities, context }) {
+      const reason = await sheetsUnavailableReason({ capabilities });
+      if (reason !== null) return unavailable(reason);
+      if (context.hostKind === 'desktop') return { mode: 'system-browser' };
+      const config = await hostedPickerConfig(capabilities.publicConfig);
+      return config === null ? unavailable('picker-not-configured') : openHostedSession(capabilities, context, config);
+    },
+
+    /** Hosted: the frame's `{ sessionId, fileId }` → the verified spreadsheet, for the session's account only. */
+    async verifyHosted({ capabilities, context, input, fail }) {
+      const session = await capabilities.state.get({ key: sessionKey(context.surfaceId) });
+      if (!isLiveSession(session, input.sessionId, now())) throw surfaceRefusal({ fail, code: 'picker-expired' });
+      return verifySelectedSpreadsheet({ client: surfaceSheetsClient({ capabilities }), connectionRef: CONNECTION_ID, fileId: input.fileId, expectedAccountId: session.accountId });
+    },
+
+    /** Desktop: starts the native Picker sign-in; the host page opens it in the system browser. */
+    async startSystemBrowser({ capabilities, context }) {
+      // The account read goes through the Sheets client, so Sheets being off refuses here, before any sign-in.
+      const account = await surfaceAccount({ capabilities });
+      // Native Picker allows drive.file only, so this re-consent asks for the Sheets scope set alone.
+      const started = await capabilities.connections.begin(
+        { connectionId: CONNECTION_ID, action: 'reconnect' },
+        { scopeSetIds: [SHEETS_PRODUCT_ID], startParams: { ...DESKTOP_PICKER_START_PARAMS } },
+      );
+      const pending = { attemptId: started.attemptId, accountId: account.accountId, expiresAt: Date.parse(started.expiresAt) };
+      await capabilities.state.set({ key: attemptKey(context.surfaceId), value: pending });
+      return { expiresAt: started.expiresAt };
+    },
+
+    /**
+     * Desktop: polls the pending attempt. `{ status: 'none' | 'waiting' | 'expired' | 'cancelled' }`,
+     * or `{ status: 'selected', spreadsheet }` once the callback's file id checked out.
+     */
+    async finishSystemBrowser({ capabilities, context }) {
+      const key = attemptKey(context.surfaceId);
+      const pending = await capabilities.state.get({ key });
+      if (!isPendingAttempt(pending)) return { status: 'none' };
+      if (pending.expiresAt <= now()) { await capabilities.state.delete({ key }); return { status: 'expired' }; }
+      const fields = await capabilities.connections.takeCallbackFields({ connectionId: CONNECTION_ID, attemptId: pending.attemptId });
+      if (fields === null) return { status: 'waiting' };
+      await capabilities.state.delete({ key });
+      const fileId = parsePickedFileIds({ value: fields.picked_file_ids });
+      if (fileId === null) return { status: 'cancelled' };
+      const spreadsheet = await verifySelectedSpreadsheet({ client: surfaceSheetsClient({ capabilities }), connectionRef: CONNECTION_ID, fileId, expectedAccountId: pending.accountId });
+      return { status: 'selected', spreadsheet };
+    },
+  };
+}
+
+/** The reply shape of a desktop poll: the spreadsheet's metadata only. @complexity O(1). */
+export function pollReply(required, _optional = {}) {
+  const { outcome } = required;
+  return outcome.status === 'selected' ? { status: 'selected', spreadsheet: metadataOf(outcome.spreadsheet) } : { status: outcome.status };
+}
+
+/** The plugin-settings key holding the spreadsheets picked on the Picker panel, newest first. */
+export const PICKED_SPREADSHEETS_KEY = 'picked-spreadsheets';
+const MAX_PICKED = 10;
+
+/**
+ * The picked spreadsheets kept in the plugin's settings (metadata and the account they were picked
+ * with), newest first; entries in any other shape are dropped.
+ * @param {{ state: { get(input: { key: string }): Promise<unknown> } }} required
+ * @returns {Promise<Array<{ spreadsheetId: string, title: string, url: string, accountId: string }>>}
+ * @complexity O(n), n ≤ 10.
+ */
+export async function readPickedSpreadsheets(required, _optional = {}) {
+  const stored = await required.state.get({ key: PICKED_SPREADSHEETS_KEY });
+  return Array.isArray(stored) ? stored.filter((entry) => typeof entry?.spreadsheetId === 'string' && typeof entry.accountId === 'string') : [];
+}
+
+/**
+ * Saves a VERIFIED selection at the top of the picked list (one entry per spreadsheet, at most 10).
+ * @param {{ state: { get: Function, set: Function }, spreadsheet: { spreadsheetId: string, title: string, url: string, accountId: string } }} required
+ * @complexity O(n), n ≤ 10.
+ */
+export async function rememberPickedSpreadsheet(required, _optional = {}) {
+  const { state, spreadsheet } = required;
+  const others = (await readPickedSpreadsheets({ state })).filter((entry) => entry.spreadsheetId !== spreadsheet.spreadsheetId);
+  const entry = { ...metadataOf(spreadsheet), accountId: spreadsheet.accountId };
+  await state.set({ key: PICKED_SPREADSHEETS_KEY, value: [entry, ...others].slice(0, MAX_PICKED) });
+}

package/google-workspace/lib/picker-selection.mjs

@@ -0,0 +1,107 @@
+/**
+ * @file Server-side checks for a Google Picker selection, shared by the hosted JS Picker surface and
+ * the desktop native Picker (system browser, `picked_file_ids` callback field).
+ *
+ * Exists because a selection is only a claim until the server re-checks it: the browser (or the
+ * callback) names a file id, and under `drive.file` that id is useful only if the Picker really
+ * granted it to THIS account. So a selection is saved only after: the id is a plain Drive id (it is
+ * placed in URL paths), the connection is still the account the Picker was opened for, Drive says
+ * the file is a Google Sheets spreadsheet, and the Sheets API actually opens it. A pasted URL never
+ * reaches here as a grant. Results are file metadata only, never contents or tokens.
+ */
+import { DRIVE_FILES_URL, readAccount } from './drive-files.mjs';
+import { pathSegment } from './http.mjs';
+import { GoogleWorkspaceError } from './request-policy.mjs';
+import { assertSpreadsheetId, sheetsUrl } from './sheets-client.mjs';
+
+export const SPREADSHEET_MIME_TYPE = 'application/vnd.google-apps.spreadsheet';
+
+/**
+ * Extra authorization parameters for "Choose spreadsheet" on desktop: Google's native Picker in the
+ * system browser, one file, spreadsheets only. The connection descriptor allowlists both names
+ * (`startParams`); `prompt=consent` already comes from its installed-app parameters.
+ */
+export const DESKTOP_PICKER_START_PARAMS = Object.freeze({ trigger_onepick: 'true', mimetypes: SPREADSHEET_MIME_TYPE });
+
+// Drive ids are URL-safe base64-like strings; anything else could reshape the request path.
+const assertFileId = (value) => assertSpreadsheetId({ id: value }, { code: 'invalid-selection' });
+
+/**
+ * The one file id a desktop native Picker callback carried, or null when the person cancelled.
+ * `picked_file_ids` is comma-separated; "Choose spreadsheet" asks for one file, so more than one is
+ * refused rather than guessing which to keep. Call only after the sign-in's state and code checked out.
+ * @param {{ value: string | undefined }} required The raw `picked_file_ids` callback field.
+ * @returns {string | null}
+ * @throws {GoogleWorkspaceError} `invalid-selection`.
+ * @complexity O(n) in the field length (the connection descriptor caps it at 4096).
+ */
+export function parsePickedFileIds(required, _optional = {}) {
+  const { value } = required;
+  if (value === undefined || value === '') return null;
+  const ids = value.split(',');
+  if (ids.length !== 1) throw new GoogleWorkspaceError({ code: 'invalid-selection' });
+  return assertFileId(ids[0]);
+}
+
+/** Drive metadata for the file; refuses a trashed file and anything but a spreadsheet. @complexity O(1): one request. */
+async function readSpreadsheetFile(client, connectionRef, fileId, optional) {
+  const file = await client.request({
+    connectionRef, url: `${DRIVE_FILES_URL}/${pathSegment({ value: fileId })}`, kind: 'read',
+    query: { fields: 'id,name,mimeType,trashed', supportsAllDrives: 'true' },
+  }, optional);
+  if (file?.id !== fileId) throw new GoogleWorkspaceError({ code: 'unexpected-response' });
+  // A trashed file still answers files.get, but it is no longer a spreadsheet anyone works in.
+  if (file.trashed === true) throw new GoogleWorkspaceError({ code: 'file-not-granted' });
+  if (file.mimeType !== SPREADSHEET_MIME_TYPE) throw new GoogleWorkspaceError({ code: 'not-a-spreadsheet' });
+  return file;
+}
+
+/** Opens the spreadsheet through the Sheets API itself: Drive metadata alone does not prove access. @complexity O(1). */
+async function openSpreadsheet(client, connectionRef, fileId, optional) {
+  const sheet = await client.request({
+    connectionRef, url: sheetsUrl({ spreadsheetId: fileId }), kind: 'read',
+    query: { fields: 'spreadsheetId,properties.title' },
+  }, optional);
+  if (sheet?.spreadsheetId !== fileId) throw new GoogleWorkspaceError({ code: 'unexpected-response' });
+  return sheet;
+}
+
+/**
+ * Whether the connected account can really work in this spreadsheet: Drive says it is a live Google
+ * Sheets file, and the Sheets API opens it. Shared by the Picker check below and
+ * `sheets_open_existing`. The link is built from the verified id, never taken from Google.
+ * @param {{ client: { request(input: object, options?: object): Promise<unknown> }, connectionRef: string, fileId: string }} required
+ *   `fileId` already passed {@link assertSpreadsheetId}.
+ * @param {{ signal?: AbortSignal }} [optional]
+ * @returns {Promise<{ spreadsheetId: string, title: string, url: string }>}
+ * @throws {GoogleWorkspaceError} `not-a-spreadsheet`, `file-not-granted` / `access-denied`, `unexpected-response`.
+ * @complexity O(1): two requests (Drive metadata, Sheets).
+ */
+export async function verifySpreadsheetAccess(required, optional = {}) {
+  const { client, connectionRef, fileId } = required;
+  const file = await readSpreadsheetFile(client, connectionRef, fileId, optional);
+  const sheet = await openSpreadsheet(client, connectionRef, fileId, optional);
+  const title = sheet.properties?.title ?? file.name ?? 'Untitled spreadsheet';
+  return { spreadsheetId: fileId, title, url: `https://docs.google.com/spreadsheets/d/${fileId}/edit` };
+}
+
+/**
+ * Verifies a Picker selection before anything saves it: the id, the account, then
+ * {@link verifySpreadsheetAccess}.
+ * @param {{ client: { request(input: object, options?: object): Promise<unknown> }, connectionRef: string, fileId: unknown, expectedAccountId: string }} required
+ *   `expectedAccountId` is the account the Picker session was opened for (hosted: the bootstrap's;
+ *   desktop: the connection's account when "Choose spreadsheet" started).
+ * @param {{ signal?: AbortSignal }} [optional]
+ * @returns {Promise<{ spreadsheetId: string, title: string, accountId: string, url: string }>}
+ * @throws {GoogleWorkspaceError} `invalid-selection`, `account-changed`, `not-a-spreadsheet`,
+ *   `file-not-granted` / `access-denied` (from the client), `unexpected-response`.
+ * @complexity O(1): three requests (account, Drive metadata, Sheets).
+ */
+export async function verifySelectedSpreadsheet(required, optional = {}) {
+  const { client, connectionRef, expectedAccountId } = required;
+  const fileId = assertFileId(required.fileId);
+  const account = await readAccount({ client, connectionRef }, optional);
+  if (account.accountId !== expectedAccountId) throw new GoogleWorkspaceError({ code: 'account-changed' });
+  const verified = await verifySpreadsheetAccess({ client, connectionRef, fileId }, optional);
+  return { ...verified, accountId: account.accountId };
+}

package/google-workspace/lib/product-state.mjs

@@ -0,0 +1,93 @@
+/**
+ * @file The Google Workspace product catalog (`products.json`): which products the plugin ships and
+ * which Google scopes each one needs. Turns the host's opaque scope-set ids (the products being
+ * connected) into the exact scope list the sign-in requests.
+ *
+ * Exists because enabling a product and granting its scopes are separate steps: the catalog is the
+ * one place that says what a product needs, so the sign-in never asks for more than the products
+ * being connected. v1 ships Sheets only, on `drive.file` (files the person picked or the site created).
+ *
+ * Also the one on/off gate per product. The plugin's own settings (the host's plugin state, which the
+ * Google Workspace panel writes and tools and form delivery may only read) hold
+ * `products: { "<productId>": true }`. A product is OFF unless that value is exactly `true`
+ * (fail closed: no settings, no reader, or any other value). Turning a product off blocks its
+ * tools and refuses its form deliveries as retryable (the forms retry policy re-tries them for about
+ * a day, then marks them failed); it never revokes the Google authorization.
+ */
+import catalog from '../products.json' with { type: 'json' };
+import { GoogleWorkspaceError } from './request-policy.mjs';
+
+const GOOGLE_SCOPE = /^https:\/\/www\.googleapis\.com\/auth\/[a-z.]+$/;
+
+/** A catalog entry that is not well formed stops the plugin loading, instead of requesting odd scopes. @complexity O(s). */
+function assertScopes(scopes, where) {
+  if (!Array.isArray(scopes) || !scopes.every((scope) => GOOGLE_SCOPE.test(scope))) {
+    throw new Error(`products.json ${where} must list Google OAuth scope URLs. Fix the plugin package.`);
+  }
+  return Object.freeze([...scopes]);
+}
+
+/**
+ * The validated, frozen catalog. Exported so the load-time check can be pinned against malformed
+ * catalogs (the shipped `products.json` always passes it).
+ * @param {{ raw: { baseScopes: unknown, products: readonly { id: string, requiredScopes: unknown }[] } }} required
+ * @throws {Error} When a scope list is not a list of Google OAuth scope URLs.
+ * @complexity O(p * s).
+ */
+export function readCatalog(required, _optional = {}) {
+  const { raw } = required;
+  const products = raw.products.map((product) => Object.freeze({
+    ...product,
+    requiredScopes: assertScopes(product.requiredScopes, `products '${product.id}' requiredScopes`),
+  }));
+  return Object.freeze({ baseScopes: assertScopes(raw.baseScopes, 'baseScopes'), products: Object.freeze(products) });
+}
+
+export const PRODUCTS = readCatalog({ raw: catalog });
+
+/**
+ * The scopes to request for these products: the base scope plus each product's required scopes,
+ * de-duplicated in catalog order. An id the catalog does not know is refused, never ignored, so a
+ * typo cannot silently connect less than the person chose.
+ * @param {{ productIds: readonly string[] }} required
+ * @returns {readonly string[]}
+ * @complexity O(p * s).
+ */
+export function scopesFor(required, _optional = {}) {
+  const chosen = required.productIds.map((id) => {
+    const product = PRODUCTS.products.find((entry) => entry.id === id);
+    if (!product) throw new Error(`Google Workspace has no product '${id}'. Choose one of: ${PRODUCTS.products.map((entry) => entry.id).join(', ')}.`);
+    return product;
+  });
+  return [...new Set([...PRODUCTS.baseScopes, ...chosen.flatMap((product) => product.requiredScopes)])];
+}
+
+/** The plugin-state key whose value says which products are on: `{ "<productId>": true }`. */
+export const PRODUCT_STATE_KEY = 'products';
+
+/**
+ * Whether the product is on in the plugin's own settings. Off when there is no reader, nothing is
+ * stored, or the stored value is anything but `true` for this product.
+ * @param {{ state?: { get(input: { key: string }): Promise<unknown> }, productId: string }} required
+ *   `state` is the host's read-only plugin-state reader (`capabilities.state` for tools).
+ * @returns {Promise<boolean>}
+ * @complexity O(1): one state read.
+ */
+export async function isProductEnabled(required, _optional = {}) {
+  const { state, productId } = required;
+  if (typeof state?.get !== 'function') return false;
+  const value = await state.get({ key: PRODUCT_STATE_KEY });
+  return value?.[productId] === true;
+}
+
+/**
+ * Refuses unless the product is on, before anything is sent to Google.
+ * @param {{ state?: { get(input: { key: string }): Promise<unknown> }, productId: string }} required
+ * @throws {GoogleWorkspaceError} `product-disabled` (next action: turn the product on in the panel).
+ * @complexity O(1): one state read.
+ */
+export async function assertProductEnabled(required, _optional = {}) {
+  if (await isProductEnabled(required)) return;
+  const label = PRODUCTS.products.find((product) => product.id === required.productId)?.label ?? required.productId;
+  throw new GoogleWorkspaceError({ code: 'product-disabled' }, { detail: label });
+}

package/google-workspace/lib/request-policy.mjs

@@ -0,0 +1,163 @@
+/**
+ * @file Google request policy for the Google Workspace plugin: the safe error every failure becomes,
+ * whether a failed request may be retried and how long to wait. The per-minute budgets themselves
+ * are declared in `tovu-connections.json` and enforced by the host on every token read.
+ *
+ * Exists so chat tools, admin actions and form delivery share ONE answer to "may this run again?"
+ * and one error vocabulary. Errors never carry tokens, Google's own message text or sheet contents:
+ * Google echoes ranges and values in its messages, so only a fixed sentence per code is shown.
+ */
+
+/** Longest wait spent inside one call; a longer Retry-After is returned to the caller instead. */
+export const MAX_INLINE_WAIT_MS = 10_000;
+export const MAX_ATTEMPTS = 3;
+const BASE_BACKOFF_MS = 500;
+const MAX_RETRY_AFTER_MS = 15 * 60_000;
+
+/** Every safe code: whether a retry can help, what the person does next, and the fixed sentence. */
+const SAFE_ERRORS = Object.freeze({
+  'invalid-request': { retryable: false, nextAction: 'fix-request', message: 'Google rejected the request as invalid. Check the spreadsheet, tab, range and values, then try again.' },
+  'not-connected': { retryable: false, nextAction: 'connect', message: 'Google Workspace is not connected. Connect it from the Google Workspace plugin, then retry.' },
+  'reconnect-required': { retryable: false, nextAction: 'reconnect', message: 'Reconnect required: Google no longer accepts the saved sign-in. Reconnect Google Workspace, then retry.' },
+  'account-changed': { retryable: false, nextAction: 'review-account', message: 'The connected Google account changed since this was confirmed. Review the account and confirm again.' },
+  'missing-permission': { retryable: false, nextAction: 'grant-permission', message: 'The connected Google account has not granted a permission this needs. Reconnect and allow every requested permission.' },
+  'file-not-granted': { retryable: false, nextAction: 're-pick-file', message: 'This site cannot open this file with the connected Google account. Choose it again with the file picker, or create a new spreadsheet.' },
+  'access-denied': { retryable: false, nextAction: 're-pick-file', message: 'Google refused access to this file for the connected account. Check that the account can edit it, then choose it again.' },
+  'admin-policy': { retryable: false, nextAction: 'contact-admin', message: "A Google Workspace administrator's policy blocks this. Ask the administrator to allow this site, then retry." },
+  'conflict': { retryable: true, nextAction: 'retry-later', message: 'Google reported a conflicting change. Retry in a moment.' },
+  'quota-delay': { retryable: true, nextAction: 'retry-later', message: 'Google asked this site to slow down. Nothing was lost; retry after the delay.' },
+  'service-unavailable': { retryable: true, nextAction: 'retry-later', message: 'Google is temporarily unavailable. Nothing was lost; retry later.' },
+  'network-error': { retryable: true, nextAction: 'retry-later', message: 'This site could not reach Google. Check the connection and retry later.' },
+  'uncertain-outcome': { retryable: false, nextAction: 'review-outcome', message: 'Google did not confirm whether the change was applied. Check the spreadsheet before trying again.' },
+  'unexpected-response': { retryable: false, nextAction: 'report', message: 'Google returned a response this site does not understand. Report this to the plugin author.' },
+  'product-disabled': { retryable: false, nextAction: 'enable-product', message: 'This Google product is turned off. Turn it on in the Google Workspace panel, then retry; the Google sign-in is kept.' },
+  'picker-not-configured': { retryable: false, nextAction: 'contact-admin', message: "Choosing an existing spreadsheet is not set up on this site yet (the Google file picker is not configured). Add this site's Google Picker browser key and app ID, or create a new spreadsheet." },
+  'invalid-selection': { retryable: false, nextAction: 're-pick-file', message: 'The file picker returned a selection this site cannot use. Choose the spreadsheet again.' },
+  'not-a-spreadsheet': { retryable: false, nextAction: 're-pick-file', message: 'The chosen file is not a Google Sheets spreadsheet. Choose a spreadsheet, or create a new one.' },
+  // Refused by the plugin before anything was sent to Google (bounds and input checks of the Sheets tools).
+  'invalid-input': { retryable: false, nextAction: 'fix-request', message: 'This request is not valid for the tool. Check the spreadsheet id, tab, range and options, then try again. Nothing was sent to Google.' },
+  'limit-exceeded': { retryable: false, nextAction: 'narrow-request', message: 'This request or its result is larger than the tool allows. Ask for a smaller range, fewer rows or fewer entries, then try again.' },
+  'export-unavailable': { retryable: false, nextAction: 'read-in-chat', message: 'Saving a CSV file is not available on this site. Nothing was read from Google; read the values in chat instead (sheets_values_get or sheets_values_batch_get).' },
+  'unsupported-request': { retryable: false, nextAction: 'fix-request', message: 'The batch contains a request kind Google Workspace tools do not support (only reviewed, generally available Sheets request kinds are allowed). Remove it and retry; nothing was sent to Google.' },
+});
+
+/** A failure a person can act on. `outcome` says whether the request may have changed anything. */
+export class GoogleWorkspaceError extends Error {
+  /**
+   * @param {{ code: keyof typeof SAFE_ERRORS, outcome?: 'not-applied' | 'unknown' }} required
+   * @param {{ retryAfterMs?: number, cause?: unknown, detail?: string }} [optional] `detail` is a
+   *   short pointer the plugin itself composes (a request index, a kind name it validated); never
+   *   Google's text, a token or a cell value.
+   */
+  constructor(required, optional = {}) {
+    const safe = SAFE_ERRORS[required.code];
+    const message = optional.detail === undefined ? safe.message : `${safe.message} (${optional.detail})`;
+    super(message, optional.cause === undefined ? undefined : { cause: optional.cause });
+    this.name = 'GoogleWorkspaceError';
+    this.code = required.code;
+    this.retryable = safe.retryable;
+    this.nextAction = safe.nextAction;
+    this.outcome = required.outcome ?? 'not-applied';
+    if (optional.retryAfterMs !== undefined) this.retryAfterMs = optional.retryAfterMs;
+  }
+
+  /** The tool-output shape: never the cause, which may hold provider text. */
+  toJSON() {
+    const { code, message, retryable, outcome, nextAction, retryAfterMs } = this;
+    return { code, message, retryable, outcome, nextAction, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) };
+  }
+}
+
+/** Google's machine-readable reasons (Drive `errors[].reason`, Sheets `details[].reason`) → code. */
+const REASON_CODES = new Map([
+  ['rateLimitExceeded', 'quota-delay'], ['userRateLimitExceeded', 'quota-delay'], ['RATE_LIMIT_EXCEEDED', 'quota-delay'],
+  ['insufficientPermissions', 'missing-permission'], ['ACCESS_TOKEN_SCOPE_INSUFFICIENT', 'missing-permission'],
+  ['appNotAuthorizedToFile', 'file-not-granted'], ['domainPolicy', 'admin-policy'],
+]);
+const STATUS_CODES = new Map([
+  [400, 'invalid-request'], [401, 'reconnect-required'], [403, 'access-denied'], [404, 'file-not-granted'],
+  [409, 'conflict'], [412, 'conflict'], [413, 'invalid-request'], [429, 'quota-delay'],
+]);
+
+/** The reasons named in a Google error body; a body that is not Google's shape names none. @complexity O(r). */
+export function errorReasons(required, _optional = {}) {
+  const error = required.body?.error;
+  if (typeof error !== 'object' || error === null) return [];
+  const listed = [...(Array.isArray(error.errors) ? error.errors : []), ...(Array.isArray(error.details) ? error.details : [])];
+  return listed.map((entry) => entry?.reason).filter((reason) => typeof reason === 'string');
+}
+
+/**
+ * Retry-After as milliseconds (delta-seconds or an HTTP date), capped; undefined when absent or unusable.
+ * @complexity O(1).
+ */
+export function parseRetryAfter(required, optional = {}) {
+  const raw = required.header?.trim();
+  if (!raw) return undefined;
+  const nowMs = optional.nowMs ?? Date.now();
+  const ms = /^\d+$/.test(raw) ? Number(raw) * 1000 : Date.parse(raw) - nowMs;
+  return capRetryAfterMs({ ms });
+}
+
+/**
+ * A wait in milliseconds, capped; undefined when it is not a finite, non-negative number. Shared by
+ * Google's Retry-After and the host's budget refusal so both obey one ceiling.
+ * @complexity O(1).
+ */
+export function capRetryAfterMs(required, _optional = {}) {
+  const { ms } = required;
+  return Number.isFinite(ms) && ms >= 0 ? Math.min(ms, MAX_RETRY_AFTER_MS) : undefined;
+}
+
+/**
+ * The safe code for an HTTP failure: a known reason wins, then the status, then 5xx → unavailable.
+ * @complexity O(r) reasons.
+ */
+export function codeForStatus(required, _optional = {}) {
+  const fromReason = required.reasons.map((reason) => REASON_CODES.get(reason)).find(Boolean);
+  if (fromReason) return fromReason;
+  return STATUS_CODES.get(required.status) ?? (required.status >= 500 ? 'service-unavailable' : 'unexpected-response');
+}
+
+/**
+ * Whether a failed request may have been applied. Only a non-read can be applied; 4xx means Google
+ * refused it before acting, while a 5xx or a lost response leaves it unknown.
+ * @complexity O(1).
+ */
+function outcomeFor(kind, status) {
+  if (kind === 'read') return 'not-applied';
+  return status !== undefined && status < 500 ? 'not-applied' : 'unknown';
+}
+
+/**
+ * The safe error for one failed attempt. `kind` is `read`, `idempotent-write` (same request, same
+ * result: values update/clear) or `write` (append, create, copy). An unknown outcome of a `write`
+ * is `uncertain-outcome` and never retryable: replaying it could apply it twice.
+ * @param {{ kind: 'read' | 'idempotent-write' | 'write', status?: number, body?: unknown, retryAfterHeader?: string | null, cause?: unknown }} required
+ * @param {{ nowMs?: number }} [optional]
+ * @complexity O(r) reasons.
+ */
+export function classifyFailure(required, optional = {}) {
+  const { kind, status, cause } = required;
+  const outcome = outcomeFor(kind, status);
+  if (kind === 'write' && outcome === 'unknown') return new GoogleWorkspaceError({ code: 'uncertain-outcome', outcome }, { cause });
+  const code = status === undefined ? 'network-error' : codeForStatus({ status, reasons: errorReasons({ body: required.body }) });
+  const retryAfterMs = parseRetryAfter({ header: required.retryAfterHeader ?? undefined }, optional);
+  return new GoogleWorkspaceError({ code, outcome }, { ...(retryAfterMs === undefined ? {} : { retryAfterMs }), ...(cause === undefined ? {} : { cause }) });
+}
+
+/**
+ * Delay before attempt `attempt + 1`: full-jitter exponential backoff, never shorter than Google's
+ * Retry-After.
+ * @complexity O(1).
+ */
+export function backoffMs(required, optional = {}) {
+  const random = optional.random ?? Math.random;
+  const jittered = Math.round(random() * BASE_BACKOFF_MS * 2 ** required.attempt);
+  return Math.max(required.retryAfterMs ?? 0, jittered);
+}
+
+/** Whether to wait and try again inside this call. @complexity O(1). */
+export function shouldRetryInline(required, _optional = {}) {
+  return required.error.retryable && required.attempt + 1 < MAX_ATTEMPTS && required.delayMs <= MAX_INLINE_WAIT_MS;
+}

package/google-workspace/lib/sheets-a1.mjs

@@ -0,0 +1,79 @@
+/**
+ * @file The A1-notation helpers of the Google Workspace plugin's Sheets code (tools, CSV export and
+ * form delivery): column letters, Google's normalized range parsed into parts, the strict
+ * two-corner range the CSV export plans with, tab-title quoting, and the person-readable label of a
+ * Sheets `GridRange` the confirmation card shows.
+ *
+ * Exists so each of these has ONE name and ONE contract: a range Google returns is parsed one way
+ * (`parseA1Range`, undefined when not in Google's shape), a range a person gives the export another
+ * (`parseBoundsA1`, refused when not a plain `A1:B2`), and a tab title is quoted one way
+ * (`tabRange`), so a title can never change which cells a range names.
+ */
+import { GoogleWorkspaceError } from './request-policy.mjs';
+
+/** 0 → `A`, 25 → `Z`, 26 → `AA`. @complexity O(letters). */
+export function columnName(required, _optional = {}) {
+  let name = '';
+  for (let n = required.index + 1; n > 0; n = Math.floor((n - 1) / 26)) name = String.fromCharCode(65 + ((n - 1) % 26)) + name;
+  return name;
+}
+
+/** `A` → 0, `AA` → 26. @complexity O(letters). */
+export function columnIndex(required, _optional = {}) {
+  return [...required.column].reduce((index, letter) => index * 26 + letter.charCodeAt(0) - 64, 0) - 1;
+}
+
+/** `'Tab ''name'''!<cells>`: the title quoted, its quotes doubled, so a title cannot change the range. @complexity O(title). */
+export function tabRange(required, _optional = {}) {
+  return `'${required.title.replaceAll("'", "''")}'!${required.cells}`;
+}
+
+const GOOGLE_RANGE = /^(?<sheet>.+)!(?<startColumn>[A-Z]+)(?<startRow>\d+)(?::(?<endColumn>[A-Z]+)(?<endRow>\d+))?$/;
+
+/**
+ * Google's normalized A1 range (`'Tab name'!B2:D90`) as its parts; undefined when it is not in that
+ * shape (Google normalizes every values range it returns to it).
+ * @complexity O(n) characters.
+ */
+export function parseA1Range(required, _optional = {}) {
+  const groups = GOOGLE_RANGE.exec(required.range ?? '')?.groups;
+  if (!groups) return undefined;
+  return { sheet: groups.sheet, startColumn: groups.startColumn, startRow: Number(groups.startRow), endColumn: groups.endColumn, endRow: groups.endRow === undefined ? undefined : Number(groups.endRow) };
+}
+
+const BOUNDS_RANGE = /^([A-Z]{1,3})([1-9]\d{0,6}):([A-Z]{1,3})([1-9]\d{0,6})$/;
+
+/**
+ * Zero-based inclusive bounds of a two-corner A1 range such as `B2:F200` (no tab name): the CSV
+ * export bounds its reads from it before it sends any.
+ * @returns {{ firstRow: number, lastRow: number, firstColumn: number, lastColumn: number }}
+ * @throws {GoogleWorkspaceError} `invalid-input` for anything else, including reversed corners.
+ * @complexity O(1).
+ */
+export function parseBoundsA1(required, _optional = {}) {
+  const match = BOUNDS_RANGE.exec(required.range);
+  const bounds = match && { firstColumn: columnIndex({ column: match[1] }), firstRow: Number(match[2]) - 1, lastColumn: columnIndex({ column: match[3] }), lastRow: Number(match[4]) - 1 };
+  if (!bounds || bounds.lastRow < bounds.firstRow || bounds.lastColumn < bounds.firstColumn) {
+    throw new GoogleWorkspaceError({ code: 'invalid-input' }, { detail: 'range must look like A1:D200, top-left corner first' });
+  }
+  return bounds;
+}
+
+/** "rows 2-10", "rows 2 onward" or "all rows" for zero-based [start, end). @complexity O(1). */
+function span(name, start, end, show) {
+  if (start === undefined && end === undefined) return `all ${name}`;
+  const first = show(start ?? 0);
+  return end === undefined ? `${name} ${first} onward` : `${name} ${first}-${show(end - 1)}`;
+}
+
+/**
+ * The card label of a `GridRange`: `tab 0, rows 2-10, columns A-D`, instead of raw zero-based indices.
+ * @param {{ range: { sheetId: number, startRowIndex?: number, endRowIndex?: number, startColumnIndex?: number, endColumnIndex?: number } }} required
+ * @complexity O(1).
+ */
+export function gridRangeLabel(required, _optional = {}) {
+  const { sheetId, startRowIndex, endRowIndex, startColumnIndex, endColumnIndex } = required.range;
+  const rows = span('rows', startRowIndex, endRowIndex, (index) => String(index + 1));
+  const columns = span('columns', startColumnIndex, endColumnIndex, (index) => columnName({ index }));
+  return `tab ${sheetId}, ${rows}, ${columns}`;
+}