@jini-ai/agent-plugins 0.6.17 → 0.6.19

package/google-workspace/tools/sheets/copy.mjs

@@ -0,0 +1,23 @@
+/**
+ * @file Tool `sheets_copy` (`p_google_workspace__sheets_copy`): a whole-spreadsheet copy through
+ * Drive `files.copy` (the shared Drive helper), optionally into a folder the connection can open.
+ *
+ * A copy is not idempotent: a lost answer is `uncertain-outcome` and is never replayed.
+ */
+import { copyFile } from '../../lib/drive-files.mjs';
+import { sheetsClientFor, resourceLines } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, title: string, parentFolderId?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke({ input, capabilities, signal }) {
+    const copied = await copyFile(
+      { client: sheetsClientFor({ capabilities }), connectionRef: input.connectionRef, fileId: input.spreadsheetId, name: input.title },
+      { ...(input.parentFolderId ? { parentId: input.parentFolderId } : {}), ...(signal ? { signal } : {}) },
+    );
+    return { spreadsheetId: copied.fileId, title: copied.name, url: copied.url };
+  },
+  describeAffectedResources({ input }) {
+    const where = input.parentFolderId ? ` in folder ${input.parentFolderId}` : '';
+    return resourceLines({ lines: [`New spreadsheet "${input.title}" copied from spreadsheet ${input.spreadsheetId}${where}`] });
+  },
+};

package/google-workspace/tools/sheets/create.mjs

@@ -0,0 +1,35 @@
+/**
+ * @file Tool `sheets_create` (`p_google_workspace__sheets_create`): a new spreadsheet, optionally
+ * with named tabs. Under `drive.file`, a file the site creates is one the site may open from then on.
+ *
+ * A create is not idempotent: if Google's answer is lost the outcome is `unknown`
+ * (`uncertain-outcome`) and the call is never replayed, so a lost answer cannot make two files.
+ */
+import { resourceLines, SHEETS_API, sendSheetsRequest } from '../../lib/sheets-client.mjs';
+
+const CREATE_FIELDS = 'spreadsheetId,spreadsheetUrl,properties(title),sheets(properties(sheetId,title,index))';
+
+/** The new file's properties: the title plus the locale and time zone only when given. @complexity O(1). */
+function propertiesOf(input) {
+  return { title: input.title, ...(input.locale ? { locale: input.locale } : {}), ...(input.timeZone ? { timeZone: input.timeZone } : {}) };
+}
+
+/** What chat needs from Google's answer: ids, URL and tabs. @complexity O(tabs). */
+function created(body) {
+  return { spreadsheetId: body?.spreadsheetId, url: body?.spreadsheetUrl, title: body?.properties?.title, tabs: (body?.sheets ?? []).map((sheet) => sheet.properties) };
+}
+
+export default {
+  /** @param {{ input: { connectionRef: string, title: string, tabs?: string[], locale?: string, timeZone?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'write', method: 'POST', url: SHEETS_API, query: { fields: CREATE_FIELDS },
+      body: { properties: propertiesOf(input), ...(input.tabs ? { sheets: input.tabs.map((title) => ({ properties: { title } })) } : {}) },
+    } });
+    return created(body);
+  },
+  describeAffectedResources({ input }) {
+    return resourceLines({ lines: [`New spreadsheet "${input.title}" in the connected Google Drive`] });
+  },
+};

package/google-workspace/tools/sheets/find-replace.mjs

@@ -0,0 +1,38 @@
+/**
+ * @file Tool `sheets_find_replace` (`p_google_workspace__sheets_find_replace`): replaces every match
+ * of a text on one tab or on every tab (`batchUpdate` with one `findReplace` request). Destructive:
+ * matched cells are overwritten and the site cannot undo it.
+ *
+ * Not idempotent (replacing `a` with `aa` twice differs), so a lost answer is `uncertain-outcome` and
+ * is never replayed.
+ */
+import { resourceLines, sendSheetsRequest, sheetsUrl } from '../../lib/sheets-client.mjs';
+
+/** The request's scope: the named tab, else every tab (the schema requires exactly one). @complexity O(1). */
+const scopeOf = (input) => (input.sheetId === undefined ? { allSheets: true } : { sheetId: input.sheetId });
+const MATCH_OPTIONS = ['matchCase', 'matchEntireCell', 'searchByRegex', 'includeFormulas'];
+const COUNTS = ['occurrencesChanged', 'valuesChanged', 'formulasChanged', 'rowsChanged', 'sheetsChanged'];
+
+/** The one `findReplace` request; every match option is sent explicitly (absent = false). @complexity O(1). */
+function findReplaceRequest(input) {
+  const options = Object.fromEntries(MATCH_OPTIONS.map((name) => [name, input[name] === true]));
+  return { find: input.find, replacement: input.replacement, ...options, ...scopeOf(input) };
+}
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, find: string, replacement: string, sheetId?: number, allSheets?: true, matchCase?: boolean, matchEntireCell?: boolean, searchByRegex?: boolean, includeFormulas?: boolean }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'write', method: 'POST', url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { method: ':batchUpdate' }),
+      body: { requests: [{ findReplace: findReplaceRequest(input) }], includeSpreadsheetInResponse: false },
+    } });
+    // Google omits a zero count from the reply.
+    const reply = body?.replies?.[0]?.findReplace ?? {};
+    return Object.fromEntries(COUNTS.map((name) => [name, reply[name] ?? 0]));
+  },
+  describeAffectedResources({ input }) {
+    const where = input.sheetId === undefined ? 'every tab' : `tab ${input.sheetId}`;
+    return resourceLines({ lines: [`Replace every match of "${input.find}" with "${input.replacement}" on ${where} of spreadsheet ${input.spreadsheetId} (matched cells are overwritten)`] });
+  },
+};

