From 267f60a55cf226052d18221648345b356a273746 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=91=D0=BE=D1=80=D0=BE=D0=B4=D0=B8=D0=BD=20=D0=A0=D0=BE?= =?UTF-8?q?=D0=BC=D0=B0=D0=BD?= Date: Fri, 25 Sep 2026 16:18:13 +0300 Subject: [PATCH] docs: update README with V1/V2 support, trigger behavior, session management --- plugins/matrix-plugin/README.md | 82 +++++++++++++++------------------ 1 file changed, 36 insertions(+), 46 deletions(-) diff --git a/plugins/matrix-plugin/README.md b/plugins/matrix-plugin/README.md index 492a441..91d061a 100644 --- a/plugins/matrix-plugin/README.md +++ b/plugins/matrix-plugin/README.md @@ -1,6 +1,6 @@ # opencode-matrix-plugin -OpenCode V2 plugin that connects your OpenCode agent to Matrix messaging servers. +OpenCode plugin that connects your OpenCode agent to Matrix messaging servers. Supports both V1 (SDK) and V2 (full context) APIs. ## Features @@ -8,14 +8,13 @@ OpenCode V2 plugin that connects your OpenCode agent to Matrix messaging servers - **Thread Isolation**: Each Matrix thread gets its own isolated session - **E2EE Support**: End-to-end encryption via Rust crypto SDK - **Auto-join**: Bot auto-joins rooms it's invited to -- **Multiple Trigger Modes**: Prefix trigger (`!oc`), @mention, or DM -- **Thread Replies**: Respond to plain replies within active threads +- **Configurable Triggers**: `triggerPatterns` array — empty = all messages, configured = only trigger/mention/thread-reply +- **Thread Replies**: Respond to plain replies within active threads (follow-up mode) - **Bridge Commands**: `/status`, `/clear`, `/help` for session management - **Rate Limiting**: Configurable per-user rate limiting - **User Allowlisting**: Restrict who can interact with the bot -- **Image Support**: Upload and display images in Matrix -- **HTML Formatting**: Optional HTML-formatted responses -- **Session Persistence**: Sessions survive plugin reloads +- **Session Persistence**: Sessions survive plugin reloads via `~/.opencode-matrix-sessions.json` +- **V1/V2 Dual Support**: Works with OpenCode 1.18.x (V1 SDK) and V2 (full context) ## Installation @@ -25,7 +24,7 @@ OpenCode V2 plugin that connects your OpenCode agent to Matrix messaging servers ```bash mkdir -p ~/.config/opencode/plugins -cp -r ./opencode-matrix-plugin ~/.config/opencode/plugins/ +cp -r ./plugins/matrix-plugin ~/.config/opencode/plugins/ ``` 2. Add the plugin to your `opencode.jsonc`: @@ -33,34 +32,16 @@ cp -r ./opencode-matrix-plugin ~/.config/opencode/plugins/ ```jsonc { "plugins": [ - "./plugins/opencode-matrix-plugin" + "./plugins/matrix-plugin" ] } ``` -### Option 2: npm Package +### Option 2: Symlink ```bash -cd ~/.config/opencode -npm init -y -npm install ./path/to/opencode-matrix-plugin -``` - -Then in `opencode.jsonc`: - -```jsonc -{ - "plugins": [ - { - "package": "opencode-matrix-plugin", - "options": { - "homeserver": "https://matrix.org", - "userId": "@opencode:matrix.org", - "password": "your-bot-password" - } - } - ] -} +mkdir -p ~/.config/opencode/plugins +ln -s /path/to/your/project/plugins/matrix-plugin ~/.config/opencode/plugins/matrix-plugin ``` ## Configuration @@ -133,13 +114,11 @@ Then in `opencode.jsonc`: | `password` | string | - | Bot password (preferred, auto-refreshes token) | | `deviceId` | string | `opencode-matrix-plugin` | Device ID for login | | `autoJoin` | boolean | `true` | Auto-join rooms the bot is invited to | -| `triggerPatterns` | string[] | `["!oc "]` | Message prefixes to trigger the bot | -| `ignoreRooms` | string[] | `[]` | Room IDs to ignore | -| `ignoreUsers` | string[] | `[]` | User IDs to ignore | +| `triggerPatterns` | string[] | `[]` | Message prefixes to trigger the bot. Empty = all messages. | | `allowedUsers` | string[] | `[]` | Allowlist (empty = everyone) | | `formatHtml` | boolean | `false` | Send HTML-formatted responses | | `threadIsolation` | boolean | `true` | Per-thread sessions | -| `respondToThreadReplies` | boolean | `true` | Reply to plain thread messages | +| `respondToThreadReplies` | boolean | `true` | Reply to plain thread messages (follow-up) | | `rateLimitSeconds` | number | `5` | Per-user cooldown between messages | | `botName` | string | `opencode` | Bot display name for @mentions | | `storagePath` | string | auto | Directory for bot state and crypto keys | @@ -149,10 +128,15 @@ Then in `opencode.jsonc`: ### Triggering the Bot +Behavior depends on `triggerPatterns` config: + +**With triggers configured** (e.g., `["!oc "]`): 1. **Prefix trigger**: Send `!oc What is TypeScript?` 2. **@Mention**: Send `@opencode What is TypeScript?` -3. **DM**: Send any message in a direct message with the bot -4. **Thread reply**: Reply to any message in an active thread +3. **Thread reply**: Reply to any message in an active thread (follow-up mode) + +**With empty triggers** (`triggerPatterns: []`): +- All messages are processed ### Bridge Commands @@ -194,21 +178,27 @@ SessionManager ├── Rate limiting ├── Event deduplication ├── Thread isolation (room:threadId) - └── Session lifecycle + └── Session persistence (~/.opencode-matrix-sessions.json) │ ▼ -OpenCode V2 Plugin API +OpenCode API │ - ├── ctx.session.prompt() - send queries - ├── ctx.session.hook("prompt") - intercept - ├── ctx.command.transform() - bridge commands - ├── ctx.event.subscribe() - event stream - └── ctx.storage - persistence + ├── V2: ctx.session.prompt() / ctx.session.create() + ├── V1: sdkClient.session.prompt() / sdkClient.session.create() + └── Session mapping: Matrix thread → OpenCode session │ ▼ Response → MatrixBotClient → Matrix Room ``` +## Session Management + +Sessions are persisted across plugin restarts in `~/.opencode-matrix-sessions.json`. + +- **V1 API**: Sessions are created with auto-generated IDs, mapped via JSON file +- **V2 API**: Sessions can be created with custom deterministic IDs (no map needed) +- **Sync**: Use `sessionManager.syncWithOpenCode(sessionIds)` to prune orphaned sessions + ## Security - **E2EE**: Full end-to-end encryption support via `@matrix-org/matrix-sdk-crypto-nodejs` @@ -243,10 +233,10 @@ Response → MatrixBotClient → Matrix Room ## Development ```bash -cd plugins/opencode-matrix-plugin -npm install -npm run typecheck -npm run build +cd plugins/matrix-plugin +bun install +bun run typecheck +bun run build ``` ## License