opencode-reviewer 0.6.1 → 0.8.0

package/README.md

@@ -1,13 +1,15 @@
-# OpenCode reviewer
+# OpenCode Reviewer
 
 Reviews pending permissions in the OpenCode sidebar using a separate LLM. Covers
 shell commands, file edits, MCP calls, custom tools, and external-directory access.
-Supports streaming explanations, optional one-time auto-approval, and
-reviewer-aware Linux desktop notifications with distinct sounds.
+Supports streaming explanations, saved report history, auto-approval, and Linux
+desktop notifications with distinct sounds.
 
-Requires OpenCode 1.18.35 on Linux.
+![](./assets/recording.gif)
 
-## Install
+Requires OpenCode 1.18.35 or newer on Linux.
+
+## Install and config
 
 Add this entry to `~/.config/opencode/tui.json` or `.opencode/tui.json`.
 OpenCode installs the [npm package](https://www.npmjs.com/package/opencode-reviewer).
@@ -35,8 +37,18 @@ OpenCode installs the [npm package](https://www.npmjs.com/package/opencode-revie
         "autoApproveDelaySeconds": 15,
         "notify": true,
         "notifySound": true,
+        "staleReminderSeconds": 60,
+        "notifications": {
+          "attention": { "banner": true, "sound": true },
+          "unsafe": { "banner": true, "sound": true },
+          "question": { "banner": true, "sound": true },
+          "approved": { "banner": true, "sound": true },
+          "error": { "banner": true, "sound": true },
+          "ended": { "banner": true, "sound": true }
+        },
         "notificationSoundDirectory": "/absolute/path/to/notification-sounds",
         "formatRetries": 1,
+        "maxOutputTokens": 2048,
         "timeoutMs": 30000,
         "maxFiles": 6,
         "maxEvidenceBytes": 131072
@@ -47,7 +59,7 @@ OpenCode installs the [npm package](https://www.npmjs.com/package/opencode-revie
 ```
 
 Only `baseURL` and `model` are required. Use any OpenAI-compatible Chat Completions
-endpoint; `/chat/completions` is appended to the base URL. Choose a model available
+endpoint: `/chat/completions` is appended to the base URL. Choose a model available
 at that endpoint.
 
 Replace `apiKey`, or remove it and set the variable named by `apiKeyEnv` before
@@ -59,7 +71,7 @@ The remaining values above are the defaults. Restart OpenCode after changing
 configuration. Reviews run when OpenCode asks for permission, so set the relevant
 rules to `ask` in `opencode.json`. Existing `allow` rules skip review.
 
-## Options
+## Options reference
 
 | Option | Behavior |
 | --- | --- |
@@ -69,38 +81,50 @@ rules to `ask` in `opencode.json`. Existing `allow` rules skip review.
 | `reviewMcp` | Review identifiable MCP tool and resource permissions. |
 | `reviewCustomTools` | Review permissions requested by registered custom tools. |
 | `reviewExternalDirectories` | Review directory access independently of the other switches. Directory approval can resume the operation without another prompt. |
-| `autoApprove` | Allow completed Safe reviews once after the visible countdown. |
+| `autoApprove` | Allow completed Safe reviews once after their countdown, including behind report history. |
 | `extraCareful` | Include the extra-careful prompt in auto-mode reviews. Defaults to `true`; set `false` to omit it. |
 | `autoApproveDelaySeconds` | Countdown duration, 0–3600 seconds. |
 | `notify` | Linux desktop notifications and sounds. Defaults to `true`; set `false` to disable both. |
 | `notifySound` | Play notification sounds. Defaults to `true`; set `false` to keep banners silent. |
-| `notificationSoundDirectory` | Absolute custom sound directory. Use `attention`, `approved`, `error`, and `ended` basenames with `.wav` or `.mp3`; WAV takes precedence. Missing or unusable files fall back to bundled sounds. |
+| `staleReminderSeconds` | Repeat pending human-interaction notifications every 60 seconds by default. Nonnegative safe integer seconds; `0` disables reminders. Only the front-of-queue blocker per conversation repeats. |
+| `notifications` | Per-type `banner` and `sound` booleans for `attention`, `unsafe`, `question`, `approved`, `error`, and `ended`. Omitted types and fields default to `true`. |
+| `notificationSoundDirectory` | Absolute custom sound directory. Use any of the six notification type names as basenames with `.wav` or `.mp3`; WAV takes precedence. Missing or unusable files fall back to that type's bundled sound. |
 | `formatRetries` | Additional attempts to correct malformed assessment JSON, 0–100. |
+| `maxOutputTokens` | Provider output-token limit, sent as `max_tokens`. Defaults to 2,048; accepts positive safe integers within your provider/model's supported range. Retries keep the same limit. |
 | `timeoutMs` | Total review deadline, 1–3,600,000 ms. |
 | `maxFiles` | File limit per review, 1–1,000. |
 | `maxEvidenceBytes` | Evidence limit, 1–16,777,216 bytes. Whole files or diffs may be omitted; oversized mandatory arguments fail review. |
 | `instructions` | Absolute directory containing overrides for the [prompt templates](https://github.com/mightykatun/opencode-reviewer/tree/main/prompts). Missing templates use the built-ins. |
 
-## Usage
+My LLMs insist on writing a bunch of useless text to my README, so I collapsed them here in case anyone wants to inflict themselves (or more likely their agent) the pain of reading it.
 
+<details>
+<summary>Usage</summary>
 The sidebar shows Safe, Unsafe, or Analysis unavailable. Explanations support
 Markdown and scrolling. If the sidebar is hidden, use OpenCode's Show sidebar
 command.
 
 With streaming enabled, Evaluating and its spinner disappear when a rating arrives.
-The rating remains provisional until the full response is validated. A format retry
+The rating remains provisional until the full response is validated. A retry
 clears the preview and restores the loading indicator. Auto-approval
 starts only after the full response is validated and rendered.
 
-Transient connection failures and HTTP 408/429/500/502/503/504 responses get up to
-two internal retries within `timeoutMs`, honoring server cooldowns. A stream that
-has already delivered assessment text is not restarted. This is separate from
-`formatRetries`; no additional setting is needed. Retried requests can incur
-additional provider charges, and unreported usage remains unknown.
+Transient connection failures, HTTP 408/429/500/502/503/504 responses, and rejected
+assessment streams share up to two internal retries within `timeoutMs`, honoring
+server cooldowns. Stream protocol failures and output-token truncation regenerate
+the report from a fresh, identical request; previous previews are cleared and never
+joined to the next response. Socket failures after text starts, provider error/refusal
+events, tool calls, invalid JSON/UTF-8, incomplete SSE framing and resource-limit
+failures remain terminal. This recovery is separate from `formatRetries`.
+If token-limit errors persist, increase `maxOutputTokens` within your model's limits.
+Providers enforce this limit and may include reasoning tokens; the plugin's byte
+limits and overall timeout still apply. Retried requests can incur additional
+provider charges, and unreported usage remains unknown.
 
 During an auto-approval countdown, click the countdown to allow once immediately,
 or Cancel to leave the request manual. Hiding or covering the panel also cancels
-that request's countdown. Cancel before using native Allow always or rejection
+that request's countdown, except when covered by this plugin's report history.
+Cancel before using native Allow always or rejection
 forms; those forms alone do not stop the countdown.
 Positive countdowns hold their configured starting number for one extra second
 before counting down. A zero-second setting still approves without that hold.
@@ -110,35 +134,103 @@ descendants. The setting is saved for resume. Both commands are also in the comm
 palette. Disabling stops current reviews and countdowns while native permission
 controls remain available.
 
+### Report history
+
+Use `/reviewer-history` or **Reviewer: Report history** in the command palette to
+open the newest saved report for the current conversation and its descendants.
+Left/Right or the arrow buttons select older/newer entries; Up/Down and
+PageUp/PageDown scroll. Close or Escape closes history. Repeating the command
+returns to the newest report. History remains available with review disabled or
+invalid reviewer configuration, and does not force a hidden sidebar open.
+
+Each entry shows the original report, available usage, model, provider and outcome:
+**Auto approved**, **Manually approved**, **Cancelled**, or **Rejected**. Cancelled
+records a linked interruption or removed request after automation was cancelled;
+it does not prove that the tool never ran. Ambiguous outcomes are omitted, including
+native Allow once replies whose submitting client cannot be identified. History
+keeps the latest completed report, which can differ from the report that caused
+approval in another window.
+
+History can cover an ongoing review without stopping its countdown. A newly
+completed Safe review can also start its countdown beneath history after its full
+report is rendered. Native dialogs, including the command palette, still cancel an
+active countdown; opening history afterward cannot restart it. Browsing saved
+reports never approves a request or replays notifications.
+
+Reports are saved only after a qualifying permission resolution. Saved reports
+can contain private text and are retained in OpenCode's local state directory
+until their conversation is deleted. Deleting a root removes its descendants'
+details; deletion missed while OpenCode was closed is reconciled when that host
+scope is visited again. Windows using the same state directory share this history,
+partitioned by host directory and root conversation. Uncommitted reports can be
+lost on shutdown or prolonged storage failure.
+
+### Usage totals
+
 Token and cost totals appear below completed reports when available. Open
-Reviewer: Lifetime usage in the command palette for cumulative totals. OpenRouter
+**Reviewer: Statistics** in the command palette for **Lifetime** and **Conversation**
+views. Use Tab or click a scope to switch. The dialog opens on Lifetime;
+Conversation uses the session selected when opened, resolving its root and all
+descendants, including subagents, within the current host-directory scope.
+Opening from a descendant shows the same combined conversation totals.
+OpenRouter
 costs use reported charges; other endpoints use available catalog estimates.
 Received usage counts even if a review fails or is interrupted. Unreported charges
 are missing from the totals.
 
-Lifetime statistics also show **Safe** and **Unsafe** review counts. Each completed,
-validated review counts once, even without usage data. Previews, retries and failed
-or interrupted analyses do not count. Re-enabling a conversation can produce a new
-review, which counts again. The totals persist across restarts; earlier ratings
-were not recorded and cannot be reconstructed.
+Both views show completed reviews, retries, tokens, cost, Safe/Unsafe
+percentages, confirmed auto-approvals, and average time to a rating and full report.
+Percentages use recorded completed reviews as their denominator. Each validated
+review counts once, even without usage data; a fresh review after re-enabling counts
+again. Retries count extra API attempts actually dispatched, including format
+corrections and transport recovery. Manual approvals are not auto-approvals.
+Timings run from evaluation start, including evidence and retries, to the accepted
+attempt's first rating and final validated response, excluding rendering/countdown
+time. Non-streaming reviews use the final response time for both measurements.
+Averages use running means and sample counts; stored review details also retain
+their individual timings. Both scopes persist in the existing history database
+across restart/resume. Conversation totals keep independent roots separate;
+Lifetime combines activity across conversations and host directories using the
+same state directory. Browsing and switching views do not add usage.
+
+Older retained history can provide a **partial** conversation baseline. Previously
+deleted details and usage predating history tracking cannot be attributed or
+reconstructed from legacy lifetime aggregates. This limitation is labeled in the
+dialog. Once recorded in conversation totals, deleting report details does not
+reduce those totals or Lifetime. Storage failures show unavailable, not zero.
+
+Tokens describe received provider usage, not just the visible explanation. One
+report may sum several reviewer POSTs, including format corrections and transport
+retries with received usage. Each POST can resend the prompt and evidence;
+corrections also include the failed response and feedback. Cached input remains
+part of the provider's input-token count. Lifetime and Conversation also retain
+received usage from unsuccessful or interrupted reviews, which do not count as
+completed reviews. Averages include measured reviews only.
 
 Reviews send the pending request, latest user prompt, project context, and relevant
 file snapshots, diffs, or tool arguments to your endpoint before approval. Shell
 file snapshots can follow symlinks outside the project. Missing evidence is noted
 in the report; ratings are advice based on the supplied evidence.
+</details>
 
-### Desktop notifications
-
+<details>
+<summary>Desktop notifications</summary>
 Transient banners have an **Opencode (Session name)** heading and a small status icon: green
-checkmark for approvals, orange exclamation mark for attention, red X
+checkmark for approvals, orange exclamation mark for attention, red exclamation mark
+for Unsafe reviews, purple question mark for questions, red X
 for errors, and a neutral code mark for completed responses. GNOME controls the
 heading's font weight. The event message appears beneath it, even while the
 terminal is focused:
 
-- **Session needs attention:** questions and manual permissions. Reviewed requests
-  wait for a final validated assessment; failures, canceled automation, and a Safe
-  review blocked from starting its countdown also notify. Unreviewed requests
-  notify immediately, including when conversation review is disabled.
+- **Session needs attention:** manual permissions. Reviewed requests
+  stay silent during identification, report generation and retries. Final Safe
+  reports notify when auto-approval is disabled or canceled, or after failed approval
+  is confirmed to remain pending. Waiting for rendering, queue position or an
+  automatic countdown to start does not trigger attention. Disabled/unsupported
+  reviews and terminal analysis failures can notify without a report.
+- **Unsafe permission needs human approval:** a completed, validated Unsafe review,
+  with its own sound. Provisional streamed ratings never notify.
+- **Agent has a question:** a pending agent question, with its own sound.
 - **Reviewer approved a permission:** sent with the approval sound after confirmed
   automatic approval, for both positive and zero delays. The countdown is silent.
   Approval sounds are limited to
@@ -147,8 +239,42 @@ terminal is focused:
 - **Session ended:** a completed root-agent response, not a question/permission
   pause or an explicit user interruption.
 
+Permission attention and Unsafe notifications, including their reminders, apply
+only to the current native permission blocker in each visited root conversation.
+Requests queued behind it stay silent and are re-evaluated from their current
+review/approval state when they become actionable. A sequence that proceeds
+through automatic approval stays free of attention notifications. Losing the
+actionable position, restarting analysis or entering automatic approval cancels
+pending attention delivery and reminders.
+
+Each type's `banner` and `sound` can be controlled independently. For example,
+`notifications.approved.banner: false` keeps approval sounds without banners;
+`notifications.question.sound: false` keeps question banners silent. Set both to
+`false` to disable that type. `notify: false` overrides all types and disables
+reminders too; `notifySound: false` silences all types and their reminders.
+Sound-only delivery does not require a desktop banner or delivery acknowledgement.
+Invalid notification settings disable notification work without disabling reviews.
+
+Pending permissions and questions repeat after `staleReminderSeconds`, measured
+from initial dispatch, even if desktop delivery fails. Reminders replace their
+previous banner and append **(Reminder)** to the event text, reusing the same
+sound, icon, session heading and click target. Only the native front-of-queue
+interaction per root conversation repeats: permissions precede questions, with
+the host's session/request ordering. Queued interactions wait; when the blocker
+changes, its replacement waits a full interval. Independent visited conversations
+can each remind. The supported host presents input for roots and direct children;
+deeper descendants cannot become a native root-input permission notification or
+reminder target. Their questions can still receive initial question notifications.
+
+Answering/dismissing a question in OpenCode, resolving a permission, deleting its
+session or closing the plugin stops its reminders. Closing/clicking a desktop
+banner, activating the terminal or viewing a conversation does not. Countdown
+and approval submission remain silent. Approval, error and completed-response
+notifications never repeat. Setting `staleReminderSeconds: 0` disables all reminders.
+
 Notifications cover conversations visited in this terminal and their descendants.
-Existing pending requests at startup/resume are not replayed. Clicking can select
+Existing pending requests at startup/resume are not replayed or reminded, but still
+participate in queue ordering. Clicking can select
 the originating GNOME Terminal tab and root conversation. Native input prompts
 cover root/direct-child requests in the supported host. Open dialogs are
 left intact; other terminals still receive banners and sounds. Desktop policies
@@ -159,7 +285,7 @@ the banner heading remains Opencode.
 
 Linux delivery uses `notify-send`, `stdbuf`, and `gdbus`; audio uses `paplay` or `pw-play`.
 On Ubuntu, `libnotify-bin`, `coreutils`, `libglib2.0-bin`, and `pulseaudio-utils` provide these
-utilities. The MP3 decoder and four default sounds are bundled; FFmpeg is not
+utilities. The MP3 decoder and six default sounds are bundled; FFmpeg is not
 required. MP3 and mono/stereo PCM/float WAV files up to 4 MiB and 10 seconds are
 normalized toward -20 dBFS RMS with a -3 dBFS peak ceiling before playback.
 Custom sounds are loaded on first use; restart after replacing them.
@@ -168,6 +294,7 @@ with a low-latency buffer; preparation never blocks permission approval.
 `stdbuf` makes delivery acknowledgements immediate instead of waiting for
 `notify-send` to flush its output when the banner closes.
 Disable overlapping notification plugins to avoid duplicate alerts.
+</details>
 
 ## Development
 

package/THIRD_PARTY_NOTICES.md

@@ -29,7 +29,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 # Bundled audio decoder and supplied sounds
 
-The four notification MP3 files were supplied by the maintainer with explicit
+The six notification MP3 files were supplied by the maintainer with
 permission to redistribute them with this plugin. Their original bytes are
 embedded in the bundle. Normalization occurs during playback preparation.