@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/google-workspace/lib/sheets-admin-csv.mjs

@@ -0,0 +1,82 @@
+/**
+ * @file CSV export planning and encoding for the `export_csv` tool: split one tab (or an A1 range of
+ * it) into bounded values reads, and encode the rows as RFC 4180 CSV.
+ *
+ * Exists because Google's own CSV export covers only a spreadsheet's first tab and an arbitrary tab
+ * would need an undocumented `gid` URL; bounded `values.batchGet` reads plus local encoding work for
+ * any tab. The size is bounded BEFORE the first read (from the tab's grid size or the range), and an
+ * export over a bound is an error, never a silently partial file. Text cells that start like a
+ * formula are prefixed with `'` so opening the file never runs a visitor's formula.
+ */
+import { GoogleWorkspaceError } from './request-policy.mjs';
+import { columnName, tabRange } from './sheets-a1.mjs';
+
+export const MAX_EXPORT_ROWS = 20_000;
+export const MAX_EXPORT_CELLS = 100_000;
+export const MAX_CSV_BYTES = 4 * 1024 * 1024;
+/** Cells per read: keeps each answer far below the host's 1 MiB response bound. */
+const CHUNK_CELLS = 10_000;
+
+const tooLarge = (detail) => new GoogleWorkspaceError({ code: 'limit-exceeded' }, { detail });
+
+/**
+ * The reads covering `area` (zero-based, inclusive), in row order.
+ * @param {{ title: string, area: { firstRow: number, lastRow: number, firstColumn: number, lastColumn: number } }} required
+ * @returns {{ range: string, rowCount: number }[]}
+ * @throws {GoogleWorkspaceError} `limit-exceeded` when the area is over the row or cell bound.
+ * @complexity O(chunks), at most MAX_EXPORT_CELLS / CHUNK_CELLS.
+ */
+export function planChunks(required, _optional = {}) {
+  const { firstRow, lastRow, firstColumn, lastColumn } = required.area;
+  const rows = lastRow - firstRow + 1;
+  const columns = lastColumn - firstColumn + 1;
+  if (rows > MAX_EXPORT_ROWS) throw tooLarge(`at most ${MAX_EXPORT_ROWS} rows; give a range`);
+  if (rows * columns > MAX_EXPORT_CELLS) throw tooLarge(`at most ${MAX_EXPORT_CELLS} cells; give a smaller range`);
+  const rowsPerChunk = Math.max(1, Math.floor(CHUNK_CELLS / columns));
+  const [from, to] = [columnName({ index: firstColumn }), columnName({ index: lastColumn })];
+  const chunks = [];
+  for (let start = firstRow; start <= lastRow; start += rowsPerChunk) {
+    const end = Math.min(lastRow, start + rowsPerChunk - 1);
+    chunks.push({ range: tabRange({ title: required.title, cells: `${from}${start + 1}:${to}${end + 1}` }), rowCount: end - start + 1 });
+  }
+  return chunks;
+}
+
+/**
+ * Text a spreadsheet app would run as a formula when it opens the CSV (OWASP "CSV injection"):
+ * a leading `=`, `+`, `-`, `@`, tab or carriage return. Form answers are stored RAW, so a visitor's
+ * `=HYPERLINK(...)` comes back from Google as plain text and would otherwise become live.
+ */
+const FORMULA_TRIGGER = /^[=+\-@\t\r]/;
+
+/**
+ * One CSV field: text that a spreadsheet app would evaluate gets a leading `'` (shown as text, not
+ * run), then the field is quoted when it holds a comma, quote or line break. Only strings are
+ * prefixed: a number Google returns as a number (`UNFORMATTED_VALUE`) stays exact, while a
+ * formatted value such as `-5` or `+1 555` is text and keeps the `'` (the fidelity trade-off,
+ * documented in `references/sheets.md`).
+ * @complexity O(length).
+ */
+function csvField(value) {
+  const raw = value === undefined || value === null ? '' : String(value);
+  const text = typeof value === 'string' && FORMULA_TRIGGER.test(value) ? `'${raw}` : raw;
+  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+/**
+ * RFC 4180 CSV (CRLF line ends) of `rows`, padded to the widest row, trailing empty rows dropped.
+ * @param {{ rows: readonly (readonly unknown[])[] }} required
+ * @returns {{ csv: string, rows: number, columns: number, bytes: number }}
+ * @throws {GoogleWorkspaceError} `limit-exceeded` over {@link MAX_CSV_BYTES}.
+ * @complexity O(cells).
+ */
+export function encodeCsv(required, _optional = {}) {
+  let used = required.rows.length;
+  while (used > 0 && required.rows[used - 1].length === 0) used -= 1;
+  const kept = required.rows.slice(0, used);
+  const columns = Math.max(0, ...kept.map((row) => row.length));
+  const csv = kept.map((row) => Array.from({ length: columns }, (_, index) => csvField(row[index])).join(',')).join('\r\n');
+  const bytes = Buffer.byteLength(csv);
+  if (bytes > MAX_CSV_BYTES) throw tooLarge('the CSV would be over 4 MiB; give a smaller range');
+  return { csv, rows: used, columns, bytes };
+}

package/google-workspace/lib/sheets-admin-request-kinds.mjs

@@ -0,0 +1,183 @@
+/**
+ * @file The reviewed inventory of Sheets `spreadsheets.batchUpdate` request kinds the Google
+ * Workspace tools may send, and the one check every batch passes before it reaches Google (the raw
+ * `batch_update` tool and every named wrapper: tab, sort, filter, format, named ranges).
+ *
+ * Exists because a raw batch tool is the broad-coverage escape hatch, so it must fail closed: only
+ * kinds listed here are sent; an unknown, misspelt or preview kind is refused before any request.
+ * Each listed kind carries:
+ * - `effect`: `destructive` when it deletes something, overwrites or moves cell values, or changes
+ *   protection; otherwise `write`. The confirmation card names every kind with its effect.
+ * - `replay`: `unsafe` when sending the same request twice can change the sheet twice (adds,
+ *   inserts, appends, deletes by index, moves, find/replace, randomize). A batch holding one is a
+ *   `write` for the HTTP client, so an unknown outcome is `uncertain-outcome` and never replayed.
+ *   The class judges a request ALONE. Google applies a batch's requests in order, so two safe kinds
+ *   can compose into an unsafe sequence (copy A1 to B1, then set A1: a replay copies the new A1 into
+ *   B1). No sequence is reviewed as safe, so a batch of more than one request is always a `write`.
+ * - `requires`: the fields Google needs; an inner array means "at least one of". `fields` (the field
+ *   mask) must be explicit: `*` would reset every property the request does not set.
+ *
+ * Reviewed against the Request union of Sheets API v4
+ * (https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request).
+ * Deliberately NOT listed (refused as unsupported): the data-source kinds (`addDataSource`,
+ * `updateDataSource`, `deleteDataSource`, `refreshDataSource`, `cancelDataSourceRefresh`). They need
+ * Connected Sheets and a BigQuery permission that this sign-in never requests (drive.file only);
+ * offering them would only produce permission failures. Adding a kind means reviewing it against the
+ * reference and adding one row here.
+ */
+import { GoogleWorkspaceError } from './request-policy.mjs';
+
+export const MAX_BATCH_REQUESTS = 100;
+export const MAX_BATCH_BYTES = 1024 * 1024;
+/** The confirmation card shows at most 50 lines: one for the spreadsheet, one per kind. */
+export const MAX_DISTINCT_KINDS = 48;
+
+const W = 'write';
+const D = 'destructive';
+const SAFE = 'idempotent';
+const UNSAFE = 'unsafe';
+
+/** [kind, effect, replay, requires] */
+const ROWS = [
+  ['updateSpreadsheetProperties', W, SAFE, ['properties', 'fields']],
+  // Shrinking gridProperties.rowCount/columnCount deletes cells.
+  ['updateSheetProperties', D, SAFE, ['properties', 'fields']],
+  ['updateDimensionProperties', W, SAFE, ['properties', 'fields', ['range', 'dataSourceSheetRange']]],
+  ['updateNamedRange', W, SAFE, ['namedRange', 'fields']],
+  ['repeatCell', D, SAFE, ['range', 'cell', 'fields']],
+  ['addNamedRange', W, UNSAFE, ['namedRange']],
+  ['deleteNamedRange', D, SAFE, ['namedRangeId']],
+  ['addSheet', W, UNSAFE, []],
+  ['deleteSheet', D, SAFE, ['sheetId']],
+  ['autoFill', D, SAFE, [['range', 'sourceAndDestination']]],
+  ['cutPaste', D, UNSAFE, ['source', 'destination']],
+  ['copyPaste', D, SAFE, ['source', 'destination']],
+  ['mergeCells', D, SAFE, ['range', 'mergeType']],
+  ['unmergeCells', W, SAFE, ['range']],
+  ['updateBorders', W, SAFE, ['range']],
+  ['updateCells', D, SAFE, ['rows', 'fields', ['start', 'range']]],
+  ['addFilterView', W, UNSAFE, ['filter']],
+  ['appendCells', W, UNSAFE, ['sheetId', 'rows', 'fields']],
+  ['clearBasicFilter', W, SAFE, ['sheetId']],
+  ['deleteDimension', D, UNSAFE, ['range']],
+  ['deleteEmbeddedObject', D, SAFE, ['objectId']],
+  ['deleteFilterView', D, SAFE, ['filterId']],
+  ['duplicateFilterView', W, UNSAFE, ['filterId']],
+  ['duplicateSheet', W, UNSAFE, ['sourceSheetId']],
+  ['findReplace', D, UNSAFE, ['find', ['range', 'sheetId', 'allSheets']]],
+  ['insertDimension', W, UNSAFE, ['range']],
+  ['insertRange', W, UNSAFE, ['range', 'shiftDimension']],
+  ['moveDimension', W, UNSAFE, ['source', 'destinationIndex']],
+  ['updateEmbeddedObjectPosition', W, SAFE, ['objectId', 'newPosition', 'fields']],
+  ['pasteData', D, SAFE, ['coordinate', 'data']],
+  ['textToColumns', D, UNSAFE, ['source']],
+  ['updateFilterView', W, SAFE, ['filter', 'fields']],
+  ['deleteRange', D, UNSAFE, ['range', 'shiftDimension']],
+  ['appendDimension', W, UNSAFE, ['sheetId', 'dimension', 'length']],
+  ['addConditionalFormatRule', W, UNSAFE, ['rule', 'index']],
+  ['updateConditionalFormatRule', W, UNSAFE, ['index', 'sheetId', ['rule', 'newIndex']]],
+  ['deleteConditionalFormatRule', D, UNSAFE, ['index', 'sheetId']],
+  ['sortRange', D, SAFE, ['range', 'sortSpecs']],
+  ['setDataValidation', W, SAFE, ['range']],
+  // A basic filter's sortSpecs physically reorder the rows, like sortRange.
+  ['setBasicFilter', D, SAFE, ['filter']],
+  ['addProtectedRange', D, UNSAFE, ['protectedRange']],
+  ['updateProtectedRange', D, SAFE, ['protectedRange', 'fields']],
+  ['deleteProtectedRange', D, SAFE, ['protectedRangeId']],
+  ['autoResizeDimensions', W, SAFE, [['dimensions', 'dataSourceSheetDimensions']]],
+  ['addChart', W, UNSAFE, ['chart']],
+  ['updateChartSpec', W, SAFE, ['chartId', 'spec']],
+  ['updateBanding', W, SAFE, ['bandedRange', 'fields']],
+  ['addBanding', W, UNSAFE, ['bandedRange']],
+  ['deleteBanding', D, SAFE, ['bandedRangeId']],
+  ['createDeveloperMetadata', W, UNSAFE, ['developerMetadata']],
+  ['updateDeveloperMetadata', W, SAFE, ['dataFilters', 'developerMetadata', 'fields']],
+  ['deleteDeveloperMetadata', D, SAFE, ['dataFilter']],
+  ['randomizeRange', D, UNSAFE, ['range']],
+  ['addDimensionGroup', W, UNSAFE, ['range']],
+  ['deleteDimensionGroup', D, UNSAFE, ['range']],
+  ['updateDimensionGroup', W, SAFE, ['dimensionGroup', 'fields']],
+  ['trimWhitespace', D, SAFE, ['range']],
+  ['deleteDuplicates', D, SAFE, ['range']],
+  ['updateEmbeddedObjectBorder', W, SAFE, ['objectId', 'border', 'fields']],
+  ['addSlicer', W, UNSAFE, ['slicer']],
+  ['updateSlicerSpec', W, SAFE, ['slicerId', 'spec', 'fields']],
+  ['addTable', W, UNSAFE, ['table']],
+  ['updateTable', W, SAFE, ['table', 'fields']],
+  ['deleteTable', D, SAFE, ['tableId']],
+];
+
+/** kind → `{ effect, replay, requires }`, frozen. */
+export const REQUEST_KINDS = Object.freeze(Object.fromEntries(ROWS.map(([kind, effect, replay, requires]) => [kind, Object.freeze({ effect, replay, requires })])));
+
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const refuse = (code, detail) => new GoogleWorkspaceError({ code }, { detail });
+
+/** Whether one requirement (a field, or "one of" these fields) is present. @complexity O(1). */
+function satisfied(body, requirement) {
+  return [requirement].flat().some((field) => body[field] !== undefined && body[field] !== null);
+}
+
+/** What is wrong with a listed kind's body, or undefined. @complexity O(f). */
+function bodyProblem(entry, body) {
+  const missing = entry.requires.find((requirement) => !satisfied(body, requirement));
+  if (missing) return `needs ${[missing].flat().join(' or ')}`;
+  const explicitMask = typeof body.fields === 'string' && body.fields.trim() !== '' && !body.fields.includes('*');
+  return body.fields === undefined || explicitMask ? undefined : 'needs an explicit field mask, not *';
+}
+
+/**
+ * The listed kind of one request, or the refusal that stops the whole batch.
+ * @complexity O(f) fields of the kind's requirements.
+ */
+function checkOne(request, index) {
+  const keys = isPlainObject(request) ? Object.keys(request) : [];
+  if (keys.length !== 1) return { error: refuse('invalid-input', `request ${index + 1} must name exactly one request kind`) };
+  const kind = keys[0];
+  // Own-property lookup only, so `constructor` or `__proto__` can never pass as a kind.
+  const entry = Object.hasOwn(REQUEST_KINDS, kind) ? REQUEST_KINDS[kind] : undefined;
+  if (!entry) return { error: refuse('unsupported-request', `request ${index + 1}`) };
+  const body = request[kind];
+  if (!isPlainObject(body)) return { error: refuse('invalid-input', `request ${index + 1} (${kind}) must be an object`) };
+  const problem = bodyProblem(entry, body);
+  return problem ? { error: refuse('invalid-input', `request ${index + 1} (${kind}) ${problem}`) } : { kind, entry };
+}
+
+/** Refuses an empty, oversized or too varied batch. @complexity O(serialized size). */
+function checkBounds(requests) {
+  if (!Array.isArray(requests) || requests.length === 0) throw refuse('invalid-input', 'the batch has no requests');
+  if (requests.length > MAX_BATCH_REQUESTS) throw refuse('limit-exceeded', `at most ${MAX_BATCH_REQUESTS} requests per batch`);
+  if (Buffer.byteLength(JSON.stringify(requests)) > MAX_BATCH_BYTES) throw refuse('limit-exceeded', 'at most 1 MiB of requests per batch');
+}
+
+/**
+ * Checks a whole batch against the inventory. Nothing is sent unless every request passes.
+ * @param {{ requests: unknown }} required
+ * @returns {{ kind: 'write' | 'idempotent-write', kinds: Map<string, { effect: string, count: number }> }}
+ *   `kind` is what the HTTP client needs to know about replays; `kinds` is in first-seen order.
+ * @throws {GoogleWorkspaceError} `invalid-input`, `unsupported-request` or `limit-exceeded`.
+ * @complexity O(n) requests plus their serialized size.
+ */
+export function checkRequests(required, _optional = {}) {
+  checkBounds(required.requests);
+  const kinds = new Map();
+  let unsafe = false;
+  required.requests.forEach((request, index) => {
+    const checked = checkOne(request, index);
+    if (checked.error) throw checked.error;
+    unsafe ||= checked.entry.replay === UNSAFE;
+    kinds.set(checked.kind, { effect: checked.entry.effect, count: (kinds.get(checked.kind)?.count ?? 0) + 1 });
+  });
+  if (kinds.size > MAX_DISTINCT_KINDS) throw refuse('limit-exceeded', `at most ${MAX_DISTINCT_KINDS} different request kinds per batch`);
+  return { kind: unsafe || required.requests.length > 1 ? 'write' : 'idempotent-write', kinds };
+}
+
+/**
+ * One confirmation line per request kind in the batch: `deleteDimension x2 (destructive)`.
+ * @param {{ requests: unknown }} required
+ * @complexity O(n).
+ */
+export function describeRequests(required, _optional = {}) {
+  const { kinds } = checkRequests(required);
+  return [...kinds].map(([kind, { effect, count }]) => `${kind} x${count} (${effect})`);
+}

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

@@ -0,0 +1,286 @@
+/**
+ * @file The one Sheets client of the Google Workspace plugin: every Sheets tool (values, search,
+ * tabs, filters, formatting, batch updates, export) and the form destination build their endpoint,
+ * check and encode ids and ranges, apply the RAW input default and enforce the §D bounds here, then
+ * send through the one Google client (`http.mjs`), which owns tokens, retries and safe errors
+ * (quotas are the host's, charged on each token read). A1 helpers live in `sheets-a1.mjs`.
+ *
+ * Exists so the rules that keep a call inside what the person asked for live in one place:
+ * - a spreadsheet id must look like a Google file id ({@link assertSpreadsheetId}) and, like a
+ *   range, is ONE encoded path segment (`.`/`..` refused), so caller text can never change which
+ *   endpoint is called;
+ * - every batch, raw or built by a named tool, passes the reviewed request-kind inventory first
+ *   ({@link runBatchUpdate});
+ * - values are written `RAW` unless the caller explicitly asks for `USER_ENTERED`, so text a
+ *   visitor typed never becomes a formula;
+ * - reads return at most 500 rows, 5,000 cells and 64 KiB, with an explicit continuation range
+ *   instead of a silent partial; mutation payloads stay under 1 MiB;
+ * - every request a Sheets tool sends first checks that the Sheets product is on
+ *   ({@link sheetsClientFor}), so turning Sheets off blocks every Sheets tool at once.
+ */
+import { createGoogleClient, pathSegment } from './http.mjs';
+import { assertProductEnabled } from './product-state.mjs';
+import { GoogleWorkspaceError } from './request-policy.mjs';
+import { parseA1Range } from './sheets-a1.mjs';
+import { MAX_BATCH_BYTES, MAX_BATCH_REQUESTS, checkRequests } from './sheets-admin-request-kinds.mjs';
+
+export const SHEETS_API = 'https://sheets.googleapis.com/v4/spreadsheets';
+/** The `products.json` id every Sheets tool belongs to (its tools are named `sheets_*`). */
+export const SHEETS_PRODUCT_ID = 'sheets';
+export const DEFAULT_VALUE_INPUT_OPTION = 'RAW';
+
+/** §D starting bounds. Batch reads share ONE output budget across all their ranges. */
+export const SHEETS_LIMITS = Object.freeze({
+  maxRows: 500, maxCells: 5_000, maxOutputBytes: 64 * 1024, maxRanges: 20,
+  // One mutation bound for values writes and batch updates alike.
+  maxMutationEntries: MAX_BATCH_REQUESTS, maxPayloadBytes: MAX_BATCH_BYTES,
+  // find reads more than it returns: it scans up to this many cells and returns at most maxMatches.
+  maxScannedCells: 50_000, maxMatches: 100, maxExcerptChars: 120,
+});
+
+/** Default spreadsheet metadata mask: no grid data, only what chat needs to name tabs. */
+const SHEET_PROPERTIES = 'properties(sheetId,title,index,sheetType,gridProperties(rowCount,columnCount,frozenRowCount,frozenColumnCount))';
+const SPREADSHEET_PREFIX = 'spreadsheetId,spreadsheetUrl,properties(title,locale,timeZone)';
+export const SPREADSHEET_FIELDS = `${SPREADSHEET_PREFIX},sheets(${SHEET_PROPERTIES})`;
+const GRID_DATA_FIELDS = `${SPREADSHEET_PREFIX},sheets(${SHEET_PROPERTIES},data(startRow,startColumn,rowData(values(formattedValue))))`;
+
+const byteLength = (value) => Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+
+/** Google file ids are URL-safe base64 characters; the input schemas use the same pattern. */
+export const SPREADSHEET_ID_PATTERN = /^[A-Za-z0-9_-]{10,200}$/;
+
+/**
+ * The id, when it is a plausible Google file id; refused before it reaches any URL otherwise (the
+ * value is never echoed).
+ * @param {{ id: unknown }} required
+ * @param {{ code?: 'invalid-input' | 'invalid-selection' }} [optional] The Picker refuses with
+ *   `invalid-selection` (re-pick the file); tools with `invalid-input` (the default).
+ * @throws {GoogleWorkspaceError}
+ * @complexity O(n) characters.
+ */
+export function assertSpreadsheetId(required, optional = {}) {
+  if (typeof required.id === 'string' && SPREADSHEET_ID_PATTERN.test(required.id)) return required.id;
+  const code = optional.code ?? 'invalid-input';
+  throw new GoogleWorkspaceError({ code }, code === 'invalid-input' ? { detail: 'spreadsheetId' } : {});
+}
+
+/**
+ * `<SHEETS_API>/<spreadsheetId>[/<segment>…][<method>]`, the id checked first. `method`
+ * (`:append`, `:batchUpdate`, …) is always a constant from plugin code, never caller text.
+ * @param {{ spreadsheetId: string }} required
+ * @param {{ segments?: readonly string[], method?: string }} [optional]
+ * @throws {GoogleWorkspaceError} `invalid-input` for an id or segment that cannot be a path segment.
+ * @complexity O(n) characters.
+ */
+export function sheetsUrl(required, optional = {}) {
+  const segments = [assertSpreadsheetId({ id: required.spreadsheetId }), ...(optional.segments ?? [])].map((value) => pathSegment({ value }));
+  return `${SHEETS_API}/${segments.join('/')}${optional.method ?? ''}`;
+}
+
+/**
+ * Sends one Sheets request for a tool call through the shared Google client.
+ * @param {{ call: { input: { connectionRef: string }, capabilities: { http: object, connections: object, state?: object }, signal?: AbortSignal }, request: { url: string, method?: string, query?: object, body?: unknown, kind: 'read' | 'idempotent-write' | 'write' } }} required
+ *   `call` is the tool's `invoke` argument as received.
+ * @returns {Promise<any>} Google's parsed JSON body.
+ * @throws {GoogleWorkspaceError} Every failure, already mapped to a safe code.
+ * @complexity O(attempts) (see `createGoogleClient`).
+ */
+export function sendSheetsRequest(required, _optional = {}) {
+  const { input, capabilities, signal } = required.call;
+  return sheetsClientFor({ capabilities }).request({ connectionRef: input.connectionRef, ...required.request }, signal ? { signal } : {});
+}
+
+/** The shared Google client over one call's host capabilities. @complexity O(1). */
+export function googleClientFor(required, _optional = {}) {
+  const { capabilities } = required;
+  return createGoogleClient({ http: capabilities.http, connections: capabilities.connections });
+}
+
+/**
+ * The Google client a Sheets tool uses: each request first checks that the Sheets product is on in
+ * the plugin's settings (`capabilities.state`), then goes through the shared client. Checked per
+ * request, so turning Sheets off also stops a multi-request call (an export) part way, before the
+ * next request is sent.
+ * @param {{ capabilities: { http: object, connections: object, state?: { get(input: { key: string }): Promise<unknown> } } }} required
+ * @throws {GoogleWorkspaceError} `product-disabled` from `request` while Sheets is off.
+ * @complexity O(1) to build; each request adds one state read.
+ */
+export function sheetsClientFor(required, _optional = {}) {
+  const { capabilities } = required;
+  const client = googleClientFor({ capabilities });
+  return {
+    async request(request, options = {}) {
+      await assertProductEnabled({ state: capabilities.state, productId: SHEETS_PRODUCT_ID });
+      return client.request(request, options);
+    },
+  };
+}
+
+/** A mask that reaches cell data: `*`, or a `data` field (`sheets.data`, `sheets(data)`), not `dataSources`. */
+const GRID_DATA_MASK = /\*|\bdata\b/;
+
+/**
+ * The spreadsheet field mask: the caller's, else the default (plus cell values when grid data is
+ * asked for). Google ignores `includeGridData` once a mask is set, so a caller mask that reaches
+ * cell data counts as asking for grid data: it needs `includeGridData` (which `sheets_get` only
+ * allows with explicit ranges; `get_by_data_filter` always names its data filters).
+ * @throws {GoogleWorkspaceError} `invalid-input` for a grid-data mask without `includeGridData`.
+ * @complexity O(n) mask length.
+ */
+export function spreadsheetFields(required, _optional = {}) {
+  if (required.fields !== undefined && GRID_DATA_MASK.test(required.fields) && !required.includeGridData) {
+    throw new GoogleWorkspaceError({ code: 'invalid-input' }, { detail: 'a fields mask with * or data needs includeGridData and ranges' });
+  }
+  if (required.fields !== undefined) return required.fields;
+  return required.includeGridData ? GRID_DATA_FIELDS : SPREADSHEET_FIELDS;
+}
+
+const MAX_RESOURCE_LINES = 50;
+const MAX_RESOURCE_CHARS = 300;
+
+/**
+ * Lines for the confirmation card, inside the projection's bounds (50 lines of 300 characters):
+ * a long line is shortened and extra lines are summarized as a count, so nothing is hidden silently.
+ * @complexity O(lines).
+ */
+export function resourceLines(required, _optional = {}) {
+  const fit = (line) => (line.length > MAX_RESOURCE_CHARS ? `${line.slice(0, MAX_RESOURCE_CHARS - 1)}…` : line);
+  const { lines } = required;
+  if (lines.length <= MAX_RESOURCE_LINES) return lines.map(fit);
+  return [...lines.slice(0, MAX_RESOURCE_LINES - 1).map(fit), `… and ${lines.length - MAX_RESOURCE_LINES + 1} more`];
+}
+
+/** The value input option to send: `RAW` unless the caller explicitly chose `USER_ENTERED`. @complexity O(1). */
+export function valueInputOption(required, _optional = {}) {
+  return required.option === 'USER_ENTERED' ? 'USER_ENTERED' : DEFAULT_VALUE_INPUT_OPTION;
+}
+
+/** Read options every values read sends: rows-major, plus the caller's render choices. @complexity O(1). */
+export function readOptions(required, _optional = {}) {
+  const { valueRenderOption, dateTimeRenderOption } = required.input;
+  return { majorDimension: 'ROWS', ...(valueRenderOption ? { valueRenderOption } : {}), ...(dateTimeRenderOption ? { dateTimeRenderOption } : {}) };
+}
+
+/** Total cells in rows of values. @complexity O(rows). */
+export function cellCount(required, _optional = {}) {
+  return required.values.reduce((total, row) => total + row.length, 0);
+}
+
+/**
+ * Refuses a mutation whose serialized body exceeds the payload bound, before anything is sent.
+ * @throws {GoogleWorkspaceError} `limit-exceeded`.
+ * @complexity O(n) serialized size.
+ */
+export function assertPayloadWithin(required, _optional = {}) {
+  if (byteLength(required.value) > SHEETS_LIMITS.maxPayloadBytes) throw new GoogleWorkspaceError({ code: 'limit-exceeded' });
+  return required.value;
+}
+
+/**
+ * Whether a result fits the tool-output bound, less `headroomBytes` (room a caller keeps for the
+ * rest of its answer).
+ * @complexity O(n) serialized size.
+ */
+export function outputFits(required, optional = {}) {
+  return byteLength(required.value) <= SHEETS_LIMITS.maxOutputBytes - (optional.headroomBytes ?? 0);
+}
+
+/**
+ * Returns a result only when it fits the tool-output bound; a larger result is an error, never a
+ * silently cut one (used where no range continuation exists: metadata, data-filter and admin reads).
+ * @throws {GoogleWorkspaceError} `limit-exceeded`.
+ * @complexity O(n) serialized size.
+ */
+export function assertOutputWithin(required, _optional = {}) {
+  if (!outputFits(required)) throw new GoogleWorkspaceError({ code: 'limit-exceeded' }, { detail: 'answer over 64 KiB; narrow it to one tab or fewer items' });
+  return required.value;
+}
+
+const signalOption = (signal) => (signal ? { signal } : {});
+
+/**
+ * `spreadsheets.get` with a field mask (grid data is never requested).
+ * @param {{ client: object, connectionRef: string, spreadsheetId: string, fields: string }} required
+ * @param {{ signal?: AbortSignal }} [optional]
+ * @complexity O(1) requests.
+ */
+export function getSpreadsheet(required, optional = {}) {
+  return required.client.request({
+    connectionRef: required.connectionRef, url: sheetsUrl({ spreadsheetId: required.spreadsheetId }), kind: 'read', query: { fields: required.fields },
+  }, signalOption(optional.signal));
+}
+
+/**
+ * `spreadsheets.batchUpdate` after the inventory check; a batch holding any non-replayable kind is a
+ * `write`, so an unknown outcome is reported as uncertain and never replayed.
+ * @param {{ client: object, connectionRef: string, spreadsheetId: string, requests: readonly object[] }} required
+ * @param {{ signal?: AbortSignal }} [optional]
+ * @returns {Promise<{ replies: unknown[] }>}
+ * @complexity O(n) requests to check, one HTTP request.
+ */
+export async function runBatchUpdate(required, optional = {}) {
+  const { kind } = checkRequests({ requests: required.requests });
+  const body = await required.client.request({
+    connectionRef: required.connectionRef, url: sheetsUrl({ spreadsheetId: required.spreadsheetId }, { method: ':batchUpdate' }),
+    method: 'POST', kind, body: { requests: required.requests },
+  }, signalOption(optional.signal));
+  return { replies: Array.isArray(body?.replies) ? body.replies : [] };
+}
+
+/** The first line of every admin tool's disclosure. @complexity O(1). */
+export function spreadsheetLine(required, _optional = {}) {
+  return `spreadsheet ${assertSpreadsheetId({ id: required.spreadsheetId })}`;
+}
+
+/**
+ * The tabs of a `sheets(properties(...),<part>)` answer, optionally only one tab.
+ * @complexity O(t) tabs.
+ */
+export function tabsOf(required, _optional = {}) {
+  const sheets = Array.isArray(required.body?.sheets) ? required.body.sheets : [];
+  return required.sheetId === undefined ? sheets : sheets.filter((sheet) => sheet?.properties?.sheetId === required.sheetId);
+}
+
+/**
+ * The range that continues `range` after its first `rows` rows, same columns.
+ * @throws {GoogleWorkspaceError} `limit-exceeded` when Google's range cannot be continued, so the
+ *   caller errors instead of returning an undisclosed partial read.
+ * @complexity O(n) characters.
+ */
+export function continuationRange(required, _optional = {}) {
+  const parts = parseA1Range({ range: required.range });
+  if (!parts) throw new GoogleWorkspaceError({ code: 'limit-exceeded' });
+  const start = `${parts.sheet}!${parts.startColumn}${parts.startRow + required.rows}`;
+  return parts.endRow === undefined ? start : `${start}:${parts.endColumn}${parts.endRow}`;
+}
+
+/** Whether one more row fits the shared output budget. @complexity O(1). */
+function rowFits(totals, row, rowBytes) {
+  return totals.rows < SHEETS_LIMITS.maxRows && totals.cells + row.length <= SHEETS_LIMITS.maxCells && totals.bytes + rowBytes <= SHEETS_LIMITS.maxOutputBytes;
+}
+
+/**
+ * Cuts value ranges to ONE shared output budget (rows, cells, bytes) in order. A cut range gets
+ * `continuation`: the exact range to read next.
+ * @param {{ valueRanges: readonly { range: string, values?: unknown[][] }[] }} required
+ * @returns {{ range: string, values: unknown[][], continuation?: string }[]}
+ * @throws {GoogleWorkspaceError} `limit-exceeded` when not even the first row fits (no progress possible).
+ * @complexity O(cells).
+ */
+export function boundValueRanges(required, _optional = {}) {
+  const totals = { rows: 0, cells: 0, bytes: 0 };
+  const bounded = required.valueRanges.map((valueRange) => {
+    const values = valueRange.values ?? [];
+    let kept = 0;
+    for (const row of values) {
+      const rowBytes = byteLength(row);
+      if (!rowFits(totals, row, rowBytes)) break;
+      Object.assign(totals, { rows: totals.rows + 1, cells: totals.cells + row.length, bytes: totals.bytes + rowBytes });
+      kept += 1;
+    }
+    if (kept === values.length) return { range: valueRange.range, values };
+    return { range: valueRange.range, values: values.slice(0, kept), continuation: continuationRange({ range: valueRange.range, rows: kept }) };
+  });
+  if (totals.rows === 0 && bounded.some((entry) => entry.continuation)) throw new GoogleWorkspaceError({ code: 'limit-exceeded' });
+  return bounded;
+}

package/google-workspace/lib/surface-actions.mjs

@@ -0,0 +1,107 @@
+/**
+ * @file Server-side pieces every Google Workspace admin-surface handler shares: the plugin's one
+ * connection id, a Google client over the surface capability port, the "is Sheets usable right now"
+ * check, and the translation of plugin and host refusals into surface-safe failures.
+ *
+ * Exists because the three panels (connection, Picker, form destination) run in the host's
+ * admin-surface handler seam, whose port differs from the tool port in one way that matters here:
+ * connections are named by the surface's declared connection id, not by a connection ref. Keeping
+ * that adaptation and the failure mapping in one place means every panel sends the same safe codes
+ * and fixed messages (never Google's text, a token, or a file's contents) to the frame.
+ */
+import { readAccount } from './drive-files.mjs';
+import { isProductEnabled } from './product-state.mjs';
+import { GoogleWorkspaceError } from './request-policy.mjs';
+import { SHEETS_PRODUCT_ID, sheetsClientFor } from './sheets-client.mjs';
+
+/** The plugin's one sign-in: `tovu-connections.json`'s id, declared by every surface that uses it. */
+export const CONNECTION_ID = 'account';
+
+const FAILURE_CODE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Panel-only refusals (nothing was sent to Google), with the fixed sentence the frame shows. */
+const SURFACE_FAILURES = Object.freeze({
+  'picker-expired': 'The file picker session ended. Close this panel, open it again, and choose the spreadsheet again.',
+  'invalid-destination': 'The form name or tab is not valid. Use the form\'s short name (letters, digits, - or _) and choose a tab from the list.',
+  'tab-not-found': 'That tab is not in the spreadsheet any more. Reload the tabs and choose one again.',
+  'confirm-external-rows': 'Confirm that removing this destination later leaves the rows already written in the spreadsheet, then save again.',
+  'too-many-destinations': 'This plugin keeps at most 50 form destinations. Remove one you no longer use, then save again.',
+});
+
+/**
+ * A surface-safe failure for a panel-only refusal.
+ * @param {{ fail: (input: { code: string, message: string }) => Error, code: keyof typeof SURFACE_FAILURES }} required
+ * @returns {Error}
+ * @complexity O(1).
+ */
+export function surfaceRefusal(required, _optional = {}) {
+  return required.fail({ code: required.code, message: SURFACE_FAILURES[required.code] });
+}
+
+/**
+ * The plugin's one Sheets client (product gate on every request) over the surface port: the client
+ * asks for a `connectionRef`, and inside a surface handler that reference is the declared connection
+ * id, which the host resolves for this plugin and workspace only.
+ * @param {{ capabilities: { http: object, state: object, connections: { getAccessToken(input: { connectionId: string }): Promise<string> } } }} required
+ * @returns {{ request(input: object, options?: object): Promise<unknown> }}
+ * @complexity O(1).
+ */
+export function surfaceSheetsClient(required, _optional = {}) {
+  const { http, state, connections } = required.capabilities;
+  return sheetsClientFor({
+    capabilities: { http, state, connections: { getAccessToken: ({ connectionRef }) => connections.getAccessToken({ connectionId: connectionRef }) } },
+  });
+}
+
+/** The signed-in Google account (`{ accountId, displayName }`), read through the surface client. @complexity O(1): one request. */
+export function surfaceAccount(required, _optional = {}) {
+  return readAccount({ client: surfaceSheetsClient(required), connectionRef: CONNECTION_ID });
+}
+
+/** Status → why Sheets cannot be used yet, as a safe code. @complexity O(s) granted scope sets. */
+function connectionRefusal(status) {
+  if (status.status === 'reconnect-required') return 'reconnect-required';
+  if (status.status !== 'connected') return 'not-connected';
+  return status.grantedScopeSetIds.includes(SHEETS_PRODUCT_ID) ? null : 'missing-permission';
+}
+
+/**
+ * Why the Picker (or anything else Sheets-backed on a panel) cannot run now, or null: the
+ * connection must be connected with the Sheets permission granted, and Sheets must be turned on.
+ * @param {{ capabilities: { connections: { status(input: { connectionId: string }): Promise<{ status: string, grantedScopeSetIds: readonly string[] }> }, state: { get(input: { key: string }): Promise<unknown> } } }} required
+ * @returns {Promise<'not-connected' | 'reconnect-required' | 'missing-permission' | 'product-disabled' | null>}
+ * @complexity O(1): one status read and one state read.
+ */
+export async function sheetsUnavailableReason(required, _optional = {}) {
+  const { connections, state } = required.capabilities;
+  const refusal = connectionRefusal(await connections.status({ connectionId: CONNECTION_ID }));
+  if (refusal !== null) return refusal;
+  return (await isProductEnabled({ state, productId: SHEETS_PRODUCT_ID })) ? null : 'product-disabled';
+}
+
+/**
+ * Turns a refusal into what the frame may see: a plugin `GoogleWorkspaceError` keeps its code, fixed
+ * message and retryable flag; a host refusal with a plain lowercase code keeps its code and message
+ * (host messages are written for people and never carry secrets); anything else is rethrown so the
+ * host's dispatcher answers with its generic failure and logs the cause.
+ * @complexity O(1).
+ */
+function surfaceFailure(error, fail) {
+  if (error instanceof GoogleWorkspaceError) return fail({ code: error.code, message: error.message }, { retryable: error.retryable });
+  const hostRefusal = typeof error?.code === 'string' && FAILURE_CODE.test(error.code) && typeof error.message === 'string';
+  return hostRefusal ? fail({ code: error.code, message: error.message }, { retryable: error.retryable === true }) : error;
+}
+
+/**
+ * Runs one handler body with {@link surfaceFailure} applied to whatever it throws.
+ * @param {{ fail: Function, run: () => Promise<unknown> }} required `fail` is the handler call's own.
+ * @returns {Promise<unknown>} The body's result.
+ * @complexity O(1) plus the body.
+ */
+export async function withSurfaceFailures(required, _optional = {}) {
+  try {
+    return await required.run();
+  } catch (error) {
+    throw surfaceFailure(error, required.fail);
+  }
+}