@joe-broadhead/opencode-gws 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.3] - 2026-11-04
+
+### Fixed
+
+- Policy recipient rules no longer fail open. `allowedRecipientDomains`, `allowedRecipients`, `deniedRecipientDomains` and `allowExternalRecipients` now read every address in `to`, `cc` and `bcc`: comma- and semicolon-separated strings, `Name <address>`, quoted names and groups. They read the `To`, `Cc` and `Bcc` headers of a raw `gmail.users.messages.send`, and before the plan they read who a reply, reply-all, `gmail.users.drafts.send`, a notifying event change or a Drive permission update reaches. Calendar ACL scopes (by address, domain or rule id), Gmail delegates and forwarding addresses, Drive domain shares and the other share methods are read too. When a matching rule limits recipients and the plugin cannot tell who a send or share reaches, the plan is refused with the new code `RECIPIENTS_UNKNOWN`. A plan whose recipients were read is checked again at commit, and expires if someone was added.
+- A Calendar event write that emails its guests through the deprecated `sendNotifications: true`, or a `sendUpdates` value other than `none`, is now a `send`, so it asks every time and never offers Always. Before, only `sendUpdates` `all` and `externalOnly` were sends, and `sendNotifications` committed as a `write`.
+- `allowExternalRecipients: false` now compares each recipient with the account's own domain, not with the first recipient, so a send only to outside addresses is refused. The domain is the new `accounts.<alias>.domains` option, or the signed-in address's domain, read with Gmail, Drive or Calendar; when neither is known the plan is refused with the new code `ACCOUNT_DOMAIN_UNKNOWN`.
+- An operation that is not a download no longer reports gws's `{"saved_file":"download.html",…}` when Google answers with an empty body, as a Drive delete does: the result is empty (`""`), and no file is left in the plugin's work folder. Each gws call without staged files now runs in its own private folder, removed afterwards. A read whose body is not JSON reports its `mimeType` and `bytes`, with a next step to save it through `download.path` and `gws_export`.
+- A plan's preview, and so the approval prompt and `/gws-status`, now names everyone a send or share reaches. A reply lists the sender (or `Reply-To`) of the message it answers, a reply-all every other participant except the account itself, a raw message its `To`, `Cc` and `Bcc`, and a draft, a notifying event change or a Drive permission update the recipients read for it. Before, a reply showed only its `cc` and `bcc`. When the plugin cannot tell who a send or share reaches, the preview says why in the new `recipientsUnknown` field.
+- `ADMIN_PRIVILEGE_REQUIRED` applies only to Admin SDK services (`admin-reports`, and any later `admin-*`). A Chat, Drive, Classroom or other refusal worded "not authorized to access" is now that service's own error (`GWS_API_ERROR`, or `AUTH_REQUIRED` for a 401), not a pointer to a Workspace admin account. Reads, plans, commits and `/gws-doctor` agree.
+- The package no longer ships `views/jelly-view.d.ts`: no type declarations ship (it stays in the repository for view authors), and the pack test refuses any `.d.ts`.
+- Committing a plan a second time says `PLAN_ALREADY_USED: This plan was already committed`, with the next step to create a new plan, until the plan's time limit passes. Before, creating any other plan removed the used one, and the second commit said `PLAN_NOT_FOUND: Run gws_plan first`.
+- Work folders (`$TMPDIR/opencode-gws-*`) left by a server that stopped without closing are removed at the next start, once they are a day old and the process that owned them is gone. A folder from an earlier version, which has no owner record, is removed after a week.
+- The audit log no longer grows without bound: `audit.jsonl` is capped at 5 MiB, and a write that would pass the cap first moves it to `audit.jsonl.1`, replacing the previous one.
+- The README's Uninstall now signs out first, while the plugin's sign-ins still exist, then removes the plugin, then names the state and cache folders to delete (`~/Library/Application Support/opencode-gws` and `~/Library/Caches/opencode-gws` on macOS, `~/.local/state/opencode-gws` and `~/.cache/opencode-gws` on Linux). Install says to run `opencode reload` and `/gws-status`, and a new paragraph explains updating.
+- `docs/scripting.md` says that `opencode api` calls run in the service's default location (your home directory), not the directory you run them in, and how to target a project; that `opencode api` exits with status 1 on an RPC error; and when a read's `data` is text rather than JSON.
+
+### Changed
+
+- The status RPC (`google-workspace.gws/status`) and `gws_status` use the field names every plugin shares. `pluginVersion` is now `version`; `hostVersion` and `hostWarning` are now `host: { version, range, tested }`; the new `state` is `connected`, `sign_in_required`, `not_configured` or `host_untested`; and `nextStep` is always present, `Nothing to do.` when nothing is needed (before, it was absent).
+- The tools RPC's envelope errors use the wording every plugin's tools RPC shares: `"extra" is not allowed`, `"sessionID" must be a non-empty string`, `"input" is missing`, `the envelope must be an object, such as …`, and `describe takes no input`, instead of zod's text such as `Unrecognized key: "extra"`. The next steps of `SESSION_UNKNOWN`, `SESSION_AGENT_REQUIRED` and `PERMISSION_DENIED` match the shared ones too.
+- OpenCode 2.2.5 is a tested host. Status calls only 2.2.3, 2.2.4 and 2.2.5 tested: another release inside `>=2.2.3 <2.3.0` starts as before, and now shows as host untested, with the supported range, in `/gws-status` and the dialog. `HOST_UNTESTED` says the range is supported, not tested.
+
+### Added
+
+- `accounts.<alias>.domains`: the account's own email domains, for `allowExternalRecipients`.
+- Helper flags from gws 0.22.5: `to` on `gmail.reply` and `gmail.reply-all` (extra To recipients), `remove` on `gmail.reply-all`, `cc`, `bcc`, `from`, `draft`, `attachments` and `noOriginalAttachments` on `gmail.forward`, and `format` on `gmail.triage`. Before, these were refused with `GWS_VALIDATION_ERROR`. A test now compares every adapter with the flags `gws <service> +<helper> --help` lists.
+
+## [0.0.2] - 2026-11-03
+
+### Fixed
+
+- The default sign-in no longer requests the Keep scopes, which Google grants only through domain-wide delegation, so Google no longer refuses the whole consent with `invalid_scope`. No access level requests `keep` or `keep.readonly`, and the `default` account no longer enables Keep: Read and write now requests 45 scopes and Read-only 37. `gws_catalog` and `gws_schema` mark the 7 Keep methods `restriction: "domain-wide-delegation"` (app-only methods keep `appOnly` and gain `restriction: "app-only"`), and the scope check refuses them with that reason. For an interactive account that enables `keep` without adding a Keep scope in `accounts.<alias>.scopes`, status carries `delegationRequired`, the sign-in form says Keep needs delegation, and `/gws-doctor` reports Keep `SKIPPED` with the reason. (#8)
+- A non-admin's Admin SDK refusal of a valid sign-in, such as the Reports API's 401 `Access denied. You are not authorized to read activity records.`, is now `ADMIN_PRIVILEGE_REQUIRED`, not `AUTH_REQUIRED`. Its next step is to sign in with a Workspace admin account that has the privilege (Reports for `admin-reports`) or to remove the service from `enabledServices`. Reads, plans, commits and `/gws-doctor` classify it the same way; it never marks the account as needing sign-in in status or `/connect`, and the doctor reports it as its own status, counted as needing attention. Token failures (`invalid_grant`, an expired or revoked token, `UNAUTHENTICATED`) stay `AUTH_REQUIRED`. (#9)
+- The tools RPC reports `SESSION_UNKNOWN` only when OpenCode says the session does not exist (`Session.NotFoundError`, or a 404). Any other failure to look the session up now propagates unchanged instead of being reported as an unknown session.
+
 ## [0.0.1] - 2026-11-03
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@ Unofficial; not affiliated with Google.
 
 ## Requirements
 
-- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3 and 2.2.4.
+- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3, 2.2.4 and 2.2.5. Another release in that range starts, and status shows it as host untested. Outside the range the plugin does not start, unless you set `allowUntestedHost`.
 - macOS (arm64, x64) or Linux (arm64, x64, glibc).
 - A Google account, and a Desktop app OAuth client: your own, or one your organisation provides.
 
@@ -16,9 +16,11 @@ Unofficial; not affiliated with Google.
 opencode plugin add @joe-broadhead/opencode-gws
 ```
 
+Run `opencode reload`, or restart OpenCode. Then run `/gws-status`.
+
 npm also installs the matching `@joe-broadhead/opencode-gws-bin-<target>` package, which holds the unmodified `gws` binary at the version the plugin pins ([details](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/backend.md)). Nothing downloads at runtime and there is no install script.
 
-With no options, the plugin creates one account, `default`, with every Workspace service it covers at Read and write, so one consent grants every scope it can use. Every change still needs a plan and your approval. To narrow it, set `accounts` ([configuration](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md#accounts)).
+With no options, the plugin creates one account, `default`, with every Workspace service a Google sign-in can use at Read and write, so one consent grants every scope it can use. Keep is left out: Google grants its scopes only through domain-wide delegation, which a Workspace admin sets up ([Keep](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#keep-needs-domain-wide-delegation)). Every change still needs a plan and your approval. To narrow it, set `accounts` ([configuration](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md#accounts)).
 
 ## Sign in
 
@@ -28,7 +30,9 @@ Run `/connect` and choose **Google Workspace**. The TUI shows the sign-in link:
 opencode auth login gws-default
 ```
 
-No Google OAuth client ships with the plugin. The first time, the form asks for the client ID and secret of your own Desktop app OAuth client, unless your organisation set one (see [Organisation rollout](#organisation-rollout)). To make one, follow [Create your Desktop client](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#create-your-desktop-client). The form lists the exact scopes before Google's consent screen. Read and write is the default for the `default` account and needs an acknowledgment; Read-only is the other choice. The default consent lists about 46 scopes, and an External client in Testing shows unverified-app warnings and expires refresh tokens after 7 days: see [What the default consent asks for](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#what-the-default-consent-asks-for). With several accounts, each `/connect` entry is named **Google Workspace (`<alias>`)**.
+No Google OAuth client ships with the plugin. The first time, the form asks for the client ID and secret of your own Desktop app OAuth client, unless your organisation set one (see [Organisation rollout](#organisation-rollout)). To make one, follow [Create your Desktop client](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#create-your-desktop-client). The form lists the exact scopes before Google's consent screen. Read and write is the default for the `default` account and needs an acknowledgment; Read-only is the other choice. The default consent lists 45 scopes (37 for Read-only), and an External client in Testing shows unverified-app warnings and expires refresh tokens after 7 days: see [What the default consent asks for](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md#what-the-default-consent-asks-for). With several accounts, each `/connect` entry is named **Google Workspace (`<alias>`)**.
+
+To update, run `opencode plugin update @joe-broadhead/opencode-gws`, then `opencode reload`. An entry pinned to a version (`@joe-broadhead/opencode-gws@0.0.2`) does not update: remove the `@version` from `plugins` first. Your options and sign-ins are kept.
 
 Details and the scope table: [docs/auth.md](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/auth.md).
 
@@ -101,22 +105,37 @@ Members then only run `/connect`, choose Google Workspace, and pick an access le
 | Code | What to do |
 | --- | --- |
 | `AUTH_REQUIRED` | Run `/connect` and choose Google Workspace, or run `opencode auth login gws-<alias>`. |
-| `AUTH_SCOPE_MISSING` | Sign in again, approve every scope Google lists, and choose Read and write. A method marked `appOnly` needs a Chat app's or Classroom add-on's own credentials and cannot run with a Google sign-in. Nothing ran. |
+| `ADMIN_PRIVILEGE_REQUIRED` | The sign-in is valid, but the account is not a Workspace admin with the privilege the API needs, such as Reports for `admin-reports`. Signing in again as the same account does not help: sign in with an admin account that has it, or remove the service from `enabledServices`. |
+| `AUTH_SCOPE_MISSING` | Sign in again, approve every scope Google lists, and choose Read and write. A method marked `appOnly` (`restriction: "app-only"`) needs a Chat app's or Classroom add-on's own credentials and cannot run with a Google sign-in. A Keep method (`restriction: "domain-wide-delegation"`) needs domain-wide delegation that a Workspace admin sets up. Nothing ran. |
 | `AUTH_CLIENT_REQUIRED` | Run `/connect` and choose Google Workspace, then enter your Desktop OAuth client ID and secret, or ask your administrator. |
 | `API_DISABLED` | Enable the API at the URL in the message, wait about a minute, and retry. `/gws-doctor` checks every service. |
-| `HOST_UNTESTED` | Use OpenCode 2.2.3 or a later 2.2.x, or set `"allowUntestedHost": true`. |
+| `HOST_UNTESTED` | Use OpenCode 2.2.3, 2.2.4 or 2.2.5, or another 2.2.x release, or set `"allowUntestedHost": true`. |
 | `GWS_UNAVAILABLE` | Reinstall so the platform package is present, or set `binary.path` to a `gws` executable of the pinned version ([details](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/backend.md)). |
 | `POLICY_DENIED` | A policy rule or the admin gate refused the call. A deny is final. |
+| `RECIPIENTS_UNKNOWN` | A recipient rule applies, and the plugin could not tell who the send or share reaches. |
+
+Each OpenCode server keeps a private work folder, `$TMPDIR/opencode-gws-XXXXXX`, and removes it when it stops. A server that stopped without closing leaves its folder behind; the next start removes such folders once they are a day old and their process is gone.
 
 `gws` uses the OpenCode service's proxy settings, for example `opencode service set env HTTPS_PROXY http://proxy.example:8080`. All codes: [Errors](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/configuration.md#errors).
 
 ## Uninstall
 
-```sh
-opencode plugin remove @joe-broadhead/opencode-gws
-```
+1. Sign out each account while the plugin is still installed: in `/connect`, or with `opencode auth logout gws-<alias>` (`gws-default` for the default account). After the plugin is removed, its sign-ins no longer appear.
+2. Remove the plugin:
+
+   ```sh
+   opencode plugin remove @joe-broadhead/opencode-gws
+   ```
+
+3. Delete its folders. The state folder holds the audit log (`audit.jsonl`, and `audit.jsonl.1` once it passes 5 MiB); the cache folder holds Google's API descriptions. Neither holds a credential.
+
+   | | macOS | Linux |
+   | --- | --- | --- |
+   | State | `~/Library/Application Support/opencode-gws` | `~/.local/state/opencode-gws` |
+   | Cache | `~/Library/Caches/opencode-gws` | `~/.cache/opencode-gws` |
 
-Then remove each Google Workspace sign-in in `/connect`, or with `opencode auth logout gws-<alias>`.
+   `$XDG_STATE_HOME/opencode-gws` and `$XDG_CACHE_HOME/opencode-gws` replace them when those variables are set, and `audit.path` names its own file.
+4. Remove any permission block you copied into an agent's own `permissions`.
 
 ## Links