package/google-workspace/tools/sheets/find.mjs

@@ -0,0 +1,52 @@
+/**
+ * @file Tool `sheets_find` (`p_google_workspace__sheets_find`): finds cells whose text contains (or
+ * equals) a search text in up to 20 explicit ranges, returning cell references and short excerpts.
+ *
+ * The Sheets API has no read-only search, so this reads the ranges (`values.batchGet`) and matches
+ * plain text locally (no regular expressions, so no pathological patterns). It scans at most 50,000
+ * cells (more is an error, never a silent partial scan) and returns at most 100 matches with
+ * `truncated` set when there were more.
+ */
+import { GoogleWorkspaceError } from '../../lib/request-policy.mjs';
+import { columnIndex, columnName, parseA1Range } from '../../lib/sheets-a1.mjs';
+import { cellCount, readOptions, sendSheetsRequest, sheetsUrl, SHEETS_LIMITS } from '../../lib/sheets-client.mjs';
+
+/** The matcher for the caller's options. @complexity O(1) to build; O(text) per cell. */
+function matcherFor(input) {
+  const fold = (text) => (input.matchCase ? text : text.toLowerCase());
+  const needle = fold(input.text);
+  return input.matchEntireCell ? (cell) => fold(cell) === needle : (cell) => fold(cell).includes(needle);
+}
+
+/**
+ * Matching cells of one value range, appended to `found` until it holds one more than the cap (so
+ * the caller knows whether there were more).
+ * @complexity O(cells).
+ */
+function collectMatches(valueRange, matches, found) {
+  const start = parseA1Range({ range: valueRange.range });
+  if (!start) throw new GoogleWorkspaceError({ code: 'unexpected-response' });
+  const firstColumn = columnIndex({ column: start.startColumn });
+  (valueRange.values ?? []).forEach((row, rowOffset) => row.forEach((value, columnOffset) => {
+    if (found.length > SHEETS_LIMITS.maxMatches || !matches(String(value))) return;
+    found.push({ cell: `${start.sheet}!${columnName({ index: firstColumn + columnOffset })}${start.startRow + rowOffset}`, excerpt: String(value).slice(0, SHEETS_LIMITS.maxExcerptChars) });
+  }));
+}
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, ranges: string[], text: string, matchCase?: boolean, matchEntireCell?: boolean, valueRenderOption?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'read', url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values'], method: ':batchGet' }),
+      query: { ranges: input.ranges, ...readOptions({ input }) },
+    } });
+    const valueRanges = body?.valueRanges ?? [];
+    const scannedCells = valueRanges.reduce((total, valueRange) => total + cellCount({ values: valueRange.values ?? [] }), 0);
+    if (scannedCells > SHEETS_LIMITS.maxScannedCells) throw new GoogleWorkspaceError({ code: 'limit-exceeded' });
+    const matches = matcherFor(input);
+    const found = [];
+    for (const valueRange of valueRanges) collectMatches(valueRange, matches, found);
+    return { matches: found.slice(0, SHEETS_LIMITS.maxMatches), truncated: found.length > SHEETS_LIMITS.maxMatches, scannedCells };
+  },
+};

