@joe-broadhead/opencode-granola 0.0.0 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +56 -19
  3. package/dist/index.js +549 -151
  4. package/dist/tui.js +54 -28
  5. package/package.json +1 -1
  6. package/skills/granola/SKILL.md +5 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,73 @@
2
2
 
3
3
  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).
4
4
 
5
+ ## [0.0.2] - 2026-11-04
6
+
7
+ ### Added
8
+
9
+ - OpenCode 2.2.5 is a tested release, next to 2.2.3 and 2.2.4.
10
+ - The status RPC (`granola.meetings` `status`) has `version`, the plugin's version, and `host.range` and
11
+ `host.tested`. A status it cannot read is now the RPC error `unavailable` with `STATUS_UNAVAILABLE` and its next
12
+ step, and the `/granola` dialog says so.
13
+
14
+ ### Changed
15
+
16
+ - The status RPC uses the field names every plugin of this family shares. Scripts that read it need these changes:
17
+ - `next` is now `nextStep`;
18
+ - `pluginVersion` is now `version`;
19
+ - `hostVersion` is now `host.version`, which is `null` when OpenCode reports no version;
20
+ - `state` uses the shared states: `pending` is now `connecting`, `needs_auth` is now `sign_in_required`, `absent`
21
+ is now `not_configured`, and the user's own `granola` server for another URL is now `conflict` (it was that
22
+ server's connection state, next to `conflict`);
23
+ - `problem` no longer has `next`: the one next step is `nextStep`;
24
+ - `tools.visible` counts every Granola tool the model can call, unknown ones included.
25
+ - On a release inside `>=2.2.3 <2.3.0` other than 2.2.3, 2.2.4 and 2.2.5, Granola still sets everything up, and only
26
+ the `OpenCode` row calls the version untested. The row reads, for example,
27
+ `2.2.5 (tested; supported range >=2.2.3 <2.3.0), plugin <version>`. On a host outside the range that runs because
28
+ of `allowUntestedHost`, the next step, when nothing else is needed, says to use a tested release if Granola
29
+ misbehaves.
30
+ - Status always shows the `Agents without default rules` row, with `none` when no agent needs the fix. It lists an
31
+ agent only when its own rules would let a Granola tool this plugin does not know run without asking; an agent
32
+ whose rules already ask or deny for every Granola tool is not listed.
33
+ - The sign-in next step says to press `o` or Enter to open the sign-in page. A disabled server's next step offers
34
+ `/mcps` first. A missing server's next step points at an organisation policy (`mcp.use`) or another plugin that
35
+ removes it, not at the plugins list.
36
+ - The tools RPC's `describe` takes no input: anything but `{}` or nothing now gets `describe takes no input`. An
37
+ envelope that is not an object gets `the envelope must be an object, such as {…}`.
38
+ - A refused permission check now names the action that was refused, when it is not the method's own.
39
+
40
+ ### Fixed
41
+
42
+ - A failed connection's reason no longer ends in doubled punctuation, as in `…access the url?.`.
43
+ - The README's sign-in check quoted a status line that does not exist. It now says the `Connection` row shows
44
+ `connected` and the `Tools` row how many Granola tools are available.
45
+ - The README said Explore is left unchanged. Explore and Title also get the block; their own later deny rules still
46
+ keep Granola's tools out.
47
+ - The README's Uninstall now says why to sign out first: once the plugin is removed, `opencode mcp logout granola`
48
+ answers "MCP server not found" and the sign-in stays in OpenCode's credential store. It signs out, checks with
49
+ `opencode auth list`, then removes the plugin, reloads, and checks with `opencode mcp list`.
50
+ - The README now says what to do after `opencode plugin add` (run `opencode reload`, then `/granola-status`), how to
51
+ update the plugin, and, under Troubleshooting, that Granola's free plan returns only the last 30 days of meetings.
52
+ - `docs/scripting.md` said `opencode api` runs in the directory you call it from. It runs in the OpenCode service's
53
+ default location, your home directory; the doc now says how to target a project. It also says that `opencode api`
54
+ exits with status 1 for an RPC error, and that a result with only text has that text as its `output`.
55
+ - The `granola` skill now names the `folder_id` filter of `search_meetings` and `list_meetings`.
56
+ - A script's call that found Granola disconnected, while Granola reads connected again by the time the plugin looks,
57
+ now gets `CONNECTING` and "Retry in a few seconds.", as the model does. It got `CONNECTION_FAILED` and a reconnect
58
+ step before.
59
+
60
+ ## [0.0.1] - 2026-11-03
61
+
62
+ ### Added
63
+
64
+ - The tools RPC, `granola.meetings.tools`: a script can call Granola's ten read tools with no model, through
65
+ `opencode api`, as a session and its agent. It gets exactly the access that agent's model has: a tool its rules hide
66
+ is refused, OpenCode checks each call against the agent's and the session's rules, and an ask is refused at once
67
+ because no one is there to answer it. `describe` lists the methods with each tool's live input schema. Granola's
68
+ writes, `sign_out`, `export_markdown` and any tool Granola adds later are never methods. An account read records the
69
+ workspace for status, and a server that is not connected gets the same codes and next steps as for the model.
70
+ `docs/scripting.md` explains it.
71
+
5
72
  ## [0.0.0] - 2026-11-01
