@raindrop-ai/opencode-plugin 0.1.4 → 0.3.0

package/README.md

@@ -54,10 +54,70 @@ then send its `event_id` to [`/v1/signals`](https://docs.raindrop.ai):
 }
 ```
 
+## OpenCode v2 plugin API
+
+OpenCode's newer plugin API (`@opencode/plugin`, `@opencode/sdk` v2) is served
+by the `@raindrop-ai/opencode-plugin/v2` subpath. Use it instead of the default
+export when running against the v2 plugin host:
+
+```jsonc
+// opencode.json
+{ "plugin": ["@raindrop-ai/opencode-plugin/v2"] }
+```
+
+```bash
+npm install @raindrop-ai/opencode-plugin @opencode/plugin
+```
+
+The v2 entry exposes the plugin object plus a `raindrop` handle
+(`users.identify`, `signals.track`, `currentEventId(sessionID)`, `flush`,
+`shutdown`). Configuration, event/tracing semantics, and payload bounds are the
+same as the v1 entry. `@opencode/plugin` and `@opencode/sdk` are optional peer
+dependencies — v1 users install neither.
+
+## Self-diagnostics
+
+The plugin can inject a `__raindrop_report` tool that lets the agent flag
+serious, unrecoverable problems for developer review. When the agent calls it,
+a `self diagnostics - <category>` signal is posted to `signals/track`, attached
+to the session's currently-open turn event. The tool is invisible to the end
+user — its output is a bare acknowledgement and the model is instructed never
+to mention it.
+
+Enable it via `raindrop.json` (`~/.config/opencode/raindrop.json` or
+`.opencode/raindrop.json`), or set `RAINDROP_SELF_DIAGNOSTICS=true` to override
+just the `enabled` flag:
+
+```json
+{
+  "self_diagnostics": { "enabled": true }
+}
+```
+
+For the v2 host API, pass the option directly:
+
+```ts
+import raindrop from "@raindrop-ai/opencode-plugin/v2";
+
+export default raindrop({ selfDiagnostics: { enabled: true } });
+```
+
+Optional `signals` (custom category → `{ description, sentiment? }` map),
+`guidance` (extra instructions appended to the tool prompt), and `tool_name` /
+`toolName` overrides are supported. The built-in categories are:
+
+- `missing_context` — blocked on information or access the user cannot provide
+- `repeatedly_broken_tool` — a tool failed across multiple distinct attempts
+- `capability_gap` — the task needs a tool/permission/capability the agent lacks
+- `complete_task_failure` — the agent genuinely could not deliver what was asked
+
+Signals only ship to the cloud destination, so the tool is not registered in
+local-only mode (no `RAINDROP_WRITE_KEY`).
+
 ## Notes
 
-- `@opencode-ai/plugin` is required.
-- `@opencode-ai/sdk` is an optional peer dependency.
+- `@opencode-ai/plugin` is required for the default (v1) export; `@opencode/plugin` for `/v2`.
+- `@opencode-ai/sdk` and `@opencode/sdk` are optional peer dependencies.
 - Tests live in the nested `tests/` package and validate HTTP payloads and tracing behavior.
 
 ## Application Git identity