package/google-workspace/tools/sheets/get-by-data-filter.mjs

@@ -0,0 +1,23 @@
+/**
+ * @file Tool `sheets_get_by_data_filter` (`p_google_workspace__sheets_get_by_data_filter`): the
+ * spreadsheet data matching data filters (A1 ranges, grid ranges or developer-metadata lookups),
+ * via `spreadsheets.getByDataFilter`.
+ *
+ * Exists for reads addressed by metadata rather than by position. The result has no range
+ * continuation, so a result over the 64 KiB tool-output bound is an error, never a cut result.
+ */
+import { assertOutputWithin, sendSheetsRequest, sheetsUrl, spreadsheetFields } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, dataFilters: object[], includeGridData?: boolean, fields?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const includeGridData = input.includeGridData === true;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'read', method: 'POST', url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { method: ':getByDataFilter' }),
+      query: { fields: spreadsheetFields({ fields: input.fields, includeGridData }) },
+      body: { dataFilters: input.dataFilters, includeGridData },
+    } });
+    return assertOutputWithin({ value: body });
+  },
+};

package/google-workspace/tools/sheets/get.mjs

@@ -0,0 +1,22 @@
+/**
+ * @file Tool `sheets_get` (`p_google_workspace__sheets_get`): a spreadsheet's title, URL and tabs,
+ * with cell data only when asked for and only for the ranges named.
+ *
+ * Exists so chat can learn tab names and ids before it reads or writes. Grid data is opt-in and
+ * needs explicit ranges, and the result must fit the 64 KiB tool-output bound or the call errors.
+ */
+import { GoogleWorkspaceError } from '../../lib/request-policy.mjs';
+import { assertOutputWithin, sendSheetsRequest, sheetsUrl, spreadsheetFields } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, ranges?: string[], includeGridData?: boolean, fields?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const includeGridData = input.includeGridData === true;
+    // Grid data for a whole spreadsheet is unbounded; it is only read for the ranges the caller names.
+    if (includeGridData && !input.ranges?.length) throw new GoogleWorkspaceError({ code: 'invalid-input' });
+    const query = { fields: spreadsheetFields({ fields: input.fields, includeGridData }), includeGridData, ...(input.ranges ? { ranges: input.ranges } : {}) };
+    const body = await sendSheetsRequest({ call, request: { kind: 'read', url: sheetsUrl({ spreadsheetId: input.spreadsheetId }), query } });
+    return assertOutputWithin({ value: body });
+  },
+};

package/google-workspace/tools/sheets/values-append.mjs

@@ -0,0 +1,27 @@
+/**
+ * @file Tool `sheets_values_append` (`p_google_workspace__sheets_values_append`): appends rows after
+ * the table found in a tab or range (`values.append`), inserting new rows by default so nothing
+ * below the table is written over.
+ *
+ * Values go in `RAW` unless the caller explicitly asks for `USER_ENTERED`. An append is not
+ * idempotent: a lost answer is `uncertain-outcome` and is never replayed (it could add the rows twice).
+ */
+import { assertPayloadWithin, cellCount, resourceLines, sendSheetsRequest, sheetsUrl, valueInputOption } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, range: string, values: unknown[][], valueInputOption?: string, insertDataOption?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'write', method: 'POST',
+      url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values', input.range], method: ':append' }),
+      query: { valueInputOption: valueInputOption({ option: input.valueInputOption }), insertDataOption: input.insertDataOption ?? 'INSERT_ROWS' },
+      body: assertPayloadWithin({ value: { range: input.range, majorDimension: 'ROWS', values: input.values } }),
+    } });
+    const updates = body?.updates ?? {};
+    return { tableRange: body?.tableRange, updatedRange: updates.updatedRange, updatedRows: updates.updatedRows, updatedCells: updates.updatedCells };
+  },
+  describeAffectedResources({ input }) {
+    return resourceLines({ lines: [`Append ${input.values.length} row(s), ${cellCount({ values: input.values })} cell(s), after the table in ${input.range} of spreadsheet ${input.spreadsheetId}`] });
+  },
+};