6
73
 
7
74
  ### Added
package/README.md CHANGED
@@ -7,7 +7,8 @@ Unofficial; not affiliated with Granola.
7
7
 
8
8
  ## Requirements
9
9
 
10
- - OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3 and 2.2.4. On another version the plugin refuses to start; see
10
+ - OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3, 2.2.4 and 2.2.5. Another release inside that range runs, and status
11
+ calls it untested. Outside the range the plugin does not start, unless you set `allowUntestedHost`; see
11
12
  [Troubleshooting](#troubleshooting).
12
13
  - macOS or Linux.
13
14
  - A Granola account. Granola's free plan includes the last 30 days of meeting history; transcripts and folders are
@@ -19,13 +20,19 @@ Unofficial; not affiliated with Granola.
19
20
  opencode plugin add @joe-broadhead/opencode-granola
20
21
  ```
21
22
 
22
- This adds the plugin to your global OpenCode config. Restart OpenCode afterwards.
23
+ This adds the plugin to your global OpenCode config. Run `opencode reload`, or restart OpenCode. Then run
24
+ `/granola-status`: it shows `sign-in required` until you sign in.
25
+
26
+ **Update** with `opencode plugin update @joe-broadhead/opencode-granola`, then run `opencode reload`. An entry pinned to
27
+ a version, such as `@joe-broadhead/opencode-granola@0.0.1`, does not update: remove the `@version` from its `plugins`
28
+ entry first.
23
29
 
24
30
  ## Sign in
25
31
 
26
32
  1. Run `/connect` and choose **Granola**, listed under MCP.
27
33
  2. Press `o` or Enter to open Granola's sign-in page in your browser, then approve there.
28
- 3. Run `/granola-status`. It shows `Granola: connected` and the number of Granola tools available.
34
+ 3. Run `/granola-status`. Its `Connection` row shows `connected`, and its `Tools` row shows how many Granola tools
35
+ are available.
29
36
 
30
37
  On the CLI, `opencode mcp auth granola` opens the sign-in page automatically. `/mcps` works too. There is
31
38
  nothing to configure first: Granola registers OpenCode's sign-in itself.
@@ -60,6 +67,19 @@ To see the connection, the workspace, the tools and the next step:
60
67
  The workspace name comes from the most recent Granola account read since OpenCode started, and is kept in memory
61
68
  only. Until then, status says the workspace is unknown; ask the agent to check your Granola account.
62
69
 
70
+ ### Scripts
71
+
72
+ A script or a cron job can call Granola's ten read tools with no model, through `opencode api`. It runs as a session
73
+ and its agent, under that agent's permission rules and the session's own. Writes, `sign_out` and `export_markdown` are
74
+ never available to scripts:
75
+
76
+ ```sh
77
+ opencode api post /api/rpc/granola.meetings.tools/list_meetings \
78
+ -d '{"input":{"sessionID":"ses_…","input":{"limit":10}}}'
79
+ ```
80
+
81
+ See [Scripting](https://github.com/joe-broadhead/opencode-granola/blob/HEAD/docs/scripting.md).
82
+
63
83
  ## Permissions
64
84
 
65
85
  | Kind | Tools | Default |
@@ -71,8 +91,9 @@ only. Until then, status says the workspace is unknown; ask the agent to check y
71
91
  | Hidden | `sign_out` | removed; use `opencode mcp logout granola` |
72
92
 
73
93
  The plugin inserts these rules into each agent, directly after the agent's base "allow everything" rule. Your own
74
- `permissions` and your saved "Always allow" answers override them, and a `deny` you configure always wins. Agents
75
- without the base rule, such as Explore, are left unchanged, and Plan keeps its restrictions.
94
+ `permissions` and your saved "Always allow" answers override them, and a `deny` you configure always wins. Explore
95
+ and Title also get the block, but their own later deny rules still keep Granola tools out, and Plan keeps its
96
+ restrictions. An agent without a base "allow everything" rule gets no rules.
76
97
 
77
98
  For example, to let one write run without asking:
78
99
 
@@ -86,7 +107,8 @@ For example, to let one write run without asking:
86
107
 
87
108
  Agents defined only in your own config are created after plugins start, so they miss the default rules, and Granola's
88
109
  writes would run there without asking. Status names each such agent and gives the block to paste first in that agent's
89
- own `permissions`. Do not put the block in the top-level `permissions`, which would loosen Explore.
110
+ own `permissions`. An agent whose own rules already ask or deny for every Granola tool needs nothing and is not named.
111
+ Do not put the block in the top-level `permissions`, which would loosen Explore.
90
112
 
91
113
  In `opencode run` and other runs where nobody can answer, a call that would ask is refused; reads still work.
92
114
 
@@ -119,26 +141,33 @@ Each member then signs in once with `/connect` → Granola. A managed `mcp.serve
119
141
 
120
142
  ## Troubleshooting
121
143
 
122
- Each connection state, as `/granola-status` shows it:
144
+ Run `/granola-status` (or `/granola` in the terminal UI) first. It shows the rows `Connection`, `Account`, `Access`,
145
+ `Export folder`, `Tools`, `Agents without default rules` (`none` when no agent needs the fix), `OpenCode` and exactly
146
+ one `Next step`. Each connection state:
123
147
 
124
148
  | Status | Code | What to do |
125
149
  | --- | --- | --- |
126
- | not configured | `NOT_REGISTERED` | Retry in a few seconds; if it persists, check that `plugins` in your OpenCode config lists the Granola plugin and that no `mcp.servers.granola` entry points elsewhere. |
150
+ | not configured | `NOT_REGISTERED` | Retry in a few seconds; if it persists, check that no organisation policy (`mcp.use`) or other plugin removes the `granola` server, then restart OpenCode. |
127
151
  | connecting | `CONNECTING` | Retry in a few seconds. |
128
- | sign-in required | `AUTH_REQUIRED` | Run `/connect` and choose Granola, or run `opencode mcp auth granola` in a terminal. |
152
+ | sign-in required | `AUTH_REQUIRED` | Run `/connect` and choose Granola, then press `o` or Enter to open the sign-in page. In a terminal, `opencode mcp auth granola` opens it automatically. |
129
153
  | failed | `CONNECTION_FAILED` | Reconnect Granola from `/mcps`, and if it keeps failing, run `/connect` and choose Granola to sign in again. |
130
- | disabled | `DISABLED` | Remove `disabled: true` from `mcp.servers.granola` in your OpenCode config. |
154
+ | disabled | `DISABLED` | Enable `granola` in `/mcps`, or remove `"disabled": true` from `mcp.servers.granola` in your OpenCode config. |
131
155
  | conflict | none | Remove `mcp.servers.granola` from your OpenCode config to use Granola's official server. |
156
+ | connected | none | Ready. The next step reads `Nothing to do.`, or names agents without default rules. |
132
157
 
133
158
  **`MCP server not found: granola` from `opencode mcp auth granola`, right after OpenCode starts.** Plugins are still
134
159
  loading for a few seconds. Run it again, or use `/connect`, which updates live.
135
160
 
161
+ **Older meetings are missing.** On Granola's free plan, Granola's server returns only the meetings of the last 30 days.
162
+
136
163
  **A tool says your Granola plan does not include it, or `TOOL_UNAVAILABLE`.** Granola's free plan has no
137
- transcripts or folders, and covers the last 30 days of meetings. Older meetings are not found.
164
+ transcripts or folders.
138
165
 
139
- **`HOST_UNTESTED`.** The plugin refuses to start on an OpenCode version outside `>=2.2.3 <2.3.0`, including
140
- development builds. Use a tested OpenCode version, or set the plugin option `allowUntestedHost: true` to run anyway;
141
- status then shows `host untested`.
166
+ **`HOST_UNTESTED`.** The plugin does not start on an OpenCode version outside `>=2.2.3 <2.3.0`, including
167
+ development builds. Use OpenCode `>=2.2.3 <2.3.0`, or set the plugin option `allowUntestedHost: true` to run anyway;
168
+ the `OpenCode` row then says `host untested`, and when nothing else is needed the next step says to use a tested
169
+ release if Granola misbehaves. A release inside the range other than 2.2.3, 2.2.4 and 2.2.5 runs normally: only the
170
+ `OpenCode` row calls it untested.
142
171
 
143
172
  **`OPTIONS_INVALID`.** A plugin option has an unknown name or a wrong type. The message names the option.
144
173
 
@@ -147,22 +176,30 @@ overwrites it. An entry for Granola's official URL is used as it is.
147
176
 
148
177
  **Status lists Agents without default rules.** See [Permissions](#permissions).
149
178
 
179
+ **A script gets an error.** The tools RPC has its own codes, listed in
180
+ [Scripting](https://github.com/joe-broadhead/opencode-granola/blob/HEAD/docs/scripting.md#errors).
181
+
150
182
  Granola uses the workspace that is active in your Granola app; meetings in other workspaces do not appear. The plugin
151
183
  supports one Granola account.
152
184
 
153
185
  ## Uninstall
154
186
 
155
- ```sh
156
- opencode mcp logout granola
157
- opencode plugin remove @joe-broadhead/opencode-granola
158
- ```
187
+ Sign out while the plugin is still installed: once it is removed, OpenCode no longer knows the `granola` server, so
188
+ it cannot remove its sign-in, and `opencode auth list` stops showing it.
189
+
190
+ 1. Sign out of Granola: `opencode mcp logout granola`.
191
+ 2. Check: `opencode auth list` no longer lists **Granola**.
192
+ 3. Remove the plugin: `opencode plugin remove @joe-broadhead/opencode-granola`, then `opencode reload`.
193
+ `opencode mcp list` no longer lists `granola`.
194
+ 4. Remove any Granola rules you copied into your agents' own `permissions`.
159
195
 
160
- Restart OpenCode afterwards. Files you exported stay in your export folder.
196
+ Files you exported stay in your export folder.
161
197
 
162
198
  ## Links
163
199
 
164
200
  - [Configuration](https://github.com/joe-broadhead/opencode-granola/blob/HEAD/docs/configuration.md)
165
201
  - [Architecture](https://github.com/joe-broadhead/opencode-granola/blob/HEAD/docs/architecture.md)
202
+ - [Scripting](https://github.com/joe-broadhead/opencode-granola/blob/HEAD/docs/scripting.md)
166
203
  - [Contributing](https://github.com/joe-broadhead/opencode-granola/blob/HEAD/CONTRIBUTING.md)
167
204
  - [Security](https://github.com/joe-broadhead/opencode-granola/blob/HEAD/SECURITY.md)
168
205
  - [Changelog](https://github.com/joe-broadhead/opencode-granola/blob/HEAD/CHANGELOG.md)