@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/google-workspace/mcp.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {}
+}

package/google-workspace/plugin.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "google-workspace",
+  "version": "0.1.0",
+  "description": "Connects one Google account to this site with Google's own sign-in, then works with the Google files the person picks or this site creates (the drive.file permission, never the whole Drive). v1 ships Google Sheets: chat tools for spreadsheets and a form destination that appends submissions as rows. Products are turned on separately; turning one off stops its tools and deliveries without revoking the sign-in.",
+  "author": "Tovu",
+  "license": "Apache-2.0",
+  "extensions": {
+    "tovu": {
+      "maturity": "soon",
+      "vendorAliases": ["google-sheets", "docs.google.com", "sheets.googleapis.com", "drive.googleapis.com", "gmail"],
+      "displayName": "Google Workspace",
+      "summary": "Sign in with Google once, then work with the spreadsheets you choose or create here.",
+      "id": "tovu/google-workspace",
+      "provides": [
+        "api-connection:google-workspace",
+        "form-destination:google-sheets"
+      ],
+      "credentialCards": [
+        {
+          "target": "google-workspace-sign-in",
+          "title": "Connect Google Workspace",
+          "label": "Google Workspace",
+          "category": "general",
+          "intro": "Sign in with Google to read and update the spreadsheets you choose, create spreadsheets, or send form submissions to a sheet. No API key is needed.",
+          "usedFor": [
+            "Reads and updates spreadsheets you choose, and creates new ones",
+            "Saves your site's form submissions to a spreadsheet"
+          ],
+          "keyHint": "Continue to Google's sign-in page and allow access to the files you use with this app (drive.file). Choose existing spreadsheets in Tovu's Google file picker after signing in.",
+          "saveKind": "oauth",
+          "saveTarget": "google-workspace",
+          "permissions": "Requests https://www.googleapis.com/auth/drive.file: access only to files you choose or Tovu creates. It does not grant access to your whole Drive, Gmail or Calendar. Google Sheets must also be turned on in the plugin panel.",
+          "helpUrl": "https://developers.google.com/workspace/drive/api/guides/api-specific-auth#drive_api_scopes",
+          "helpLabel": "What Google file access allows",
+          "baseUrl": "https://accounts.google.com"
+        },
+        {
+          "target": "google-workspace-oauth-client",
+          "title": "Use your own Google sign-in app",
+          "label": "google-workspace/account OAuth client",
+          "ownedApiLabel": "google-workspace/account OAuth client",
+          "category": "general",
+          "intro": "For a self-hosted site that cannot use Tovu's Google sign-in app, or an organisation using its own Google Cloud project. Save the app's client ID and client secret here, then sign in with Google. This does not replace your account sign-in.",
+          "usedFor": [
+            "Uses your own Google sign-in app to connect this site to Google Workspace"
+          ],
+          "keyHint": "In Google Cloud, open Google Auth platform → Clients → Create client. Choose Web application for a hosted site, with this site's address plus /api/agent-plugins/connections/oauth/callback as the redirect URI, or Desktop app for Tovu desktop. Turn on the Sheets, Drive and Picker APIs. Paste the client secret here. Not a service-account key.",
+          "saveKind": "api",
+          "helpUrl": "https://console.cloud.google.com/auth/clients",
+          "helpLabel": "Create your Google sign-in app",
+          "baseUrl": "https://oauth2.googleapis.com/token",
+          "fields": [
+            {
+              "name": "username",
+              "label": "Google client ID",
+              "hint": "Required. Copy the client ID for the same Google sign-in app as the client secret.",
+              "required": true
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "keywords": [
+    "google-workspace",
+    "google",
+    "google-sheets",
+    "sheets",
+    "spreadsheet",
+    "google-drive",
+    "oauth",
+    "sign-in",
+    "form-destination:google-sheets",
+    "form-submissions"
+  ]
+}

package/google-workspace/products.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "baseScopes": ["https://www.googleapis.com/auth/drive.file"],
+  "products": [
+    {
+      "id": "sheets",
+      "label": "Google Sheets",
+      "toolPrefix": "sheets_",
+      "requiredScopes": ["https://www.googleapis.com/auth/drive.file"]
+    }
+  ]
+}

package/google-workspace/skills/google-workspace/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: google-workspace
+description: Connect one Google account to this site with Google's own sign-in, then work with the Google Sheets the person picks or this site creates (the drive.file permission, never the whole Drive), and send form submissions to a spreadsheet. Explains connecting, products, the account actions (reconnect, switch, disconnect) and what each error means.
+---
+
+# Google Workspace
+
+One sign-in covers every Google product this plugin ships. Version 1 ships **Google Sheets**.
+Docs, Slides, Drive, Gmail and Calendar come later on the same sign-in.
+
+Say it simply: "Connect Google Workspace, then choose or create a spreadsheet."
+
+**Follow the host guidance first.** It names the host's exact tools for turning the plugin on,
+connecting, and opening the own-client card. Where it is more specific than this skill, it wins.
+
+## Choose the connection for the task
+
+For the tasks on its `usedFor` list, use **Connect Google Workspace**: start the host's connect
+action for the plugin `google-workspace`. It reuses a working sign-in. Choose it yourself; never ask
+the person to pick between sign-in and a key. There is no API-key route.
+
+Only if sign-in fails from a self-hosted site's address, or the person asks to use their own
+Google Cloud project, open the plugin's **Use your own Google sign-in app** card (target
+`google-workspace-oauth-client`). It saves the client ID and secret; then the person signs in as
+usual. See [connection](references/connection.md).
+
+Never ask for a secret in chat. Never offer to replace a working sign-in or saved app unless asked.
+
+## What this site can and cannot see
+
+- This site asks only for **`drive.file`**: the files the person picks with Google's file picker or
+  that this site creates. It cannot browse or read the rest of their Drive.
+- **A pasted spreadsheet link grants nothing.** If the person pastes a link, explain that they need
+  to choose the file with the picker (or let this site create a new spreadsheet).
+- Never ask for a password, a token, a client secret or an API key in chat, and never accept one.
+  Sign-in always happens on Google's own page. A site that cannot use the host's own Google client
+  can use its own OAuth client, saved only through the host's secure credential form: see
+  [connection](references/connection.md), "Advanced: your own Google OAuth client".
+
+## Before working on a spreadsheet
+
+1. The plugin ships **switched off**. Offer to turn it on, or the person turns it on in the host's
+   plugin settings.
+2. Connect with the host's connect action. If sign-in is needed and starts successfully, it shows a
+   card; Google's consent page opens in the system browser. Its result carries `connectionRef`: keep
+   it and pass it unchanged as `connectionRef` to every tool below. See
+   [connection](references/connection.md).
+3. Check who is signed in with this plugin's `account_info { connectionRef }` tool and name that
+   account before you change anything.
+4. Sheets itself starts **off**: until the person turns Sheets on in the Google Workspace panel,
+   every Sheets tool answers `product-disabled`. Ask them to turn it on there; chat cannot.
+5. To use an existing spreadsheet, the person chooses it in the plugin's **Choose spreadsheet** tab
+   (Google's file picker); then `sheets_open_existing` with its id works. Or create a new one.
+
+Load [connection](references/connection.md) for sign-in, products and account actions,
+[sheets](references/sheets.md) before any spreadsheet work, [form delivery](references/form-delivery.md)
+when the person wants form submissions in a sheet, and [troubleshooting](references/troubleshooting.md)
+when a call fails.
+
+## Errors
+
+Every failure has a `code`, a plain `message`, `retryable`, `outcome` and a `nextAction`. Follow the
+next action; do not retry on your own when `retryable` is false. When `outcome` is `"unknown"` (for
+example `uncertain-outcome`), the change may already be in the spreadsheet: ask the person to look
+before trying again. Never repeat an append, create or copy just because the answer was lost.
+
+## Sheets tools (spreadsheets, values, search)
+
+Read [sheets](references/sheets.md) first. In short: read with `sheets_get`, `sheets_values_get`,
+`sheets_values_batch_get` or `sheets_find`; create or copy with `sheets_create`, `sheets_copy` or
+`sheets_copy_tab`; add rows with `sheets_values_append`; overwrite or clear with the
+`sheets_values_*update` / `*clear` tools or `sheets_find_replace`. Every change shows a
+confirmation card; only the person's click approves it.
+
+## Tabs, filters, formatting and raw batch updates
+
+The Sheets reference also covers tab changes, sorting, filters and filter views, formatting, named
+and protected ranges, developer metadata, raw batch updates (and which request kinds are allowed),
+CSV export and opening a picked spreadsheet (`sheets_open_existing`). Errors `limit-exceeded`
+(narrow the request), `unsupported-request` (use a listed request kind), `invalid-input` (fix the id,
+range or option) are raised by the plugin before anything is sent to Google; `not-a-spreadsheet`
+means the chosen file is not a spreadsheet (pick one).

package/google-workspace/skills/google-workspace/references/connection.md

@@ -0,0 +1,102 @@
+# Connecting Google Workspace
+
+## Signing in
+
+- **Desktop app:** the consent page opens in the system browser (never inside the admin page). Google sends
+  the person back to a one-time address on this computer (`127.0.0.1`), which closes right after.
+- **Hosted site:** the consent page opens in a new tab and returns to this site.
+- The consent screen shows the name of the Google sign-in app in use (the host's own app, or the
+  site's own one). The person should allow every permission listed; if they untick one, the
+  connection is not saved and this site says which permission is missing.
+- If the person cancels on Google's page, nothing is saved. Offer to try again only if they want to.
+- The host's connect action answers `{ status, connectionRef }`. `connectionRef` is an opaque reference
+  to this connection (not a password or token). Every tool takes it as `connectionRef`; it does not
+  change on reconnect or account switch. If you lost it, run the connect action again: when
+  already connected it answers at once without a new sign-in.
+
+## Products
+
+Each product (v1: Sheets) is turned on separately, and turning it on is a separate step from
+granting its permissions. Sheets needs only `drive.file`, which the first sign-in already grants.
+
+- Every product starts **off**. Until the person turns Sheets on in the Google Workspace panel,
+  every Sheets tool answers `product-disabled` ("turn it on in the Google Workspace panel") and
+  sends nothing to Google. Tell the person to enable Sheets there; you cannot turn it on from chat.
+  Checking which account is connected (`account_info`) works while every product is off.
+- Turning a product **off** stops its tools at once (even a call that is part way through stops
+  before its next request to Google). Its form deliveries are retried for about a day (about 8
+  attempts) and then marked failed; submissions stay saved in this site, but a delivery that already
+  failed is not sent again when the product is turned back on. It does **not** sign the account
+  out or revoke anything at Google.
+- On the **desktop app**, adding a product that needs a new permission means signing in again and
+  approving the full list (installed apps cannot add permissions one at a time).
+- On a **hosted site**, Google adds the new permission to the existing ones.
+
+## Where the person does it
+
+The plugin's admin page in the host (its Google Workspace plugin page) has three tabs:
+
+- **Google Workspace** - connect, reconnect, switch account, disconnect, and turn each product on or
+  off ("Grant permission" appears when a product is on but Google has not granted it yet).
+- **Choose spreadsheet** - Google's file picker. Choosing a spreadsheet there is what lets this site open
+  it; the chosen spreadsheets are listed with their ids, which you can use in chat.
+- **Form destinations** - which form sends its submissions to which spreadsheet tab.
+
+The panels cannot open links themselves: when a sign-in starts, the admin page shows a
+**Continue to sign-in** button above the panel (on the desktop app it opens the system browser).
+
+## Account actions
+
+- **Reconnect** - sign in again with the same account. The connection, its spreadsheets and its
+  form bindings stay as they are. Use it when this site says "Reconnect required".
+- **Switch account** - sign in with a different Google account. The panel shows the new account and
+  nothing changes until the person confirms it (or keeps the current one). While the switch waits,
+  the panel lists the plugin's form destinations, each with an unticked box. Only the ones the
+  person ticks move to the new account, and each moves only after this site checked that the new account
+  can open its spreadsheet; the panel then lists what moved and what did not (and why).
+  - A destination left unticked, or one the new account could not open, keeps the old account. Its
+    deliveries fail with `authorization-required` ("Reconnect required") until the person chooses
+    its spreadsheet again in the **Form destinations** tab with the new account.
+  - Deliveries that were already queued keep the account they were created with, so after a switch
+    they fail; they are not sent again automatically.
+  - The Google Workspace tools act as the new account at once.
+- **Disconnect** - the panel first asks "Disconnect and revoke?" (it cannot be undone at Google);
+  after the person confirms, this site stops using the account at once, then asks Google to revoke its access.
+  - If Google confirms, the saved sign-in is deleted.
+  - If Google does not answer or refuses, this site shows **"Disconnected locally; Google revocation
+    pending"**. This site no longer uses the account, keeps the switched-off sign-in only so it can
+    retry, and the person can remove this site's access at https://myaccount.google.com/connections (the panel's **Open
+    Google Account page** button opens it). Never tell the person
+    revocation succeeded unless this site said "confirmed".
+
+## Advanced: your own Google OAuth client
+
+A self-hosted site whose address the host's Google sign-in app does not list (this site then says it
+"cannot sign in from this site's address"), or an organisation that wants its own Google Cloud
+project, can use its own OAuth client instead of the host's. The client secret is typed only into
+the host's secure credential form, never into chat. Never ask for it in chat and never accept one pasted there.
+
+1. In their own Google Cloud project, under **Google Auth platform → Clients → Create client**, the
+   person creates an OAuth client: **Web application** for a
+   hosted site, with the authorized redirect URI the card names (this site's address plus the
+   host's OAuth callback path); **Desktop app** for the desktop app. They enable the Google Sheets API, Google Drive API and Google Picker API there and
+   set the consent screen up.
+2. Open the plugin's **Use your own Google sign-in app** card (its credential card with
+   `target: "google-workspace-oauth-client"`; the host guidance names the tool). It fixes the label and address; the person enters only the client ID and client secret:
+   - **Label:** exactly `google-workspace/account OAuth client`
+   - **Base URL:** `https://oauth2.googleapis.com/token`
+   - **Username:** the OAuth client ID
+   - **Token:** the client secret
+   Use the host's generic custom-credential form only if the plugin card is unavailable.
+3. The person reconnects in the Google Workspace panel. Until then it shows **Reconnect required**:
+   a sign-in made with one client cannot be used with another. Spreadsheets chosen before must be
+   chosen again with the picker, because Google ties each picked file to the Cloud project whose client picked it.
+
+If this site says it **"cannot use your own OAuth client"**, the message names the saved credential and
+what is wrong (base URL or missing client ID): fix it in the host's saved credentials, then retry. After
+the client changes (saved, replaced or removed), `reconnect-required` means "reconnect once".
+
+To go back to the host's own client, delete that saved credential and reconnect. On a hosted site the file
+picker uses the site's Picker settings (`TOVU_GOOGLE_PICKER_BROWSER_KEY`, `TOVU_GOOGLE_PICKER_APP_ID`):
+with your own client the operator sets them to that project's browser key and project number, or the
+picker cannot open the chosen files.

package/google-workspace/skills/google-workspace/references/form-delivery.md

@@ -0,0 +1,50 @@
+# Sending form submissions to Google Sheets
+
+The **Google Sheets** form destination adds each accepted submission as a new row.
+
+The person picks where each form goes in the plugin's **Form destinations** tab: the form's short
+name, a spreadsheet (one already chosen, or Google's file picker), and a tab. This site checks with Google
+that the account can open that spreadsheet and that the tab exists before saving; a pasted id that
+was never chosen is refused. Saving asks them to confirm that rows stay in the spreadsheet. Saving
+turns delivery on for that form straight away: there is nothing to copy into this site's settings, and
+removing the destination there stops new rows (rows already written stay in the spreadsheet).
+
+- Each form goes to its own tab. This site remembers the tab by its id, so renaming the tab is safe.
+- The first row holds the headers: `_tovu_submission_id`, `_tovu_submitted_at`, then the field
+  labels. The visitor's IP address is never sent.
+- Checkbox groups are joined with ", ". Values are written as plain text, never as formulas.
+- A new form field becomes a new column at the end. This site tags each column it writes with the
+  field's id (hidden spreadsheet metadata, not visible in cells), so existing columns never change
+  meaning: editing a field's label, renaming a header, or inserting or moving columns keeps each
+  field's answers in its own column. Deleting a column removes its tag; the field then gets a new
+  column.
+- Every submission stays saved in this site, whatever happens to the spreadsheet. A delivery that cannot
+  go through yet (Google slow or asking this site to slow down, Google unavailable, Sheets turned off) is
+  retried about 8 times over about a day; after that it is marked failed and is not sent again.
+  A sign-in problem (`authorization-required`) fails the delivery at once.
+- Delivery is **at least once with best-effort dedupe**: before every append this site looks for the
+  submission id in the `_tovu_submission_id` column (and looks again if Google's answer was lost),
+  so a retry normally does not add a duplicate. A duplicate is still possible in rare cases (for
+  example another person or tool writing to the same tab at the same moment). When this site finds the
+  same submission id on two or more rows it does not add another, and the delivery counts as done.
+  This site does not show such duplicates anywhere yet: if the person suspects one, sort or filter the
+  sheet by `_tovu_submission_id` and delete the extra row.
+- Deleting a submission in this site does **not** delete its row in the spreadsheet. When the person
+  turns this destination on, tell them: "Rows already sent to Google Sheets stay in the spreadsheet
+  if you delete the submission in this site."
+- Turning Sheets off does not pause deliveries indefinitely: they are retried for about a day, then
+  marked failed. Turn Sheets back on within that window.
+
+## When a delivery fails
+
+| code | what it means | what to do |
+|---|---|---|
+| `authorization-required` | Google no longer accepts the sign-in (reconnect required), a permission is missing, or the destination still belongs to the account used before a switch. | Same account: reconnect Google Workspace. After a switch: choose the spreadsheet again in Form destinations (or tick it when confirming the switch). The failed delivery stays listed in this site as failed; it is not sent again. |
+| `resource-not-granted` | The connected account cannot open this spreadsheet. | Choose the spreadsheet again with the file picker. |
+| `configuration-invalid` | The destination does not name a tab for this form, or the tab was deleted. | Choose the tab again in the destination settings. |
+| `mapping-invalid` | The columns cannot be matched: `_tovu_submission_id` or `_tovu_submitted_at` is missing from row 1, a header appears twice, two fields share a label, or one field's hidden column tag appears on two columns (another tool copied it). | Repair the headers in row 1 (or give the fields distinct labels); for a doubled tag, delete the extra column. |
+| `destination-limit` | The tab has more than 50,000 rows, too many to check for duplicates. | Point the form at a new tab or spreadsheet. |
+| `rate-limited` | Google asked this site to slow down. | Usually nothing; it retries after the wait, for about a day at most. |
+| `outcome-unknown` | Google did not confirm the append and the row was not found. | Nothing; the next try checks again before appending. |
+| `adapter-unavailable` | Sheets is turned off for the plugin. | Turn Sheets on. Deliveries still being retried (about a day) then go through; older ones stay failed. |
+| `delivery-failed` | Google was unavailable or answered unexpectedly. | Usually nothing; it retries for about a day, then the delivery stays failed. |

package/google-workspace/skills/google-workspace/references/sheets.md

@@ -0,0 +1,149 @@
+# Google Sheets
+
+The names below are this plugin's tool names; the host may show them with its own plugin prefix
+(the host guidance says which). Every spreadsheet tool takes the `connectionRef` of the
+connection; tools on an existing file also take its `spreadsheetId`.
+
+## Choosing a spreadsheet
+
+- **Existing spreadsheet:** the person picks it with Google's file picker. That pick is what lets
+  this site open the file. A pasted link is not enough.
+- **New spreadsheet:** This site can create one; this site then has access to it automatically.
+- If the person cancels the picker, keep the current settings.
+
+## Reading and changing data
+
+- Reads are bounded (about 500 rows or 5,000 cells at a time). For more, read the next range.
+- Values a visitor or the person typed are written **as text exactly as given** (`RAW`); this site never
+  turns them into formulas.
+- Changing, clearing or deleting data shows the person a confirmation card first. Only their click
+  approves it. Remote changes cannot be undone from this site.
+- If a change comes back with `outcome: "unknown"`, ask the person to check the spreadsheet before
+  trying again.
+
+## Limits
+
+Google allows each account about 60 requests a minute; this site keeps under that (about 45 per account
+and 240 per site). When Google asks this site to wait, this site waits; nothing is lost.
+
+## Spreadsheet, values and search tools
+
+Names below are the plugin's tool names, without the host's prefix. Every call needs `connectionRef`; calls on an
+existing file also need `spreadsheetId` (the id from the picker or from `sheets_create`).
+
+| To… | Use | Asks the person first? |
+|---|---|---|
+| See the title, URL and tabs (tab ids for other tools) | `sheets_get` | no |
+| Read one range | `sheets_values_get` with `range`, for example `'Leads'!A1:D50` | no |
+| Read several ranges at once (up to 20) | `sheets_values_batch_get` | no |
+| Find cells containing a text (up to 20 ranges) | `sheets_find` | no |
+| Read by data filter (A1, grid range or developer metadata) | `sheets_get_by_data_filter` (metadata) or `sheets_values_by_data_filter` with `action: "get"` (values) | the second one does |
+| Make a new spreadsheet | `sheets_create` | yes |
+| Copy a whole spreadsheet | `sheets_copy` | yes |
+| Copy one tab into another spreadsheet | `sheets_copy_tab` with the numeric `sheetId` | yes |
+| Add rows after the existing table | `sheets_values_append` | yes |
+| Overwrite cells | `sheets_values_update` (one range) or `sheets_values_batch_update` (up to 100) | yes, as a destructive change |
+| Clear cells | `sheets_values_clear` or `sheets_values_batch_clear` | yes, as a destructive change |
+| Replace a text everywhere on a tab or in every tab | `sheets_find_replace` (`sheetId` or `allSheets: true`) | yes, as a destructive change |
+
+### Reading a lot of data
+
+A read returns at most 500 rows, 5,000 cells or 64 KiB. When there is more, the result has
+`continuation`: call `sheets_values_get` with exactly that range to read the next part. Do not guess
+the next range yourself. `sheets_get` and `sheets_get_by_data_filter` have no continuation: when
+their answer would be too large they fail with `limit-exceeded`; ask for fewer ranges or leave out
+grid data. A `fields` mask containing `*` or `data` reads cell data too, so it is refused
+(`invalid-input`) unless `includeGridData: true` is given (with `ranges` for `sheets_get`).
+`sheets_find` searches at most 50,000 cells and returns at most 100 matches
+(`truncated: true` means there were more); narrow the ranges when it says `limit-exceeded`.
+
+### Writing values
+
+- Values are stored **as text exactly as given** (`RAW`). Only pass
+  `valueInputOption: "USER_ENTERED"` when the person explicitly wants Sheets to interpret the values
+  (formulas, dates); never for text a visitor typed.
+- One write body is at most 1 MiB; split bigger writes into several calls.
+- `sheets_values_append` inserts new rows below the table, so nothing under it is written over.
+
+### When the answer is lost
+
+`sheets_values_append`, `sheets_create`, `sheets_copy`, `sheets_copy_tab` and `sheets_find_replace`
+are never repeated automatically. If one fails with `uncertain-outcome` (`outcome: "unknown"`), ask
+the person to look at the spreadsheet (or their Drive) first; repeating it could add the rows, the
+file or the replacement twice.
+
+### Errors these tools add
+
+- `invalid-input`: the request was refused before anything was sent (for example a malformed id or
+  range). Fix it and try again.
+- `limit-exceeded`: the request or its answer is bigger than the tool allows. Ask for less.
+
+## Tabs, sorting, filters, formatting and structure
+
+Each of these tools takes `connectionRef` and `spreadsheetId`. Tabs are named by their numeric
+`sheetId` (it survives renames); ranges are grid ranges with zero-based, end-exclusive indices, for
+example `{ "sheetId": 0, "startRowIndex": 1, "endRowIndex": 10, "startColumnIndex": 0, "endColumnIndex": 4 }`
+is rows 2-10, columns A-D.
+
+| Tool | What it does | Confirmation |
+|---|---|---|
+| `sheets_tab_modify` | add, rename, delete, duplicate or move a tab | danger card (delete removes the tab's data) |
+| `sheets_sort` | reorder rows of a range by up to 10 columns | danger card (the old order is gone) |
+| `sheets_basic_filter` | set or clear a tab's filter (hides rows; no sorting: use `sheets_sort`). To read a filter, use `sheets_get` with `fields: "sheets(properties(sheetId),basicFilter)"` (no card) | card |
+| `sheets_filter_views` | list, add, update, duplicate or delete saved filter views | danger card |
+| `sheets_format` | number formats, fonts, colours, alignment, wrapping, borders, frozen rows/columns, column widths | card; never changes values |
+| `sheets_named_ranges` | list, add, update or delete named ranges | danger card (formulas follow the name) |
+| `sheets_protected_ranges_get` | protected ranges, editors, and whether this account may edit | none (read) |
+| `sheets_developer_metadata` | get metadata by id or search with data filters | none (read) |
+| `sheets_batch_update` | up to 100 raw Sheets requests in one atomic call | danger card listing every request kind |
+| `sheets_export_csv` | one tab (or `A1:F500` of it) as a downloadable CSV file | none (read) |
+| `sheets_open_existing` | check a picked spreadsheet, or point the person to the picker | none (read) |
+
+- `sheets_format`: give `cellFormat` together with `fields`, the exact format properties to set
+  (for example `["textFormat.bold", "numberFormat"]`). Properties not listed stay as they are.
+- `sheets_open_existing` without `spreadsheetId` answers `waiting`: ask the person to choose the file
+  with Google's picker in the Google Workspace plugin, or offer to create a new spreadsheet.
+  `file-not-granted` means the file was never picked (or was trashed); `not-a-spreadsheet` means it is
+  not a spreadsheet.
+- `sheets_export_csv` reads at most 20,000 rows and 100,000 cells and writes at most 4 MiB. A bigger
+  tab is refused (`limit-exceeded`), never cut short: export a range instead. It returns a file
+  reference, not the data. On a site that cannot save files it refuses with `export-unavailable`
+  before reading anything; read the values in chat instead.
+  Text that starts with `=`, `+`, `-`, `@` (or a tab or line break) is written with a leading `'`,
+  so a spreadsheet app opening the file shows it as text instead of running it as a formula (a
+  visitor could have typed one into a form). The trade-off: with the default formatted values, a
+  number shown as `-5` or a phone number like `+1 555` also gets the `'`. Ask for
+  `valueRenderOption: "UNFORMATTED_VALUE"` when exact numbers matter: real numbers are never prefixed.
+- Answers over 64 KiB are refused with `limit-exceeded`: narrow to one tab or fewer items.
+
+## Raw batch updates (`sheets_batch_update`)
+
+Each request object names exactly one request kind, for example
+`{ "insertDimension": { "range": { "sheetId": 0, "dimension": "ROWS", "startIndex": 5, "endIndex": 7 } } }`.
+Field masks (`fields`) must name the properties to change; `*` is refused because it resets
+everything else. A batch is all-or-nothing at Google.
+
+Supported request kinds. Changes data or protection (shown as destructive on the card):
+`updateSheetProperties`, `repeatCell`, `deleteNamedRange`, `deleteSheet`, `autoFill`, `cutPaste`,
+`copyPaste`, `mergeCells`, `updateCells`, `deleteDimension`, `deleteEmbeddedObject`,
+`deleteFilterView`, `findReplace`, `pasteData`, `textToColumns`, `deleteRange`,
+`deleteConditionalFormatRule`, `sortRange`, `addProtectedRange`, `updateProtectedRange`,
+`deleteProtectedRange`, `deleteBanding`, `deleteDeveloperMetadata`, `randomizeRange`,
+`deleteDimensionGroup`, `trimWhitespace`, `deleteDuplicates`, `deleteTable`, `setBasicFilter` (its
+`sortSpecs` reorder rows).
+
+Other changes: `updateSpreadsheetProperties`, `updateDimensionProperties`, `updateNamedRange`,
+`addNamedRange`, `addSheet`, `unmergeCells`, `updateBorders`, `addFilterView`, `appendCells`,
+`clearBasicFilter`, `duplicateFilterView`, `duplicateSheet`, `insertDimension`, `insertRange`,
+`moveDimension`, `updateEmbeddedObjectPosition`, `updateFilterView`, `appendDimension`,
+`addConditionalFormatRule`, `updateConditionalFormatRule`, `setDataValidation`,
+`autoResizeDimensions`, `addChart`, `updateChartSpec`, `updateBanding`, `addBanding`,
+`createDeveloperMetadata`, `updateDeveloperMetadata`, `addDimensionGroup`, `updateDimensionGroup`,
+`updateEmbeddedObjectBorder`, `addSlicer`, `updateSlicerSpec`, `addTable`, `updateTable`.
+
+Not supported: the Connected Sheets data-source kinds (`addDataSource`, `updateDataSource`,
+`deleteDataSource`, `refreshDataSource`, `cancelDataSourceRefresh`) need a BigQuery permission this site
+does not ask for. Any kind not listed is refused with `unsupported-request` before anything is sent.
+
+If a batch that adds, inserts, appends, moves or deletes by position comes back with
+`outcome: "unknown"`, it may already be applied: ask the person to check before sending it again.

package/google-workspace/skills/google-workspace/references/troubleshooting.md

@@ -0,0 +1,31 @@
+# Troubleshooting Google Workspace
+
+| Code | What happened | What to do |
+|---|---|---|
+| `not-connected` | No Google account is connected. | Connect Google Workspace. |
+| `reconnect-required` | Google no longer accepts the saved sign-in (expired, revoked or the password changed). Form deliveries fail at once and stay listed as failed; they are not re-sent after reconnecting. | Reconnect with the same account, then retry once. |
+| `account-changed` | The connection now uses another account than the one shown when the change was confirmed. | Review the account and confirm again. |
+| `missing-permission` | The person did not allow a permission this needs. | Reconnect and allow every listed permission. |
+| `file-not-granted` | This site was never given this file (often a pasted link), or it was removed or trashed. Google answered "not found". | Choose the file again with the picker, or create a new spreadsheet. |
+| `access-denied` | This site was given the file, but this account may not do this to it (for example view-only sharing). Google answered "forbidden". | Check sharing in Google Sheets, then pick it again. |
+| `admin-policy` | A Google Workspace administrator blocks this site. | Ask the administrator to allow this site. |
+| `quota-delay` | Google asked this site to slow down. | Wait (`retryAfterMs` says how long); nothing is lost. |
+| `service-unavailable` / `network-error` | Google could not be reached. | Retry later. |
+| `uncertain-outcome` | Google did not say whether a change was applied. | Ask the person to check the spreadsheet before retrying. Never repeat it automatically. |
+| `invalid-request` | Google received the request and rejected it (bad range, tab or values). Nothing changed. | Fix the request. |
+| `invalid-input` | This site refused the request before sending it: a spreadsheet id, range, field mask or option is not valid for the tool. Nothing was sent to Google. | Fix the id, range or option. |
+| `limit-exceeded` | The request or its answer is larger than the tool allows. Nothing was cut short. | Ask for a smaller range, fewer rows or fewer entries. |
+| `export-unavailable` | This site cannot save files from plugin tools, so a CSV export cannot be offered. Nothing was read. | Read the values in chat (`sheets_values_get`) instead. |
+| `unsupported-request` | A raw batch holds a request kind this site does not allow. Nothing was sent. | Remove it, or use a listed kind (see the Sheets reference). |
+| `picker-not-configured` | This site's operator has not set up Google's file picker, so an existing spreadsheet cannot be chosen here. | Ask the site operator, or create a new spreadsheet. |
+| `not-a-spreadsheet` / `invalid-selection` | The chosen file is not a Google Sheets spreadsheet, or the picker returned something unusable. | Choose a spreadsheet again with the picker. |
+| `unexpected-response` | Google answered in a way this site does not understand. | Report it; do not retry in a loop. |
+| `product-disabled` | The product (Sheets) is turned off; products start off. | Ask the person to turn Sheets on in the Google Workspace panel, then retry. The sign-in is kept. |
+
+**"The file picker session ended"** (`picker-expired`) can also mean the same Choose spreadsheet or
+Form destinations panel was opened again in another tab or by another admin: only the most recently
+opened panel can save a pick. Close the other tabs, reopen the panel, and choose the spreadsheet again.
+
+**"Disconnected locally; Google revocation pending"** means this site stopped using the account but Google
+did not confirm removing access. Retry disconnect later, or remove this site's access at
+https://myaccount.google.com/connections.

package/google-workspace/tools/account-info.mjs

@@ -0,0 +1,18 @@
+/**
+ * @file Tool `account_info` (`p_google_workspace__account_info`): which Google account a
+ * Google Workspace connection is signed in as. The smallest read the plugin's tools file ships with
+ * until the Sheets tools land, and the first thing chat checks before it works on a spreadsheet.
+ *
+ * Exists so chat can name the account it will act as without ever seeing a token: the token is
+ * read from the host inside the shared client and only the account label is returned.
+ */
+import { readAccount } from '../lib/drive-files.mjs';
+import { createGoogleClient } from '../lib/http.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string }, capabilities: { connections: object, http: object }, signal?: AbortSignal }} required */
+  async invoke({ input, capabilities, signal }) {
+    const client = createGoogleClient({ http: capabilities.http, connections: capabilities.connections });
+    return readAccount({ client, connectionRef: input.connectionRef }, signal ? { signal } : {});
+  },
+};

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

@@ -0,0 +1,54 @@
+# Sheets tools A (`tools/sheets/`)
+
+## Purpose
+
+The Google Sheets chat tools for spreadsheets, values, data filters and search (design §D). Each
+`.mjs` file is one tool module declared in `../../tovu-agent-tools.json`; the assistant sees it under
+its `name` with the host's plugin prefix (in Tovu, `p_google_workspace__<name>`). Every tool takes the `connectionRef` of the Google Workspace
+connection; tools on an existing file also take its `spreadsheetId`. Tab, sort, filter, format,
+named-range, protection, metadata, raw batch-update, CSV export and Picker tools live in
+`../sheets-admin/` (a separate lot).
+
+## Tools
+
+| Tool | Effect (card) | Google call | Request kind |
+|---|---|---|---|
+| `sheets_get` | read | `GET spreadsheets/{id}` (field mask; grid data only with ranges) | read |
+| `sheets_get_by_data_filter` | read | `POST spreadsheets/{id}:getByDataFilter` | read |
+| `sheets_create` | write | `POST spreadsheets` | write (never replayed) |
+| `sheets_copy` | write | Drive `POST files/{id}/copy` (`lib/drive-files.mjs`) | write (never replayed) |
+| `sheets_copy_tab` | write | `POST spreadsheets/{id}/sheets/{sheetId}:copyTo` | write (never replayed) |
+| `sheets_values_get` | read | `GET …/values/{range}` | read |
+| `sheets_values_batch_get` | read | `GET …/values:batchGet` (≤ 20 ranges) | read |
+| `sheets_values_append` | write | `POST …/values/{range}:append` (`INSERT_ROWS`) | write (never replayed) |
+| `sheets_values_update` | destructive | `PUT …/values/{range}` | idempotent write |
+| `sheets_values_batch_update` | destructive | `POST …/values:batchUpdate` (≤ 100 ranges) | idempotent write |
+| `sheets_values_clear` | destructive | `POST …/values/{range}:clear` | idempotent write |
+| `sheets_values_batch_clear` | destructive | `POST …/values:batchClear` (≤ 100 ranges) | idempotent write |
+| `sheets_values_by_data_filter` | destructive (all actions) | `POST …/values:batch{Get,Update,Clear}ByDataFilter` | read / idempotent write |
+| `sheets_find` | read | `GET …/values:batchGet`, matched locally (plain text) | read |
+| `sheets_find_replace` | destructive | `POST spreadsheets/{id}:batchUpdate` (`findReplace`) | write (never replayed) |
+
+`write` and `destructive` tools export `describeAffectedResources`, which names the spreadsheet,
+ranges and counts on the host's confirmation card (never cell values beyond what the caller typed).
+
+## How it fits
+
+Every module calls `lib/sheets-client.mjs`, which builds the endpoint (each id or range is ONE
+encoded path segment; `.`/`..` refused), defaults values to `RAW`, enforces the bounds and sends
+through `lib/http.mjs` (token right before each request, where the host charges its budgets; retries, safe errors).
+
+| Bound | Value | At the bound |
+|---|---|---|
+| Values reads (shared across a batch) | 500 rows, 5,000 cells, 64 KiB | cut, with `continuation` = the exact range to read next |
+| Metadata / data-filter metadata reads | 64 KiB | `limit-exceeded` (no partial) |
+| Ranges per batch read / find | 20 | schema refusal |
+| Entries per batch write / clear | 100 | schema refusal |
+| Mutation body | 1 MiB | `limit-exceeded` before sending |
+| `sheets_find` scan / matches | 50,000 cells / 100 matches | `limit-exceeded` / `truncated: true` |
+
+## Extension points
+
+A new Sheets tool adds one module here (or under `../sheets-admin/`) and one entry in
+`tovu-agent-tools.json`; it reuses `sendSheetsRequest`, `sheetsUrl` and the bound helpers. A
+second product uses `lib/http.mjs` directly with its own URL helper.

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

@@ -0,0 +1,23 @@
+/**
+ * @file Tool `sheets_copy_tab` (`p_google_workspace__sheets_copy_tab`): copies one tab into another
+ * spreadsheet the connection can open (`sheets.copyTo`), returning the new tab's properties.
+ *
+ * Each call adds a new tab, so a lost answer is `uncertain-outcome` and is never replayed.
+ */
+import { resourceLines, sendSheetsRequest, sheetsUrl } from '../../lib/sheets-client.mjs';
+
+export default {
+  /** @param {{ input: { connectionRef: string, spreadsheetId: string, sheetId: number, destinationSpreadsheetId: 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: ['sheets', String(input.sheetId)], method: ':copyTo' }),
+      body: { destinationSpreadsheetId: input.destinationSpreadsheetId },
+    } });
+    return { destinationSpreadsheetId: input.destinationSpreadsheetId, sheetId: body?.sheetId, title: body?.title, index: body?.index };
+  },
+  describeAffectedResources({ input }) {
+    return resourceLines({ lines: [`New tab in spreadsheet ${input.destinationSpreadsheetId}, copied from tab ${input.sheetId} of spreadsheet ${input.spreadsheetId}`] });
+  },
+};