package/google-workspace/tools/sheets/values-batch-clear.mjs

@@ -0,0 +1,20 @@
+/**
+ * @file Tool `sheets_values_batch_clear` (`p_google_workspace__sheets_values_batch_clear`): clears
+ * the values of up to 100 explicit ranges in one request (`values.batchClear`). Destructive.
+ */
+import { resourceLines, sendSheetsRequest, sheetsUrl } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, ranges: string[] }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'idempotent-write', method: 'POST', body: { ranges: input.ranges },
+      url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values'], method: ':batchClear' }),
+    } });
+    return { clearedRanges: body?.clearedRanges ?? [] };
+  },
+  describeAffectedResources({ input }) {
+    return resourceLines({ lines: input.ranges.map((range) => `Clear every value in ${range} of spreadsheet ${input.spreadsheetId}`) });
+  },
+};

package/google-workspace/tools/sheets/values-batch-get.mjs

@@ -0,0 +1,20 @@
+/**
+ * @file Tool `sheets_values_batch_get` (`p_google_workspace__sheets_values_batch_get`): the values
+ * of up to 20 explicit ranges in one request (`values.batchGet`).
+ *
+ * All ranges share ONE output budget (500 rows, 5,000 cells, 64 KiB); every range that was cut
+ * carries its own `continuation` range.
+ */
+import { boundValueRanges, readOptions, sendSheetsRequest, sheetsUrl } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, ranges: string[], valueRenderOption?: string, dateTimeRenderOption?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'read', url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values'], method: ':batchGet' }),
+      query: { ranges: input.ranges, ...readOptions({ input }) },
+    } });
+    return { valueRanges: boundValueRanges({ valueRanges: body?.valueRanges ?? [] }) };
+  },
+};

package/google-workspace/tools/sheets/values-batch-update.mjs

@@ -0,0 +1,29 @@
+/**
+ * @file Tool `sheets_values_batch_update` (`p_google_workspace__sheets_values_batch_update`): writes
+ * values over up to 100 explicit ranges in one request (`values.batchUpdate`). Destructive: the
+ * current values of every listed range are replaced.
+ *
+ * Values go in `RAW` unless the caller explicitly asks for `USER_ENTERED`; the whole body stays under
+ * 1 MiB. Repeating the same batch gives the same cells, so a transient failure may be retried.
+ */
+import { assertPayloadWithin, cellCount, resourceLines, sendSheetsRequest, sheetsUrl, valueInputOption } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, data: { range: string, values: unknown[][] }[], valueInputOption?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const data = input.data.map(({ range, values }) => ({ range, majorDimension: 'ROWS', values }));
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'idempotent-write', method: 'POST',
+      url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values'], method: ':batchUpdate' }),
+      body: assertPayloadWithin({ value: { valueInputOption: valueInputOption({ option: input.valueInputOption }), data, includeValuesInResponse: false } }),
+    } });
+    return {
+      totalUpdatedRows: body?.totalUpdatedRows, totalUpdatedCells: body?.totalUpdatedCells, totalUpdatedSheets: body?.totalUpdatedSheets,
+      responses: (body?.responses ?? []).map(({ updatedRange, updatedCells }) => ({ updatedRange, updatedCells })),
+    };
+  },
+  describeAffectedResources({ input }) {
+    return resourceLines({ lines: input.data.map(({ range, values }) => `Overwrite ${range} of spreadsheet ${input.spreadsheetId} (${cellCount({ values })} cell(s); current values are replaced)`) });
+  },
+};

