@jini-ai/agent-plugins 0.6.17 → 0.6.19

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

@@ -0,0 +1,96 @@
+---
+name: google-login
+description: Set up Google member sign-in in Tovu or Google via an app's existing Supabase Auth.
+---
+
+# Google login
+
+This integration is marked **soon** and has not been tested with a real Google account. Tell the person this before configuring it; do not claim it works until the real sign-in has been checked.
+
+## Choose the destination first
+
+Ask whether the site uses **Tovu members** or **Supabase Auth**, or check whether the supabase plugin is active at runtime. An active plugin is a clue; confirm which authentication system the target app actually uses. Never import the supabase plugin or add a Supabase runtime dependency. Its branch below is instructions only.
+
+Tovu member login and Google Workspace have separate credentials and activation. Use this plugin for visitor sign-in; Google Workspace owns operator file access. Never replace a working client unless asked. Never ask for the Client Secret in chat, tool arguments, pasted configuration, screenshots, or logs. The person enters it in the secure card or Supabase dashboard themselves.
+
+## Prepare the Google client
+
+1. Open [Google Cloud Console](https://console.cloud.google.com/auth/clients) and select or create the app's project.
+2. In Google Auth Platform, configure **Branding** (app identity and support contact), **Audience**, and **Data Access**. Choose External unless access is intentionally restricted to one Workspace organization. Request only `openid email profile`; do not add Drive, Sheets, Gmail, offline access, or refresh-token permissions.
+3. Under **Clients → Create client**, choose **Web application**. The older navigation is **APIs & Services → Credentials → Create Credentials → OAuth client ID**.
+4. Add the exact authorized redirect URI for the chosen branch below. HTTPS is required for production; Google permits localhost development exceptions. Scheme, host, port, path and any configured base path must match exactly. A JavaScript origin is not a replacement for a redirect URI.
+5. Check Audience's Testing/Production status before rollout. Identity-only `openid email profile` requests have an exception to the usual testing-user restrictions. Additional permissions can change those rules. Publishing and verification are separate; consult [Google's production readiness guidance](https://developers.google.com/identity/protocols/oauth2/production-readiness/overview) for the app's current requirements.
+
+## Tovu members
+
+1. Enable Google Login in this site's Agent Plugins. It is bundled but starts disabled.
+2. Read the site's **configured canonical address** and the actual bound workspace ID. Do not infer the address from request Host or forwarded headers. Compute and show the exact callback using the URL API, preserving any configured base path:
+
+   ```js
+   const callback = new URL(configuredSiteAddress);
+   callback.pathname = callback.pathname.replace(/\/$/, '')
+     + '/api/members/v1/workspaces/' + encodeURIComponent(workspaceId) + '/oidc/google/callback';
+   callback.search = '';
+   callback.hash = '';
+   callback.href;
+   ```
+
+   For example, `http://localhost:3000/api/members/v1/workspaces/<workspaceId>/oidc/google/callback`. Replace the placeholder before showing it to the person. Copy the resulting URI into Google's **Authorized redirect URIs**. Use separate local and deployed clients when appropriate.
+3. Open the existing secure card with `credential_save { kind: "plugin-provider", target: "google-login-oauth-client" }`. The person pastes the Client ID into **Google client ID** (`username`) and the Client Secret into the masked secret field (`token`). The existing vault seals it; the assistant never receives it. No extra callback field is needed on the card.
+4. Visit `/signin` and try **Sign in with Google**. Success returns to `/account`. This creates or links a site member, with no administrator privileges. Tovu core owns state, browser binding, PKCE, token validation and member sessions; do not implement a second flow in this plugin.
+5. Explain initial linking: Google-verified `@gmail.com`/`@googlemail.com` addresses and verified Google Workspace accounts with an `hd` claim auto-link directly. Other Google addresses require **one emailed code** to the member's address before the first auto-link, because Google's email verification can outlive mailbox ownership. Later sign-ins use issuer + subject, even if email changes. Disabled or trashed members cannot sign in.
+6. Check sign-out and `/account` **Unlink Google**. Unlink requires a recent sign-in and another usable sign-in method; set a password if directed. Unlink must remain effective on the next Google sign-in. Reconnect deliberately with **Connect Google** from the signed-in `/account` page. It does not revoke Google Workspace file access.
+
+## Google via Supabase Auth
+
+1. Open the target project's **Supabase dashboard → Authentication → Providers → Google** and enable Google.
+2. The person enters the **same Google Client ID and Client Secret** directly in that Supabase panel themselves, never in chat. Tovu's credential card is unnecessary unless this site also uses Tovu members.
+3. Copy the exact **Callback URL (for OAuth)** shown on that panel. Add it to the Google OAuth client's **Authorized redirect URIs**. A hosted callback commonly looks like `https://<project-ref>.supabase.co/auth/v1/callback`; use the displayed value, including a custom domain if configured. For local Supabase, use the callback shown by that instance.
+4. One Google Web application client can list both the Supabase callback and Tovu's callback when both systems are used. Keep both exact URIs in Google; do not substitute one for the other.
+5. In Supabase **Authentication → URL Configuration**, configure the app's own allowed return URL. The Google-to-Supabase callback and the Supabase-to-app return URL serve different steps.
+6. Test through the app's existing Supabase sign-in flow. These instructions do not automatically associate Supabase users with Tovu members or replace the app's session system. See [Supabase's Google setup](https://supabase.com/docs/guides/auth/social-sign-in/auth-google).
+
+## Troubleshooting without exposing secrets
+
+- `redirect_uri_mismatch`: compare the exact configured callback with Google's authorized list, including scheme, port and base path.
+- Missing Tovu button: check plugin activation, the saved Client ID/Secret card and configured canonical address. Do not switch to Workspace credentials.
+- Browser/state failure: restart from `/signin` in the same browser; do not forward an authorization URL, bypass binding, weaken validation or add issuer aliases.
+- Google access denied: check Audience restrictions and the selected account; request only identity permissions. Never copy callback query strings, codes, state, verifier, tokens, claims or upstream error bodies into chat or logs. Report fixed outcome codes only.
+
+## Embed the sign-in button on a public page
+
+Use the existing `content_read.plugin` export contract for `tovu/google-login` → `sign-in-button`.
+The plugin must be enabled and its Google client configured. `host-unavailable` means finish
+setup first; `props-required` means the host is configured and the author must choose a variant.
+The required `variant` is `light`, `dark`, or `neutral`; no template defaults or logic are added.
+Use the marker owner to serialize config; do not construct a second JSON attribute escaper.
+
+```html
+<div data-embed-config='{"type":"plugin","plugin":"tovu/google-login","component":"sign-in-button","version":1,"props":{"variant":"light"}}'>
+  <p>Google sign-in is currently unavailable.</p>
+</div>
+```
+
+Keep a useful authored fallback. Disabled/unconfigured plugins render that fallback without a
+button. Static exports always render the fallback, while bundling the stylesheet and mark.
+The action is a native link to the host's same-origin start route; Tab focuses it and Enter
+starts sign-in, including with JavaScript off. Do not replace the host link or add OAuth JavaScript.
+The Interactive editor uses a protected card; Preview and the published page render the real UI.
+The card's availability is a page-load snapshot; reload after changing plugin/client setup.
+
+Theme hooks are `.plugin-google-login-sign-in-button`, its `__mark` and `__label` parts,
+and its `--light`, `--dark`, `--neutral` variant classes. Defaults live in `@layer plugin-exports`,
+so ordinary theme CSS wins. Set inherited custom properties on the authored wrapper or a theme:
+`--plugin-signin-bg`, `--plugin-signin-fg`, `--plugin-signin-border`, `--plugin-signin-radius`,
+`--plugin-signin-height`, `--plugin-signin-padding`, `--plugin-signin-gap`, `--plugin-signin-font`,
+`--plugin-signin-font-size`, `--plugin-signin-font-weight`, `--plugin-signin-line-height`,
+`--plugin-signin-letter-spacing`, `--plugin-signin-hover-shadow`, `--plugin-signin-active-shadow`,
+`--plugin-signin-focus-color`, `--plugin-signin-focus-width`, `--plugin-signin-focus-offset`.
+
+Keep Google's fixed sign-in wording, approved palette, spacing, visible focus, and full-color G.
+Do not stretch, recolor, filter or replace the mark. The mark stays on white in all variants.
+Prefer Google Sans Medium when the host theme supplies it; the offline fallback is Arial.
+Check the current [Google branding rules](https://developers.google.com/identity/branding-guidelines)
+before visual acceptance. The unchanged gradient SVG is bundled from
+[SVGL](https://github.com/pheralb/svgl/blob/main/static/library/google.svg)
+(Git blob `8ab1351b939a780aa05645d31e5bed3fcf5c5493`); Google's trademarks remain Google's.

package/google-login/tovu-login-providers.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "providers": [
+    {
+      "id": "google",
+      "label": "Google",
+      "issuer": "https://accounts.google.com",
+      "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
+      "tokenEndpoint": "https://oauth2.googleapis.com/token",
+      "jwksUri": "https://www.googleapis.com/oauth2/v3/certs",
+      "scopes": ["openid", "email", "profile"],
+      "signingAlgorithm": "RS256",
+      "clientAuthentication": "client_secret_post",
+      "pkce": "S256",
+      "credentialLabel": "google-login/google OAuth client",
+      "credentialCardTarget": "google-login-oauth-client",
+      "authoritativeEmailDomains": ["gmail.com", "googlemail.com"],
+      "hostedDomainClaim": "hd"
+    }
+  ]
+}

package/google-workspace/README.md

@@ -0,0 +1,132 @@
+# Google Workspace plugin (`google-workspace`)
+
+## Purpose
+
+One bundled Agent Plugin for everything Google: the Google sign-in and every Google product as a
+module. v1 ships Sheets. All Google-specific code (endpoints, scopes, request formats, response
+parsing, revocation, later the Picker) lives here; host core and Jini core name no provider. It ships
+as `@jini-ai/agent-plugins/google-workspace` (this folder, `packages/agent-plugins/google-workspace`).
+A host that selects it stages the payload into its bundled-source root and seeds it **disabled**;
+the bundled-digest ledger records its digest at seed time, which the executable trust gate checks
+before any module loads. Host-specific chat guidance (exact tool names, admin paths, the OAuth
+callback route) lives in the host's overlay for this plugin, not here.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `plugin.json`, `mcp.json` | Manifest (no MCP servers). |
+| `tovu-connections.json` | The sign-in (the `tovu-*.json` files are the Tovu host's contribution contracts; their names and keys are frozen): Google endpoints, per-client-kind parameters, Picker start params and the `picked_file_ids` callback field, and the NAMES of the host config holding the client ids (`TOVU_GOOGLE_WORKSPACE_OAUTH_{WEB,DESKTOP}_CLIENT_{ID,SECRET}`, placeholders until the Cloud project exists). `byoClient: true` lets a workspace admin use their own OAuth client instead (saved as the custom credential `google-workspace/account OAuth client`; see `skills/google-workspace/references/connection.md`). |
+| `products.json` | Product catalog: id, label, tool prefix (every tool named with it belongs to the product and is gated by it; a security pin enumerates them), required scopes. Sheets = `drive.file` only. |
+| `tovu-agent-tools.json` + `tools/` | Executable tools (the host adds its own prefix to each name): `account_info`, and the Sheets tools in `tools/sheets/` (see its README). |
+| `tovu-admin-surfaces.json` + `ui/` | Plugin-owned admin surfaces: the connection panel, Choose spreadsheet (Picker) and Form destinations, each with a server-side `handlerModule`. See `ui/README.md`. |
+| `tovu-form-destinations.json` + `form-destinations/` | Push-only `google-sheets` destination (no `receive`): frozen column mapping, bounded submission-id dedupe, contract-shaped results. See `form-destinations/README.md`. Not yet called by the host's forms fan-out (wired in a later lot). |
+| `lib/` | Shared code (below). |
+| `skills/google-workspace/` | What the in-app assistant reads. |
+| `__tests__/` | Plugin-local `node:test` suites (not shipped): `fake-google-http.mjs` (127.0.0.1 fake Google), the OAuth contract pins and the skill-content pins. |
+
+## `lib/` public API
+
+| Module | Exports |
+|---|---|
+| `auth.mjs` | Default `{ createHooks({ http }) }`: Jini's `ApiConnectionHooks` (`resolveScopes`, `readAccount`, `revoke`). `GOOGLE_REVOCATION_ENDPOINT`, `GOOGLE_ACCOUNT_ACCESS_PAGE`. |
+| `http.mjs` | `createGoogleClient({ http, connections }, { sleep, random }).request({ connectionRef, url, method, query, body, kind })`; `accessTokenFor`; `buildUrl`; `pathSegment` (one encoded path segment, dot segments refused). |
+| `drive-files.mjs` | `readAccount({ client, connectionRef })` via Drive `about.get` (works under `drive.file`); `copyFile({ client, connectionRef, fileId, name }, { parentId })` via Drive `files.copy`. |
+| `sheets-client.mjs` | The one Sheets client: `sheetsClientFor({ capabilities })` (Sheets product gate per request), `googleClientFor` (ungated: delivery), `sendSheetsRequest`, `assertSpreadsheetId` / `SPREADSHEET_ID_PATTERN` (the one id rule, also every schema's pattern), `sheetsUrl` (the one URL builder; checks the id), `getSpreadsheet`, `runBatchUpdate` (inventory check first), `valueInputOption` (RAW default), `SHEETS_LIMITS` and the bounds (`boundValueRanges`, `assertPayloadWithin`, `outputFits` / `assertOutputWithin`, `spreadsheetFields` (grid-data masks need the opt-in)), `resourceLines` (card lines), `spreadsheetLine`, `tabsOf`. |
+| `sheets-a1.mjs` | A1 helpers, one name and contract each: `columnName`, `columnIndex`, `parseA1Range` (Google's normalized range → parts or undefined), `parseBoundsA1` (a plain `A1:B2` → bounds, else `invalid-input`), `tabRange` (tab-title quoting), `gridRangeLabel` (card label). |
+| `product-state.mjs` | `PRODUCTS` (validated catalog), `scopesFor({ productIds })`, and the product gate: `PRODUCT_STATE_KEY` (`'products'`), `isProductEnabled({ state, productId })`, `assertProductEnabled(...)` (`product-disabled`); form delivery uses `isProductEnabled` over the read-only plugin-state reader the host passes as `optional.state`. A product is off unless the plugin's settings hold `products: { <id>: true }`. |
+| `picker-selection.mjs` | `verifySelectedSpreadsheet({ client, connectionRef, fileId, expectedAccountId })` (plain Drive id, same account, spreadsheet MIME via Drive `files.get`, real access via Sheets `spreadsheets.get`; metadata only), `verifySpreadsheetAccess({ client, connectionRef, fileId })` (live spreadsheet per Drive, then opened by the Sheets API; shared with `sheets_open_existing`), `parsePickedFileIds({ value })` (desktop callback field → one id or null on cancel), `DESKTOP_PICKER_START_PARAMS`, `SPREADSHEET_MIME_TYPE`. |
+| `surface-actions.mjs` | For the admin-surface handlers: `CONNECTION_ID` (`'account'`), `surfaceSheetsClient({ capabilities })` (the one Sheets client over the surface port, which names connections by id), `surfaceAccount`, `sheetsUnavailableReason`, `withSurfaceFailures` (plugin/host refusals → surface-safe failures), `surfaceRefusal`. |
+| `picker-flow.mjs` | `createPickerFlow({}, { now, randomId })` → `bootstrap` (hosted session + short-lived token, or `system-browser` / `unavailable`), `verifyHosted`, `startSystemBrowser`, `finishSystemBrowser`; `readPickedSpreadsheets`, `rememberPickedSpreadsheet`, `PICKER_CONFIG_NAMES`, `PICKER_SESSION_TTL_MS`. |
+| `form-destination-settings.mjs` | `readFormDestinations({ deliveryBindings })`, `saveFormDestination({ deliveryBindings, formSlug, destination }, { bindingId })`, `SHEETS_ADAPTER_ID`, `FORM_SLUG_PATTERN`, `MAX_FORM_DESTINATIONS`. |
+| `request-policy.mjs` | `GoogleWorkspaceError`, `classifyFailure`, `parseRetryAfter`, `backoffMs`, `shouldRetryInline`. |
+
+## Rules the plugin keeps
+
+- Tokens come only from the host capability, right before each request; only access tokens ever
+  reach the plugin, and none is returned, logged or put in an error.
+- Errors carry a fixed message per code, never Google's text (it echoes ranges and values).
+- `kind: 'write'` (append, create, copy) with an unknown outcome is `uncertain-outcome` and never
+  retried; reads and idempotent writes retry with jittered backoff that honours Retry-After.
+- Revocation is confirmed only by Google's 200 (or `invalid_token`: already revoked); a failed
+  revoke throws `provider-unreachable` or `provider-refused` for the host to record.
+- An access token can expire in flight: a 401 gets one more token read and is retried only if the
+  token differs. An unchanged token or second 401 is `reconnect-required`. Tools and form delivery share this.
+- The budgets declared in `tovu-connections.json` (45/min per account, 240/min per instance) are
+  charged by the host on every token read; its refusal (`rate-limited`) becomes `quota-delay` with
+  the host's `retryAfterMs` and `outcome: 'not-applied'`, and follows the same inline backoff rules
+  as Google's 429 (nothing was sent, so even an append may wait and retry).
+- Modules import nothing outside this directory except what the host injects.
+
+## How it fits
+
+The host reads each contribution file and runs it on Jini's services: `tovu-connections.json` on
+`@jini-ai/integrations/api-connections`; `tovu-agent-tools.json` on
+`@jini-ai/agent-plugins/lifecycle/tools`; `tovu-admin-surfaces.json` on
+`@jini-ai/agent-plugins/admin-surfaces`; `tovu-form-destinations.json` through the host's form
+destination registry. In Tovu those readers are `features/api-connections/contribution.ts`,
+`features/agent-plugins/executable-tools`, `features/agent-plugins/admin-surfaces` and
+`features/form-destinations/registry.ts`.
+
+## Extension points
+
+A new product adds an entry to `products.json` (its scopes), its tools to `tovu-agent-tools.json`
+under its own prefix, and its modules under `products/<id>/`, all on the same sign-in.
+
+## Known gaps
+
+- Duplicate submission ids found in a tab are delivered as `ok` with a "review" note in
+  `reference`, which the forms ledger drops; the contract has no reviewable success outcome, so
+  no person sees it yet (Jini contract change needed for a distinct outcome).
+- Form-delivery retry window: product-off (`adapter-unavailable`) and quota (`rate-limited`)
+  refusals are retried within the site's forms retry policy (about 8 attempts over about a day),
+  then the job fails; authorization failures (`authorization-required`) fail at once and stay as
+  failed jobs, with no automatic re-send after a reconnect. Owner decision pending on longer holds
+  (for example a `paused` outcome resumed by turning the product on or reconnecting).
+
+- Products are read from the plugin's settings and default to OFF; the connection panel writes them,
+  and the host hands form delivery the same settings (read-only) as `optional.state`.
+- The Form destinations panel saves each form's choice as the form's delivery binding through the
+  host's `deliveryBindings` capability (both the destination and connection surfaces declare
+  `deliveryAdapters: ["google-sheets"]`): one binding per form slug, on this plugin's `account`
+  connection, config = spreadsheet, tab (numeric sheet id), the frozen `accountId`, plus the names the
+  panels show. The host writes it to `core.forms/deliveryBindings` as the signed-in admin.
+- Panels (G13b) are built and unit-tested only; they need a Chrome check (hosted Picker inside the
+  sandboxed frame, desktop system-browser Picker, the account-page button). The host says whether it
+  is hosted or desktop (`context.hostKind`); a hosted site also needs both
+  `TOVU_GOOGLE_PICKER_BROWSER_KEY` and `TOVU_GOOGLE_PICKER_APP_ID` (placeholders, never real values)
+  or the Picker is `picker-not-configured`. The panels cannot open links themselves (no
+  `allow-popups`): the connection panel declares `linkOrigins: ["https://myaccount.google.com"]` and
+  asks the admin page to open the Google account-access page (`client.openLink`); the address also
+  stays visible as text.
+- Quotas: the per-account (45/min) and per-instance (240/min) budgets declared in
+  `tovu-connections.json` are implemented by the host and charged on every token read; there is no
+  plugin-side limiter. Form delivery reads a token per Google request (`credential.getAccessToken`),
+  so it is charged per request like the tools.
+- Hosted Picker sessions are kept one per surface (`picker-session:<surfaceId>`), not per tab or
+  admin: opening the same panel in a second tab (or by a second admin) starts a new session and
+  the first tab's pick is refused as `picker-expired`. Documented in
+  `skills/google-workspace/references/troubleshooting.md`; not changed (a pick only needs one
+  open panel).
+
+## Sheets admin tools (`tools/sheets-admin/`, lot G12)
+
+Eleven tools for tabs, sorting, filters, filter views, formatting, named and protected ranges,
+developer metadata, raw batch updates, CSV export and opening a picked file; see
+`tools/sheets-admin/README.md`. Their helpers:
+
+| Module | Exports |
+|---|---|
+| `lib/sheets-admin-request-kinds.mjs` | `REQUEST_KINDS` (the reviewed batchUpdate inventory: effect, replay class, required fields), `checkRequests`, `describeRequests`, batch bounds. |
+| `lib/sheets-admin-csv.mjs` | `planChunks`, `encodeCsv`, export bounds. |
+
+These tools use the plugin-side codes `invalid-input` and `limit-exceeded` (shared with the values
+tools) and add `unsupported-request`; `sheets_open_existing` reuses the Picker's `not-a-spreadsheet`, plus an optional plugin-composed `detail`
+on `GoogleWorkspaceError` (a request index or kind name, never Google's text or a cell value).
+
+
+Hosted sign-in asks for consent when Jini has no renewable credential stored (`forceConsentParams`),
+so connecting another workspace can obtain offline access. Renewable same-account reconnects keep
+incremental grants without forcing consent. Client settings now use the full plugin namespace,
+`TOVU_GOOGLE_WORKSPACE_OAUTH_{WEB,DESKTOP}_CLIENT_{ID,SECRET}`. Provision these settings
+before enabling this build; the earlier abbreviated names were never configured, so no fallback is needed.

package/google-workspace/form-destinations/README.md

@@ -0,0 +1,87 @@
+# `form-destinations/` — the Google Sheets form destination
+
+**Purpose.** Push each accepted form submission into a Google Sheets tab as one row, at least once,
+with best-effort dedupe. Declared in `../tovu-form-destinations.json` as `google-sheets` (push only,
+no `receive`), part of the Sheets product (`../products.json`).
+
+## Public API
+
+`sheets.mjs` default export: `deliver(required, optional)`, the forms delivery contract's push
+method (see the forms-multidest delivery contract, §2–§3).
+
+- `required`: `{ kit, credential, form, submission, binding, idempotencyKey }` exactly as the host
+  hands a frozen job. `credential.token` is the access token the host resolved for this attempt
+  from `binding.connectionRef`; it is used only in the `authorization` header.
+- `optional`: `{ state? }` — the host's read-only reader of this plugin's settings (the store the
+  connection panel writes). Unless it holds `products.sheets === true` (no reader counts as off),
+  delivery refuses as `adapter-unavailable`, retryable: while Sheets is off a job is retried within
+  the forms retry policy (about 8 attempts over about a day), then marked failed; no reader never enables delivery.
+- `credential.getAccessToken()` (OAuth connections): one fresh token per Google request, so the
+  host's declared budgets count every request and the frozen account is re-checked each time.
+- Returns a `FormDeliveryResult`; it never throws.
+
+Binding config (non-secret, frozen with the job):
+
+```json
+{ "spreadsheetId": "…", "accountId": "…", "tabs": { "<formSlug>": { "sheetId": 7 } } }
+```
+
+`accountId` is read by the host, not this module: the OAuth connection port refuses a job whose
+connection now holds another account (`authorization-required`), and a binding without one
+(`configuration-invalid`).
+
+Which column holds which field is kept in the sheet, not the binding: the first time a field is
+written, its column gets a developer-metadata marker (`tovu_form_field` = the field id, visibility
+`DOCUMENT`, attached to that one column). The marker decides the column from then on, so a label
+edited in the form, a header renamed in the sheet, or columns inserted or moved before it keep the
+field's data in one column (Google moves column metadata with the column). An untagged field is
+matched by its label in row 1 and tagged, or gets a new column at the end (header = label, else
+field id). Chosen over the binding because the adapter cannot write the host's binding, and over a
+header note because people neither see nor edit metadata. Growing the grid, writing new headers
+(as text cells) and tagging columns happen in ONE atomic `batchUpdate` before the append.
+
+More than one row already holding the submission id (another writer, or a late append racing the
+scan) is reported as delivered with the reference `sheet <id> rows <a>, <b> (duplicate submission
+id: review)`; nothing is appended again. Nobody sees that note today: the forms delivery contract has no reviewable success outcome and the ledger keeps only `ok` (the
+reference is dropped), and any `ok: false` code would fail or re-try a row that is already
+there. A distinct outcome needs a contract change in Jini (`@jini-ai/cms/forms`).
+
+## Files
+
+| file | job |
+|---|---|
+| `sheets.mjs` | One attempt: product check → tab by sheet id → header row + column markers → dedupe scan → one atomic column batch (grid, headers, markers) → RAW append → re-scan after a lost answer. |
+| `mapping.mjs` | Field id ↔ marker / header ↔ column (`buildMapping`, `readMarkers`, `planColumns`); mapping errors; the RAW row (checkbox groups joined `", "`). |
+| `dedupe.mjs` | Scans the `_tovu_submission_id` column in 5,000-row chunks; > 50,000 data rows → `destination-limit`. |
+| `delivery-result.mjs` | The contract's result shape and the plugin-error → contract-code table. |
+
+## How it fits
+
+All HTTP goes through `../lib/sheets-client.mjs` → `../lib/http.mjs` (the one Google client:
+retries, Retry-After, safe errors; quotas are the host's budgets). The host's `kit.fetch(url, init, { timeoutMs })` is
+the transport. The forms ledger (outbox) owns attempts, backoff and terminal state; this module
+only reports one attempt's outcome.
+
+Not exactly-once: there are no row reservations, and a late append or another writer can race the
+scan. Two bindings writing to the same tab share the id column, so the second sees the first's row
+as already delivered.
+
+## Extension points
+
+A second destination (another product or another provider plugin) copies this shape: a
+push-only descriptor, a `deliver` that maps its own errors to the nine contract codes, and its own
+dedupe. Nothing here is imported by a host's core or Jini core.
+
+## Wiring (G14b) and what is left
+
+Wired: the host composes the OAuth connection port ahead of saved custom credentials, so a binding
+whose `connectionRef` is this plugin's connection resolves through it (`additionalHosts` = the
+declared `apiOrigins` after the first, as exact origins); delivery gets `optional.state` and a
+per-request `getAccessToken()`.
+
+Bindings (G14c): the destination panel saves each form's choice as its binding through the host's
+admin-surface `deliveryBindings` capability (`../lib/form-destination-settings.mjs`). The binding names
+the form by slug (the host stores the form's row id) and the `account` connection by id (the host
+stores its own ref); an admin clicking Save on the panel is the human action. A binding whose plugin
+is disabled is not delivered (`adapter-unavailable`, retryable: the host reads only active plugins'
+adapters on every attempt), the same code as Sheets turned off here.

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

@@ -0,0 +1,43 @@
+/**
+ * @file Best-effort dedupe for the Google Sheets form destination: finds the rows whose
+ * `_tovu_submission_id` cell holds a submission id, by reading that one column in bounded chunks.
+ *
+ * Exists because a retry (a lost answer, a replayed job) must not add the same submission twice,
+ * and Google's append has no idempotency key. The delivery scans before every append and again
+ * after an append whose outcome is unknown. The scan covers every row of the tab's grid, so
+ * "not found" is a complete answer; a tab with more than {@link DEDUPE_LIMITS.maxScannedRows} data
+ * rows is refused as `destination-limit` rather than appended to on an incomplete search.
+ *
+ * This is NOT exactly-once: a late append or another writer can still race the scan, and there
+ * are no row reservations. Delivery is at-least-once with best-effort dedupe (documented in
+ * `references/form-delivery.md`).
+ */
+import { DeliveryRefusal } from './delivery-result.mjs';
+
+export const DEDUPE_LIMITS = Object.freeze({ maxScannedRows: 50_000, chunkRows: 5_000 });
+
+/** Row numbers (1-based) in `[from, to]` of a chunk whose cell equals the id. @complexity O(rows). */
+function matchesIn(values, from, submissionId) {
+  return values.flatMap((row, offset) => (String(row?.[0] ?? '').trim() === submissionId ? [from + offset] : []));
+}
+
+/**
+ * Every data row (row 2 onwards) whose id cell equals `submissionId`, in sheet order.
+ * @param {{ readColumn: (input: { from: number, to: number }) => Promise<readonly (readonly unknown[])[]>, rowCount: number, submissionId: string }} required
+ *   `readColumn` returns the id column's rows `from..to` (rows-major; Google omits trailing blanks).
+ *   `rowCount` is the tab's grid row count, header included.
+ * @returns {Promise<number[]>}
+ * @throws {DeliveryRefusal} `destination-limit` (not retryable) when the tab has more data rows
+ *   than the scan ceiling; nothing is read then.
+ * @complexity O(rowCount / chunkRows) reads, O(rowCount) cells, each read ≤ chunkRows cells.
+ */
+export async function findSubmissionRows(required, _optional = {}) {
+  const { readColumn, rowCount, submissionId } = required;
+  if (rowCount - 1 > DEDUPE_LIMITS.maxScannedRows) throw new DeliveryRefusal({ code: 'destination-limit', retryable: false });
+  const found = [];
+  for (let from = 2; from <= rowCount; from += DEDUPE_LIMITS.chunkRows) {
+    const to = Math.min(rowCount, from + DEDUPE_LIMITS.chunkRows - 1);
+    found.push(...matchesIn(await readColumn({ from, to }), from, submissionId));
+  }
+  return found;
+}

package/google-workspace/form-destinations/delivery-result.mjs

@@ -0,0 +1,69 @@
+/**
+ * @file What the Google Sheets form destination reports back to the forms delivery ledger: the
+ * contract's `FormDeliveryResult` and the translation from the plugin's safe Google errors to the
+ * contract's nine codes.
+ *
+ * Exists because only the bare code, `retryable`, `retryAfterMs` and `outcome` ever reach the
+ * ledger (the host drops everything else, and a thrown error would become a generic retryable
+ * failure). So every failure of a delivery is turned into one of those values here, in one table,
+ * and no message, Google text, token or answer ever leaves the adapter. What the person does next
+ * for each code is documented in `skills/google-workspace/references/form-delivery.md`.
+ */
+import { GoogleWorkspaceError } from '../lib/request-policy.mjs';
+
+const DELIVERY_FAILED = 'delivery-failed';
+
+/** A refusal decided by the adapter itself (config, mapping, dedupe limit, product off). */
+export class DeliveryRefusal extends Error {
+  /**
+   * @param {{ code: string, retryable: boolean }} required A contract code; `message` is the code.
+   * @param {{ outcome?: 'not-applied' | 'unknown' }} [optional] Defaults to `not-applied`: every
+   *   adapter refusal happens before the append is sent, except the uncertain-append verdict.
+   */
+  constructor(required, optional = {}) {
+    super(required.code);
+    this.name = 'DeliveryRefusal';
+    this.code = required.code;
+    this.retryable = required.retryable;
+    this.outcome = optional.outcome ?? 'not-applied';
+  }
+}
+
+/**
+ * Plugin safe code → [contract code, retryable]. Authorization problems are not retried: the job
+ * fails at once and stays in the ledger as failed (it is not re-sent after a reconnect). Quota,
+ * product-off and transient failures are retried within the forms retry policy (about 8 attempts
+ * over about a day), then the job fails.
+ */
+const CONTRACT_CODES = new Map([
+  ['not-connected', ['authorization-required', false]], ['reconnect-required', ['authorization-required', false]],
+  ['account-changed', ['authorization-required', false]], ['missing-permission', ['authorization-required', false]],
+  ['file-not-granted', ['resource-not-granted', false]], ['access-denied', ['resource-not-granted', false]],
+  ['admin-policy', ['resource-not-granted', false]],
+  ['quota-delay', ['rate-limited', true]],
+  ['invalid-request', ['mapping-invalid', false]], ['invalid-input', ['configuration-invalid', false]],
+  ['limit-exceeded', ['destination-limit', false]],
+  ['uncertain-outcome', ['outcome-unknown', true]],
+  ['product-disabled', ['adapter-unavailable', true]],
+  ['conflict', [DELIVERY_FAILED, true]], ['service-unavailable', [DELIVERY_FAILED, true]], ['network-error', [DELIVERY_FAILED, true]],
+]);
+
+/** `{ ok: false, error }` with only the fields the contract keeps. @complexity O(1). */
+export function failureResult(required, _optional = {}) {
+  const { code, retryable, outcome, retryAfterMs } = required;
+  return { ok: false, error: { code, retryable, ...(outcome ? { outcome } : {}), ...(retryAfterMs === undefined ? {} : { retryAfterMs }) } };
+}
+
+/**
+ * The result a failed delivery reports. A plugin error keeps its outcome and Retry-After; anything
+ * unrecognised is a retryable `delivery-failed` with no outcome claimed, and its text is dropped.
+ * @param {{ error: unknown }} required
+ * @complexity O(1).
+ */
+export function resultForError(required, _optional = {}) {
+  const { error } = required;
+  if (error instanceof DeliveryRefusal) return failureResult(error);
+  if (!(error instanceof GoogleWorkspaceError)) return failureResult({ code: DELIVERY_FAILED, retryable: true });
+  const [code, retryable] = CONTRACT_CODES.get(error.code) ?? [DELIVERY_FAILED, false];
+  return failureResult({ code, retryable, outcome: error.outcome, retryAfterMs: error.retryAfterMs });
+}

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

@@ -0,0 +1,152 @@
+/**
+ * @file Column mapping for the Google Sheets form destination: which column each form field is
+ * written to, which new columns a delivery adds, and the row of RAW values one submission becomes.
+ *
+ * Exists so a spreadsheet's columns never silently change meaning. Fields are identified by their
+ * stable field id (`name`); the label is only the header text. The first time the plugin writes a field
+ * to a column it tags that column with a developer-metadata marker (`tovu_form_field` = field id,
+ * attached to the column itself). From then on the marker decides the column: a label edited in
+ * the form, a header renamed in the sheet, or columns inserted or moved before it do not move the
+ * field's data (Google moves column metadata with its column). Why a marker in the sheet and not
+ * the binding: the delivery adapter cannot write the host's binding, and a marker needs no state
+ * outside the spreadsheet it describes; unlike a header note, people do not see or edit it.
+ * An untagged field is matched by its label in row 1 (and tagged), else added as a new column at
+ * the end. A tab that should have the plugin's columns but lacks them, a header found twice, a field
+ * tagged on two columns, or two entries landing on one column is a mapping error the person
+ * repairs; nothing is appended into a sheet whose columns cannot be matched. The visitor's IP is
+ * never a field, and answers that are not fields of the frozen form are never written.
+ */
+import { DeliveryRefusal } from './delivery-result.mjs';
+
+// These names keep their `tovu` prefix: deliveries have already written them into people's
+// spreadsheets, and a renamed header or marker key would no longer match those columns.
+export const SUBMISSION_ID_HEADER = '_tovu_submission_id';
+export const SUBMITTED_AT_HEADER = '_tovu_submitted_at';
+/** Developer-metadata key tagging a column with the form field id it holds. */
+export const FIELD_MARKER_KEY = 'tovu_form_field';
+
+const mappingInvalid = () => new DeliveryRefusal({ code: 'mapping-invalid', retryable: false });
+
+/** One answer as a RAW cell: a checkbox group is joined with ", "; scalars keep their type. @complexity O(items). */
+export function cellValue(required, _optional = {}) {
+  const { value } = required;
+  if (value === undefined || value === null) return '';
+  if (Array.isArray(value)) return value.map((item) => String(item)).join(', ');
+  return typeof value === 'number' || typeof value === 'boolean' ? value : String(value);
+}
+
+/**
+ * The mapping for one job: the two plugin columns, then one entry per field of the frozen form.
+ * @param {{ form: { fields: readonly { name: string, label?: string }[] } }} required
+ * @returns {{ header: string, field?: string, source?: 'id' | 'submittedAt' }[]}
+ * @throws {DeliveryRefusal} `mapping-invalid` when two entries would share a header.
+ * @complexity O(fields).
+ */
+export function buildMapping(required, _optional = {}) {
+  const entries = [
+    { header: SUBMISSION_ID_HEADER, source: 'id' },
+    { header: SUBMITTED_AT_HEADER, source: 'submittedAt' },
+    // Trimmed like the sheet's cells are, so stray spaces never decide a match; a blank label falls back to the id.
+    ...required.form.fields.map((field) => ({ field: field.name, header: String(field.label ?? '').trim() || field.name })),
+  ];
+  if (new Set(entries.map((entry) => entry.header)).size !== entries.length) throw mappingInvalid();
+  return entries;
+}
+
+/** Whether a dimension range is exactly one column of this tab. @complexity O(1). */
+const isOneColumnOf = (range, sheetId) => range?.sheetId === sheetId && range.dimension === 'COLUMNS' && range.endIndex - range.startIndex === 1;
+
+/** One column marker as `{ field, index }`; anything not exactly one column of this tab is ignored. @complexity O(1). */
+function columnMarker(metadata, sheetId) {
+  const range = metadata?.location?.dimensionRange;
+  const isMarker = metadata?.metadataKey === FIELD_MARKER_KEY && typeof metadata.metadataValue === 'string';
+  return isMarker && isOneColumnOf(range, sheetId) ? { field: metadata.metadataValue, index: range.startIndex } : undefined;
+}
+
+/**
+ * Field id → the columns tagged with it, from a `developerMetadata:search` answer.
+ * @param {{ matches: readonly unknown[], sheetId: number }} required `matchedDeveloperMetadata`.
+ * @returns {Map<string, number[]>}
+ * @complexity O(matches).
+ */
+export function readMarkers(required, _optional = {}) {
+  const markers = new Map();
+  for (const match of required.matches) {
+    const marker = columnMarker(match?.developerMetadata, required.sheetId);
+    if (marker) markers.set(marker.field, [...(markers.get(marker.field) ?? []), marker.index]);
+  }
+  return markers;
+}
+
+const headerText = (cell) => String(cell ?? '').trim();
+
+/** Untagged columns of row 1 whose header is `header`. @complexity O(width). */
+function headerPositions(plan, header) {
+  return plan.headerRow.flatMap((cell, index) => (headerText(cell) === header && !plan.tagged.has(index) ? [index] : []));
+}
+
+/** A new column at the end, headed `header`. @complexity O(1). */
+function addColumn(plan, header) {
+  const index = plan.width;
+  plan.width += 1;
+  plan.newHeaders.push({ index, header });
+  return index;
+}
+
+/** A plugin column (`_tovu_*` header): found once by its fixed header, or new on a fresh tab. @complexity O(width). */
+function tovuColumn(plan, entry) {
+  const positions = headerPositions(plan, entry.header);
+  if (positions.length === 1) return positions[0];
+  if (positions.length > 1 || !plan.fresh) throw mappingInvalid();
+  return addColumn(plan, entry.header);
+}
+
+/** A field's column: its marker, else its header found once, else a new column; untagged ones get tagged. @complexity O(width). */
+function fieldColumn(plan, entry, taggedAt) {
+  if (taggedAt.length > 1) throw mappingInvalid();
+  if (taggedAt.length === 1) return taggedAt[0];
+  const positions = headerPositions(plan, entry.header);
+  if (positions.length > 1) throw mappingInvalid();
+  const index = positions.length === 1 ? positions[0] : addColumn(plan, entry.header);
+  plan.untagged.push({ field: entry.field, index });
+  return index;
+}
+
+/**
+ * Where each mapping entry is written. An empty first row is a fresh tab. The plugin's two columns are
+ * found by their fixed headers (refused when missing from a tab that is not fresh); each field by
+ * its marker, else by its label (see the file comment).
+ * @param {{ mapping: readonly { header: string, field?: string, source?: string }[], headerRow: readonly unknown[], markers: ReadonlyMap<string, readonly number[]> }} required
+ * @returns {{ columns: number[], newHeaders: { index: number, header: string }[], untagged: { field: string, index: number }[], width: number }}
+ *   `newHeaders` are contiguous at the end; `untagged` are the field columns to tag.
+ * @throws {DeliveryRefusal} `mapping-invalid` for a duplicated, missing or conflicting column.
+ * @complexity O(entries * width).
+ */
+export function planColumns(required, _optional = {}) {
+  const { mapping, markers } = required;
+  const fresh = required.headerRow.every((cell) => headerText(cell) === '');
+  const tagged = new Set([...markers.values()].flat());
+  const headerRow = fresh ? [] : required.headerRow;
+  const plan = { fresh, tagged, headerRow, width: Math.max(headerRow.length, ...[...tagged].map((index) => index + 1)), newHeaders: [], untagged: [] };
+  const columns = mapping.map((entry) => (entry.source ? tovuColumn(plan, entry) : fieldColumn(plan, entry, markers.get(entry.field) ?? [])));
+  if (new Set(columns).size !== columns.length) throw mappingInvalid();
+  return { columns, newHeaders: plan.newHeaders, untagged: plan.untagged, width: plan.width };
+}
+
+/**
+ * The appended row: each mapped value at its column, blanks elsewhere (columns of removed fields
+ * or someone else's columns stay empty for this row).
+ * @param {{ mapping: readonly { field?: string, source?: 'id' | 'submittedAt' }[], columns: readonly number[], width: number, submission: { id: string, submittedAt: string, answers: Readonly<Record<string, unknown>> } }} required
+ * @complexity O(width + entries).
+ */
+export function buildRow(required, _optional = {}) {
+  const { mapping, columns, submission } = required;
+  const row = Array.from({ length: required.width }, () => '');
+  const valueFor = (entry) => {
+    if (entry.source) return submission[entry.source];
+    // Own keys only: a field id such as `constructor` must not read the prototype.
+    return cellValue({ value: Object.hasOwn(submission.answers, entry.field) ? submission.answers[entry.field] : undefined });
+  };
+  mapping.forEach((entry, index) => { row[columns[index]] = valueFor(entry); });
+  return row;
+}