@joe-broadhead/opencode-gws 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 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.5] - 2026-11-05
+
+### Added
+
+- `gws_catalog` finds the usual method for natural phrasings such as "search email", "find file by name", "read document" or "trash file" (which now lists `drive.files.update` before the permanent `drive.files.delete`). When no entry matches every word, it returns the entries that match the most, with `relaxed: true`. When a query or `service` names a service this setup leaves out, `unavailable` lists it with the reason, such as Keep's domain-wide delegation.
+- Status names a skill of your own that uses one of the plugin's skill ids (for example `~/.claude/skills/opencode-gws`), which hides the plugin's skill: the status RPC's new `shadowedSkills`, a **Hidden skills** row in `/gws-status` and the dialog, and a next step to move or rename it.
+
+### Changed
+
+- The `default` account no longer enables `admin-reports` or Model Armor, and no access level requests `cloud-platform`: the default consent asks for 42 scopes (35 for Read-only). Only a Workspace admin with the Reports privilege can call `admin-reports`; add a separate account alias for that admin ([docs/admin.md](https://github.com/joe-broadhead/opencode-gws/blob/HEAD/docs/admin.md)). No Model Armor helper could run.
+- `gmail.send`, `gmail.reply`, `gmail.reply-all` and `gmail.forward` with `draft: true` plan as `write`, commit with `gws_write`, and list no recipients, because a draft reaches no one. `gmail.users.drafts.send` stays a `send`, with the recipient rules.
+- A change sent to `gws_read`, or a read sent to `gws_plan`, is now `CATEGORY_MISMATCH` with a next step that names the right tool, not `POLICY_DENIED`. `POLICY_DENIED` now means only a deny. Committing with the wrong tool names the plan's tool too: `Commit it with gws_send, passing only {planId}.`
+- `ADMIN_PRIVILEGE_REQUIRED`'s next step, in errors and `/gws-doctor`, says to add a separate account alias for an admin and sign in to it. Before, it said to sign in again, which would replace this account's own sign-in.
+- The unguarded-agent next step is one fixed sentence: "Put the default rules shown by /gws-status first in each listed agent's own permissions, in opencode.json or the agent's Markdown file, followed by your top-level rules for Google Workspace tools." The **Agents without default rules** row lists names, then the rules, with no extra sentence.
+- `gws_status` and the tools RPC's `status` report the count as `unguardedAgentCount` (it was `unguardedAgents`, a number). `unguardedAgents` is always the list of names, as in the status RPC.
+- The status RPC's `state` loses `host_untested`. An untested OpenCode release inside `>=2.2.3 <2.3.0` keeps the working state (`connected`, `sign_in_required` or `not_configured`); `host.tested` and the OpenCode row still mark it. Outside the range the plugin still refuses to start with `HOST_UNTESTED`, whose next step now reads the same everywhere.
+- The `gws` namespace tells the model to use these tools, never a `gws` command in a shell, and names the two skills. Both skills are rewritten to load on everyday requests (mail, calendar, Drive, Docs, Sheets, the standup report) and to teach upcoming-event times, Drive search and trash, reading a Doc's text, drafts, paging and exact counts.
+- `HELPER_UNSUPPORTED` reads `'<id>' cannot run in this plugin`, and `GWS_API_ERROR`'s next step says to tell the user Google's message.
+
+### Removed
+
+- The `opencode-gws-admin` skill. Its lessons (the admin gate, Reports, the workflow helpers) are in `opencode-gws` and `opencode-gws-recipes`.
+- The options `skills.include` and `skills.exclude` (use `skills.enabled`), `execution.schemaTimeoutMs` and `execution.pageDelayMs` (now fixed at 15 seconds and 100 ms; a read can still set `pagination.delayMs`), and `audit.sink` (audit records always go to `audit.path`). A config that still sets one is refused with `OPTIONS_INVALID`: delete the key.
+- The error codes `GWS_NOT_FOUND` and `GWS_UNSUPPORTED_PLATFORM`, which nothing raised; a missing binary is `GWS_UNAVAILABLE`.
+- `views/jelly-view.d.ts` from the repository; the view's types come with `@jelly/contracts`.
+
+### Fixed
+
+- `gws_read`'s description says a read returns one page unless `pagination` is set, that a text helper returns a string, and how to get a cut result in full; the pagination fields name their defaults.
+
+## [0.0.4] - 2026-11-04
+
+### Added
+
+- Jelly shows the plugin's one-line summary ("Gmail, Calendar, Drive, Docs and Sheets.") and its icon, a neutral envelope over a page (`assets/icon.svg`, now in the package). A Jelly release that does not know these two fields refuses the declaration, so this version needs a Jelly that accepts them.
+- In Jelly, a web tab can sign in to Google Workspace through Jelly's sign-in relay: the `google` sign-in declares `relay` with the `redirectUri` and `callbackPort` fields the plugin already takes. Nothing changes without Jelly.
+
+### Fixed
+
+- Planning `gmail.users.drafts.send` for a draft that cannot be read, or that names no recipient, now sets `recipientsUnknown` in the preview ("the draft could not be read or names no recipient"), so a recipient rule refuses it with `RECIPIENTS_UNKNOWN`. Before, such a plan could show no recipients and no reason.
+
 ## [0.0.3] - 2026-11-04
 
 ### Fixed

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, 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`.
+- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3, 2.2.4 and 2.2.5. Another release in that range works as usual, and status marks it 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.
 
@@ -20,7 +20,7 @@ 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 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)).
+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)). Admin reports, which need a Workspace admin, and Model Armor, which cannot run, are left out too. 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
 
@@ -30,9 +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 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>`)**.
+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 42 scopes (35 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.
+To update, run `opencode plugin update @joe-broadhead/opencode-gws`, then `opencode reload`. An entry pinned to a version (`@joe-broadhead/opencode-gws@<version>`) 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).
 
@@ -70,7 +70,7 @@ A later rule wins. Your own allow rule, or **Always** on a write or export, remo
 { "action": "gws.write", "resource": "work:*", "effect": "allow" }
 ```
 
-An agent defined only in your config does not get the ask rules. `/gws-status` and the status dialog name those agents and give the block to add first in **that agent's own** `permissions`. Do not put it in the top-level `permissions`: that would loosen Explore.
+An agent defined only in your config does not get the ask rules. `/gws-status` and the status dialog name those agents and show the default rules. Put them first in each listed agent's own `permissions`, in `opencode.json` or the agent's Markdown file, followed by your top-level rules for Google Workspace tools. Do not put them in the top-level `permissions`: that would loosen Explore.
 
 ## Configure
 
@@ -105,15 +105,17 @@ 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>`. |
-| `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`. |
+| `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: add a separate account alias for an admin who has it and sign in to that, 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, 2.2.4 or 2.2.5, or another 2.2.x release, or set `"allowUntestedHost": true`. |
+| `HOST_UNTESTED` | The plugin does not start. Use OpenCode 2.2.3 or a later 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. |
 
+A skill of your own named `opencode-gws` or `opencode-gws-recipes` (for example in `~/.claude/skills`) hides the plugin's skill of that name; `/gws-status` names it under **Hidden skills**, and the fix is to move or rename it.
+
 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).

package/assets/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48"><rect width="48" height="48" rx="12" fill="#52606D"/><path d="M21 9h15a2 2 0 0 1 2 2v17a2 2 0 0 1-2 2H21a2 2 0 0 1-2-2V11a2 2 0 0 1 2-2z" fill="#CBD2D9"/><path d="M23.5 14h10M23.5 18.5h10" fill="none" stroke="#52606D" stroke-width="2.4" stroke-linecap="round"/><rect x="9" y="20" width="22" height="17" rx="2.5" fill="#FFFFFF"/><path d="M12 23.5l8 6 8-6" fill="none" stroke="#52606D" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/></svg>