package/google-workspace/tools/sheets/values-by-data-filter.mjs

@@ -0,0 +1,62 @@
+/**
+ * @file Tool `sheets_values_by_data_filter` (`p_google_workspace__sheets_values_by_data_filter`):
+ * reads, overwrites or clears the values matching data filters (`values.batchGetByDataFilter`,
+ * `batchUpdateByDataFilter`, `batchClearByDataFilter`), chosen by `action`.
+ *
+ * One tool covers three actions, so it is declared destructive (the strictest of them): even a `get`
+ * shows the confirmation card. Reads share the values-read output budget and carry `continuation`;
+ * writes go in `RAW` unless `USER_ENTERED` is asked for and stay under 1 MiB.
+ */
+import {
+  assertPayloadWithin, boundValueRanges, cellCount, readOptions, resourceLines, sendSheetsRequest, sheetsUrl, valueInputOption,
+} from '../../lib/sheets-client.mjs';
+
+/** Per action: endpoint, request kind, body and result. Inputs already passed the action's schema branch. */
+const ACTIONS = {
+  get: {
+    method: ':batchGetByDataFilter', kind: 'read',
+    body: (input) => ({ dataFilters: input.dataFilters, ...readOptions({ input }) }),
+    result: (body) => ({ valueRanges: boundValueRanges({ valueRanges: (body?.valueRanges ?? []).map((matched) => matched.valueRange ?? { range: '', values: [] }) }) }),
+  },
+  update: {
+    method: ':batchUpdateByDataFilter', kind: 'idempotent-write',
+    body: (input) => assertPayloadWithin({ value: {
+      valueInputOption: valueInputOption({ option: input.valueInputOption }), includeValuesInResponse: false,
+      data: input.data.map(({ dataFilter, values }) => ({ dataFilter, majorDimension: 'ROWS', values })),
+    } }),
+    result: (body) => ({ totalUpdatedRows: body?.totalUpdatedRows, totalUpdatedCells: body?.totalUpdatedCells, totalUpdatedSheets: body?.totalUpdatedSheets }),
+  },
+  clear: {
+    method: ':batchClearByDataFilter', kind: 'idempotent-write',
+    body: (input) => ({ dataFilters: input.dataFilters }),
+    result: (body) => ({ clearedRanges: body?.clearedRanges ?? [] }),
+  },
+};
+
+/** A data filter as a card phrase; never cell values. @complexity O(1). */
+function describeFilter(filter) {
+  if (filter.a1Range) return `range ${filter.a1Range}`;
+  // No fallback tab id: the input schema requires gridRange.sheetId, and the projection only hands
+  // schema-checked input to describeAffectedResources (pinned in sheets.contract.test.mjs).
+  if (filter.gridRange) return `grid range on tab ${filter.gridRange.sheetId}`;
+  return 'cells found by developer metadata';
+}
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, action: 'get' | 'update' | 'clear', dataFilters?: object[], data?: { dataFilter: object, values: unknown[][] }[], valueInputOption?: string, valueRenderOption?: string, dateTimeRenderOption?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const action = ACTIONS[input.action];
+    const body = await sendSheetsRequest({ call, request: {
+      kind: action.kind, method: 'POST', body: action.body(input),
+      url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values'], method: action.method }),
+    } });
+    return action.result(body);
+  },
+  describeAffectedResources({ input }) {
+    const where = `of spreadsheet ${input.spreadsheetId}`;
+    if (input.action === 'update') return resourceLines({ lines: input.data.map(({ dataFilter, values }) => `Overwrite ${describeFilter(dataFilter)} ${where} (${cellCount({ values })} cell(s); current values are replaced)`) });
+    const verb = input.action === 'clear' ? 'Clear every value in' : 'Read values in';
+    return resourceLines({ lines: input.dataFilters.map((filter) => `${verb} ${describeFilter(filter)} ${where}`) });
+  },
+};

package/google-workspace/tools/sheets/values-clear.mjs

@@ -0,0 +1,20 @@
+/**
+ * @file Tool `sheets_values_clear` (`p_google_workspace__sheets_values_clear`): clears the values of
+ * one explicit range (`values.clear`; formatting stays). Destructive and not undoable from the site.
+ */
+import { resourceLines, sendSheetsRequest, sheetsUrl } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, range: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'idempotent-write', method: 'POST', body: {},
+      url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values', input.range], method: ':clear' }),
+    } });
+    return { clearedRange: body?.clearedRange };
+  },
+  describeAffectedResources({ input }) {
+    return resourceLines({ lines: [`Clear every value in ${input.range} of spreadsheet ${input.spreadsheetId}`] });
+  },
+};

package/google-workspace/tools/sheets/values-get.mjs

@@ -0,0 +1,21 @@
+/**
+ * @file Tool `sheets_values_get` (`p_google_workspace__sheets_values_get`): the values of one
+ * explicit A1 range (`values.get`), rows-major.
+ *
+ * Exists for bounded reads: at most 500 rows, 5,000 cells and 64 KiB come back; when the range holds
+ * more, the result carries `continuation`, the exact range to read next (Sheets values reads have no
+ * page tokens).
+ */
+import { boundValueRanges, readOptions, sendSheetsRequest, sheetsUrl } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, range: string, valueRenderOption?: string, dateTimeRenderOption?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'read', url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values', input.range] }), query: readOptions({ input }),
+    } });
+    const [bounded] = boundValueRanges({ valueRanges: [{ range: body?.range ?? input.range, values: body?.values }] });
+    return bounded;
+  },
+};

package/google-workspace/tools/sheets/values-update.mjs

@@ -0,0 +1,26 @@
+/**
+ * @file Tool `sheets_values_update` (`p_google_workspace__sheets_values_update`): writes values over
+ * one explicit range (`values.update`). Destructive: what was in those cells is replaced, and the site
+ * cannot undo a remote change.
+ *
+ * Values go in `RAW` unless the caller explicitly asks for `USER_ENTERED`. The same update twice
+ * gives the same cells, so a transient failure may be retried.
+ */
+import { assertPayloadWithin, cellCount, resourceLines, sendSheetsRequest, sheetsUrl, valueInputOption } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, range: string, values: unknown[][], valueInputOption?: string }, capabilities: object, signal?: AbortSignal }} call */
+  async invoke(call) {
+    const { input } = call;
+    const body = await sendSheetsRequest({ call, request: {
+      kind: 'idempotent-write', method: 'PUT',
+      url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['values', input.range] }),
+      query: { valueInputOption: valueInputOption({ option: input.valueInputOption }) },
+      body: assertPayloadWithin({ value: { range: input.range, majorDimension: 'ROWS', values: input.values } }),
+    } });
+    return { updatedRange: body?.updatedRange, updatedRows: body?.updatedRows, updatedColumns: body?.updatedColumns, updatedCells: body?.updatedCells };
+  },
+  describeAffectedResources({ input }) {
+    return resourceLines({ lines: [`Overwrite ${input.range} of spreadsheet ${input.spreadsheetId} (${cellCount({ values: input.values })} cell(s); current values are replaced)`] });
+  },
+};

package/google-workspace/tools/sheets-admin/README.md

@@ -0,0 +1,45 @@
+# Sheets admin tools (`tools/sheets-admin/`)
+
+## Purpose
+
+The structural and formatting half of the Google Sheets chat tools: everything beyond reading and
+writing values. Each file is one tool module declared in `../../tovu-agent-tools.json` and reached
+by the assistant under its `name` with the host's plugin prefix (in Tovu, `p_google_workspace__<name>`).
+
+| Module | Tool | Effect |
+|---|---|---|
+| `tab-modify.mjs` | `sheets_tab_modify` | destructive |
+| `sort.mjs` | `sheets_sort` | destructive |
+| `basic-filter.mjs` | `sheets_basic_filter` | write |
+| `filter-views.mjs` | `sheets_filter_views` | destructive |
+| `format.mjs` | `sheets_format` | write |
+| `named-ranges.mjs` | `sheets_named_ranges` | destructive |
+| `protected-ranges-get.mjs` | `sheets_protected_ranges_get` | read |
+| `developer-metadata.mjs` | `sheets_developer_metadata` | read |
+| `batch-update.mjs` | `sheets_batch_update` | destructive |
+| `export-csv.mjs` | `sheets_export_csv` | read |
+| `open-existing.mjs` | `sheets_open_existing` | read |
+
+## How it fits
+
+- Every change is ONE `spreadsheets.batchUpdate`: named tools build reviewed requests and call
+  `runBatchUpdate` (`../../lib/sheets-client.mjs`), the same path as `sheets_batch_update`, so
+  every request passes the inventory in `../../lib/sheets-admin-request-kinds.mjs` first. A batch
+  holding a non-replayable kind is a `write` for the shared client (`../../lib/http.mjs`): an
+  unknown outcome is `uncertain-outcome` and is never replayed.
+- The host confirms `write` and `destructive` calls with the card built from each module's
+  `describeAffectedResources` (spreadsheet first, then what changes; for a raw batch, every kind).
+- Tokens come from the host capability inside the shared client; no module sees or returns one.
+- Bounds: tool answers at most 64 KiB (refused, not cut); batches at most 100 requests, 1 MiB and
+  48 different kinds; CSV export at most 20,000 rows, 100,000 cells and 4 MiB, read in 10,000-cell
+  chunks through `values.batchGet` (ranges in the query, never the path), written through the host
+  `artifacts` capability (which refuses until the host binds a store).
+- `open_existing` verifies a picked file through Drive `files.get` (granted, not trashed, a
+  spreadsheet) and returns metadata only; the Picker itself is a later lot.
+
+## Extension points
+
+A new request kind is one reviewed row in `REQUEST_KINDS` (effect, replay class, required fields)
+plus a line in `skills/google-workspace/references/sheets.md`. A new named wrapper is a module here
+that builds inventory requests and calls `runBatchUpdate`, plus a declaration appended to
+`tovu-agent-tools.json`. Phase B may fold the shared helpers into `lib/sheets-client.mjs`.

package/google-workspace/tools/sheets-admin/basic-filter.mjs

@@ -0,0 +1,32 @@
+/**
+ * @file Tool `sheets_basic_filter` (`p_google_workspace__sheets_basic_filter`): set or clear the basic
+ * filter of one tab. A filter only hides rows, so the tool is a `write` (confirmed, never destructive).
+ *
+ * Exists as a named wrapper over the reviewed `setBasicFilter` and `clearBasicFilter` request kinds.
+ * Reading a tab's filter is NOT an action here: a tool's effect is declared per tool, so a read
+ * inside this write tool would ask for a confirmation it does not need. `sheets_get` with
+ * `fields: "sheets(properties(sheetId),basicFilter)"` reads it without one.
+ */
+import { resourceLines, runBatchUpdate, sheetsClientFor, spreadsheetLine } from '../../lib/sheets-client.mjs';
+import { gridRangeLabel } from '../../lib/sheets-a1.mjs';
+
+/** The set/clear request. @complexity O(1). */
+function changeRequest(input) {
+  if (input.action === 'clear') return { clearBasicFilter: { sheetId: input.sheetId } };
+  // No sortSpecs: a basic-filter sort physically reorders rows (destructive), so sorting stays in `sheets_sort`.
+  const filter = { range: input.range, ...(input.filterSpecs ? { filterSpecs: input.filterSpecs } : {}) };
+  return { setBasicFilter: { filter } };
+}
+
+export default {
+  async invoke({ input, capabilities, signal }) {
+    const client = sheetsClientFor({ capabilities });
+    await runBatchUpdate({ client, connectionRef: input.connectionRef, spreadsheetId: input.spreadsheetId, requests: [changeRequest(input)] }, { signal });
+    return { action: input.action, sheetId: input.sheetId ?? input.range.sheetId };
+  },
+  describeAffectedResources({ input }) {
+    const where = input.action === 'set' ? gridRangeLabel({ range: input.range }) : `tab ${input.sheetId}`;
+    const what = input.action === 'set' ? 'replace the basic filter on' : 'remove the basic filter from';
+    return resourceLines({ lines: [spreadsheetLine(input), `${what} ${where}`] });
+  },
+};

package/google-workspace/tools/sheets-admin/batch-update.mjs

@@ -0,0 +1,25 @@
+/**
+ * @file Tool `sheets_batch_update` (`p_google_workspace__sheets_batch_update`): send up to 100 reviewed Sheets
+ * request objects in one atomic `spreadsheets.batchUpdate`. Always destructive: the card lists every
+ * request kind in the batch with its count and effect.
+ *
+ * Exists for broad coverage without a wrapper per request family (dimensions, merges, validation,
+ * conditional formats, charts, banding, groups, pivots, slicers, tables, metadata, protection). Only
+ * kinds in `lib/sheets-admin-request-kinds.mjs` pass; anything else fails closed before any request.
+ */
+import { outputFits, resourceLines, runBatchUpdate, sheetsClientFor, spreadsheetLine } from '../../lib/sheets-client.mjs';
+import { checkRequests, describeRequests } from '../../lib/sheets-admin-request-kinds.mjs';
+
+export default {
+  async invoke({ input, capabilities, signal }) {
+    const { kinds } = checkRequests({ requests: input.requests });
+    const { replies } = await runBatchUpdate({ client: sheetsClientFor({ capabilities }), connectionRef: input.connectionRef, spreadsheetId: input.spreadsheetId, requests: input.requests }, { signal });
+    const summary = { applied: input.requests.length, kinds: Object.fromEntries([...kinds].map(([kind, { count }]) => [kind, count])) };
+    // The batch has already been applied: an oversized reply list is dropped, not turned into an error.
+    // 4 KiB of headroom keeps room for the summary next to the replies.
+    return outputFits({ value: replies }, { headroomBytes: 4096 }) ? { summary, replies } : { summary, repliesOmitted: 'larger than 64 KiB' };
+  },
+  describeAffectedResources({ input }) {
+    return resourceLines({ lines: [spreadsheetLine(input), ...describeRequests({ requests: input.requests })] });
+  },
+};

package/google-workspace/tools/sheets-admin/developer-metadata.mjs

@@ -0,0 +1,28 @@
+/**
+ * @file Tool `sheets_developer_metadata` (`p_google_workspace__sheets_developer_metadata`): read developer
+ * metadata by id (`get`) or by data filters (`search`). Read only; creating, changing and deleting
+ * metadata go through `batch_update`.
+ *
+ * Exists so chat can find the rows, columns or tabs an integration tagged. The metadata id is an
+ * integer (input schema and the check here) before it becomes a URL path segment.
+ */
+import { assertOutputWithin, sheetsClientFor, sheetsUrl } from '../../lib/sheets-client.mjs';
+import { GoogleWorkspaceError } from '../../lib/request-policy.mjs';
+
+/** The request for one action; the metadata id is checked before it reaches the path. @complexity O(1). */
+function requestFor(input) {
+  if (input.action === 'search') {
+    return { url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['developerMetadata'], method: ':search' }), method: 'POST', body: { dataFilters: input.dataFilters } };
+  }
+  if (!Number.isSafeInteger(input.metadataId) || input.metadataId < 0) throw new GoogleWorkspaceError({ code: 'invalid-input' }, { detail: 'metadataId' });
+  return { url: sheetsUrl({ spreadsheetId: input.spreadsheetId }, { segments: ['developerMetadata', String(input.metadataId)] }) };
+}
+
+export default {
+  async invoke({ input, capabilities, signal }) {
+    // A search is a POST that changes nothing: `read` lets the client retry it.
+    const body = await sheetsClientFor({ capabilities }).request({ connectionRef: input.connectionRef, kind: 'read', ...requestFor(input) }, signal ? { signal } : {});
+    const value = input.action === 'search' ? { matches: body?.matchedDeveloperMetadata ?? [] } : { metadata: body };
+    return assertOutputWithin({ value: { action: input.action, ...value } });
+  },
+};