opencode-discord-notify 0.1.0 → 0.2.0

package/README-JP.md

@@ -20,24 +20,6 @@ OpenCode のイベントを Discord Webhook に通知するプラグインです
 Discord の Forum チャンネル webhook を前提に、セッション開始時（または最初の通知タイミング）にスレッド（投稿）を作成して、その後の更新を同スレッドに流します。
 通常のテキストチャンネル webhook でも利用できます（その場合はスレッドが作れないため、チャンネルへ直投稿します）。
 
-## 使い方
-
-`opencode.json` / `opencode.jsonc` にプラグインを追加します。
-
-```jsonc
-{
-  "plugin": ["opencode-discord-notify@latest"],
-}
-```
-
-バージョン固定したい場合:
-
-```jsonc
-{
-  "plugin": ["opencode-discord-notify@0.1.0"],
-}
-```
-
 ## できること
 
 - `session.created`: セッション開始 → 開始通知をキュー（スレッド作成/送信は後続イベントで条件が揃ったタイミングで実行されることがある）
@@ -50,29 +32,24 @@ Discord の Forum チャンネル webhook を前提に、セッション開始
 
 ## セットアップ
 
-### 1) 依存のインストール
-
-グローバルにインストールします。
-
-- `npm i -g @opencode-ai/plugin`
-
-### 2) プラグイン配置
-
-プロジェクト直下に以下のファイルを置きます。
+### 1) プラグイン配置
 
-- `.opencode/plugin/discord-notification.ts`
+`opencode.json` / `opencode.jsonc` にプラグインを追加します。
 
-（グローバルに使いたい場合は `~/.config/opencode/plugin/` 配下でもOKです）
+OpenCode を再起動してください。
 
-> [!WARNING]
-> グローバル（`~/.config/opencode/plugin/`）とプロジェクト（`.opencode/plugin/`）の両方に配置すると、プラグインが二重に読み込まれて通知が重複します。どちらか一方にしてください。
+```jsonc
+{
+  "plugin": ["opencode-discord-notify@latest"],
+}
+```
 
-### 3) Discord 側の準備
+### 2) Discord 側の準備
 
 - Discord の Forum チャンネルで Webhook を作成してください。
 - テキストチャンネル webhook でも動きますが、スレッド作成（`thread_name`）は Forum 向けの挙動が前提です。
 
-### 4) 環境変数
+### 3) 環境変数
 
 必須:
 
@@ -85,6 +62,7 @@ Discord の Forum チャンネル webhook を前提に、セッション開始
 - `DISCORD_WEBHOOK_COMPLETE_MENTION`: `session.idle` / `session.error` の通知本文に付けるメンション（`@everyone` または `@here` のみ許容。Forum webhook の仕様上、ping は常に発生しない）
 - `DISCORD_WEBHOOK_PERMISSION_MENTION`: `permission.updated` の通知本文に付けるメンション（`DISCORD_WEBHOOK_COMPLETE_MENTION` へのフォールバックなし。`@everyone` または `@here` のみ許容。Forum webhook の仕様上、ping は常に発生しない）
 - `DISCORD_WEBHOOK_EXCLUDE_INPUT_CONTEXT`: `1` のとき input context（`<file>` から始まる user `text` part）を通知しない（デフォルト: `1` / `0` で無効化）
+- `SEND_PARAMS`: embed の fields として送るキーをカンマ区切りで指定。指定可能キー: `sessionID`, `permissionID`, `type`, `pattern`, `messageID`, `callID`, `partID`, `role`, `directory`, `projectID`。未設定・空文字・空要素のみの場合は全て選択。`session.created` は `SEND_PARAMS` に関わらず `sessionID`, `projectID`, `directory` を必ず含みます。
 
 ## 仕様メモ
 
@@ -104,8 +82,10 @@ Discord の Forum チャンネル webhook を前提に、セッション開始
 - `message.updated` は通知しません（role 判定用に追跡。role 未確定で保留した `text` part を後から通知することがあります）。
 - `message.part.updated` は以下の方針です。
   - `text`: user は即時通知。assistant は `part.time.end` がある確定時のみ通知（ストリーミング途中更新は通知しない）
+    - embed タイトルは `User says` / `Agent says` です
   - `tool`: 通知しない
   - `reasoning`: 通知しない（内部思考が含まれる可能性があるため）
+- `SEND_PARAMS` の制御対象は embed の fields のみです（title/description/content/timestamp などは対象外）。また `share` は fields としては送りません（Session started の embed URL には `shareUrl` を使います）。
 
 ## 動作確認（手動）
 
@@ -118,7 +98,7 @@ Discord の Forum チャンネル webhook を前提に、セッション開始
 
 - 依存のインストール: `npm i`
 - フォーマット: `npx prettier . --write`
-- プラグイン本体: `.opencode/plugin/discord-notification.ts`
+- プラグイン本体: `src/index.ts`
 
 ## 今後の展望（予定）
 

package/README.md

@@ -21,24 +21,6 @@ A plugin that posts OpenCode events to a Discord webhook.
 It is optimized for Discord Forum channel webhooks: it creates one thread per session (via `thread_name`) and posts subsequent updates to the same thread.
 It also works with regular text channel webhooks (in that case, it falls back to posting directly to the channel because threads cannot be created).
 
-## Usage
-
-Add this plugin to your `opencode.json` / `opencode.jsonc`:
-
-```jsonc
-{
-  "plugin": ["opencode-discord-notify@latest"],
-}
-```
-
-If you want to pin a version:
-
-```jsonc
-{
-  "plugin": ["opencode-discord-notify@0.1.0"],
-}
-```
-
 ## What it does
 
 - `session.created`: session started → queues a start notification (thread creation / sending may happen later when required info is available)
@@ -46,37 +28,30 @@ If you want to pin a version:
 - `session.idle`: session finished → posts a notification
 - `session.error`: error → posts a notification (skips if `sessionID` is not present)
 - `todo.updated`: todo updates → posts a checklist (keeps received order; excludes `cancelled`)
-- `message.updated`: does not notify (tracked for role inference; may emit previously-held text later)
-- `message.part.updated`:
-  - `text`: user text is posted immediately; assistant text is posted only when finalized (`time.end`)
+- `message.updated`: does not notify (tracked for role inference; may emit previously-held `text` later)
+- `message.part.updated`: message content/tool results updates →
+  - `text`: user text is posted immediately; assistant text is posted only when finalized (when `time.end` exists)
   - `tool`: not posted
   - `reasoning`: not posted
 
 ## Setup
 
-### 1) Install dependencies
-
-Install the OpenCode plugin runner globally.
-
-- `npm i -g @opencode-ai/plugin`
-
-### 2) Place the plugin file
+### 1) Add the plugin
 
-Put the plugin file in your project:
+Add this plugin to your `opencode.json` / `opencode.jsonc` and restart OpenCode.
 
-- `.opencode/plugin/discord-notification.ts`
-
-(If you want to use it globally, place it under `~/.config/opencode/plugin/` instead.)
-
-> [!WARNING]
-> If you place the plugin in both the global directory (`~/.config/opencode/plugin/`) and the project directory (`.opencode/plugin/`), it may be loaded twice and send duplicate notifications. Choose either global or project placement, not both.
+```jsonc
+{
+  "plugin": ["opencode-discord-notify@latest"],
+}
+```
 
-### 3) Create a Discord webhook
+### 2) Create a Discord webhook
 
 - Recommended: create a webhook in a Discord Forum channel.
 - A webhook in a regular text channel also works, but thread creation using `thread_name` is a Forum-oriented behavior.
 
-### 4) Environment variables
+### 3) Environment variables
 
 Required:
 
@@ -88,7 +63,8 @@ Optional:
 - `DISCORD_WEBHOOK_AVATAR_URL`: avatar URL for webhook posts
 - `DISCORD_WEBHOOK_COMPLETE_MENTION`: mention to put in `session.idle` / `session.error` messages (only `@everyone` or `@here` supported; Forum webhooks may not actually ping due to Discord behavior)
 - `DISCORD_WEBHOOK_PERMISSION_MENTION`: mention to put in `permission.updated` messages (no fallback to `DISCORD_WEBHOOK_COMPLETE_MENTION`; only `@everyone` or `@here` supported; Forum webhooks may not actually ping due to Discord behavior)
-- `DISCORD_WEBHOOK_EXCLUDE_INPUT_CONTEXT`: when set to `1`, exclude "input context" (user text parts that start with `<file>`) from notifications (default: `1`; set to `0` to disable)
+- `DISCORD_WEBHOOK_EXCLUDE_INPUT_CONTEXT`: when set to `1`, exclude "input context" (user `text` parts that start with `<file>`) from notifications (default: `1`; set to `0` to disable)
+- `SEND_PARAMS`: comma-separated list of keys to include as embed fields. Allowed keys: `sessionID`, `permissionID`, `type`, `pattern`, `messageID`, `callID`, `partID`, `role`, `directory`, `projectID`. If unset, empty, or containing only empty elements, all keys are selected. `session.created` always includes `sessionID`, `projectID`, `directory` regardless.
 
 ## Notes / behavior
 
@@ -102,26 +78,37 @@ Optional:
 - If thread creation fails (e.g. on non-Forum webhooks), it falls back to posting directly to the channel.
 - `permission.updated` / `session.idle` may be queued until the thread name becomes available.
 - `session.error` is skipped when `sessionID` is missing in the upstream payload.
-- `DISCORD_WEBHOOK_COMPLETE_MENTION=@everyone` (or `@here`) is included as message content, but Forum webhooks may not actually ping.
-- `DISCORD_WEBHOOK_PERMISSION_MENTION=@everyone` (or `@here`) is included as message content for `permission.updated`, but Forum webhooks may not actually ping.
-- `todo.updated` posts a checklist in the order received (`in_progress` = `[▶]`, `completed` = `[✓]`, `cancelled` excluded). Long lists may be truncated to fit embed constraints.
+- `DISCORD_WEBHOOK_COMPLETE_MENTION=@everyone` (or `@here`) is included as message content, but Forum webhooks may not actually ping (it may just show as plain text).
+- `DISCORD_WEBHOOK_PERMISSION_MENTION=@everyone` (or `@here`) is included as message content for `permission.updated`, but Forum webhooks may not actually ping (it may just show as plain text).
+- `todo.updated` posts a checklist in the order received (`in_progress` = `[▶]`, `completed` = `[✓]`, `cancelled` excluded). Long lists may be truncated to fit embed constraints (if empty: `(no todos)`; if truncated: adds `...and more`).
 - `message.updated` is not posted (tracked for role inference; may post a previously-held text part later).
 - `message.part.updated` policy:
   - `text`: user is posted immediately; assistant is posted only when finalized (when `part.time.end` exists)
+    - Embed titles are `User says` / `Agent says`
   - `tool`: not posted
   - `reasoning`: not posted (to avoid exposing internal thoughts)
+- `SEND_PARAMS` controls embed fields only (it does not affect title/description/content/timestamp). `share` is not an embed field (but Session started uses `shareUrl` as the embed URL).
 
 ## Manual test
 
 1. Start OpenCode → a new thread appears in the Forum channel on the first notification timing
 2. Trigger a permission request → a notification is posted to the same thread (if the thread isn't created yet, it may be created later)
-3. Finish the session → `session.idle` is posted
-4. Trigger an error → `session.error` is posted (skipped if no `sessionID`)
+3. Finish the session → `session.idle` is posted (if you set `DISCORD_WEBHOOK_COMPLETE_MENTION`, it may not actually ping in Forum webhooks)
+4. Trigger an error → `session.error` is posted (skipped if no `sessionID`; if you set `DISCORD_WEBHOOK_COMPLETE_MENTION`, it may not actually ping in Forum webhooks)
 
 ## Development
 
 - Install deps: `npm i`
 - Format: `npx prettier . --write`
-- Plugin source: `.opencode/plugin/discord-notification.ts`
+- Plugin source: `src/index.ts`
+
+## Roadmap (planned)
+
+- Publish as an npm package (to make install/update easier)
+- Support multiple webhooks / multiple channels (route by use case)
+- Allow customizing notifications (events, message templates, mention policy)
+  - Consider reading a config file (e.g. `opencode-discord-notify.config.json`) and resolving values from env vars as needed
+- Improve Discord limitations handling (rate-limit retry, split posts, better truncation rules)
+- Improve CI (automate lint/format; add basic tests)
 
 PRs and issues are welcome.

package/dist/index.d.ts

@@ -2,6 +2,4 @@ import { Plugin } from '@opencode-ai/plugin';
 
 declare const plugin: Plugin;
 
-declare const DiscordNotificationPlugin: Plugin;
-
-export { DiscordNotificationPlugin, plugin as default };
+export { plugin as default };

package/dist/index.js

@@ -1,4 +1,17 @@
 // src/index.ts
+var SEND_PARAM_KEYS = [
+  "sessionID",
+  "permissionID",
+  "type",
+  "pattern",
+  "messageID",
+  "callID",
+  "partID",
+  "role",
+  "directory",
+  "projectID"
+];
+var SEND_PARAM_KEY_SET = new Set(SEND_PARAM_KEYS);
 var COLORS = {
   info: 5793266,
   success: 5763719,
@@ -32,6 +45,23 @@ function buildFields(fields, inline = false) {
   }
   return result.length ? result : void 0;
 }
+function isSendParamKey(value) {
+  return SEND_PARAM_KEY_SET.has(value);
+}
+function filterSendFields(fields, allowed) {
+  return fields.filter(([name]) => {
+    if (!isSendParamKey(name)) return false;
+    return allowed.has(name);
+  });
+}
+function getTextPartEmbedTitle(role) {
+  return role === "user" ? "User says" : "Agent says";
+}
+function withForcedSendParams(base, forced) {
+  const next = new Set(base);
+  for (const key of forced) next.add(key);
+  return next;
+}
 function getEnv(name) {
   try {
     return process.env[name];
@@ -39,6 +69,17 @@ function getEnv(name) {
     return void 0;
   }
 }
+function parseSendParams(raw) {
+  if (raw === void 0) return new Set(SEND_PARAM_KEYS);
+  const tokens = raw.split(",").map((v) => v.trim()).filter(Boolean);
+  if (!tokens.length) return new Set(SEND_PARAM_KEYS);
+  const result = /* @__PURE__ */ new Set();
+  for (const token of tokens) {
+    if (!SEND_PARAM_KEY_SET.has(token)) continue;
+    result.add(token);
+  }
+  return result;
+}
 function withQuery(url, params) {
   const u = new URL(url);
   for (const [k, v] of Object.entries(params)) {
@@ -78,7 +119,16 @@ async function postDiscordWebhook(input) {
     channel_id: channelId
   };
 }
+var GLOBAL_GUARD_KEY = "__opencode_discord_notify_registered__";
 var plugin = async () => {
+  const globalWithGuard = globalThis;
+  if (globalWithGuard[GLOBAL_GUARD_KEY]) {
+    return {
+      event: async () => {
+      }
+    };
+  }
+  globalWithGuard[GLOBAL_GUARD_KEY] = true;
   const webhookUrl = getEnv("DISCORD_WEBHOOK_URL");
   const username = getEnv("DISCORD_WEBHOOK_USERNAME");
   const avatarUrl = getEnv("DISCORD_WEBHOOK_AVATAR_URL");
@@ -88,6 +138,7 @@ var plugin = async () => {
   const permissionMention = permissionMentionRaw || void 0;
   const excludeInputContextRaw = (getEnv("DISCORD_WEBHOOK_EXCLUDE_INPUT_CONTEXT") ?? "1").trim();
   const excludeInputContext = excludeInputContextRaw !== "0";
+  const sendParams = parseSendParams(getEnv("SEND_PARAMS"));
   const sessionToThread = /* @__PURE__ */ new Map();
   const threadCreateInFlight = /* @__PURE__ */ new Map();
   const pendingPostsBySession = /* @__PURE__ */ new Map();
@@ -312,12 +363,19 @@ var plugin = async () => {
               color: COLORS.info,
               timestamp: createdAt,
               fields: buildFields(
-                [
-                  ["sessionID", sessionID],
-                  ["projectID", projectID],
-                  ["directory", directory],
-                  ["share", shareUrl]
-                ],
+                filterSendFields(
+                  [
+                    ["sessionID", sessionID],
+                    ["projectID", projectID],
+                    ["directory", directory],
+                    ["share", shareUrl]
+                  ],
+                  withForcedSendParams(sendParams, [
+                    "sessionID",
+                    "projectID",
+                    "directory"
+                  ])
+                ),
                 false
               )
             };
@@ -336,14 +394,17 @@ var plugin = async () => {
               color: COLORS.warning,
               timestamp: toIsoTimestamp(p?.time?.created),
               fields: buildFields(
-                [
-                  ["sessionID", sessionID],
-                  ["permissionID", p?.id],
-                  ["type", p?.type],
-                  ["pattern", p?.pattern],
-                  ["messageID", p?.messageID],
-                  ["callID", p?.callID]
-                ],
+                filterSendFields(
+                  [
+                    ["sessionID", sessionID],
+                    ["permissionID", p?.id],
+                    ["type", p?.type],
+                    ["pattern", p?.pattern],
+                    ["messageID", p?.messageID],
+                    ["callID", p?.callID]
+                  ],
+                  sendParams
+                ),
                 false
               )
             };
@@ -362,7 +423,10 @@ var plugin = async () => {
             const embed = {
               title: "Session completed",
               color: COLORS.success,
-              fields: buildFields([["sessionID", sessionID]], false)
+              fields: buildFields(
+                filterSendFields([["sessionID", sessionID]], sendParams),
+                false
+              )
             };
             const mention = buildCompleteMention();
             enqueueToThread(sessionID, {
@@ -381,7 +445,10 @@ var plugin = async () => {
               title: "Session error",
               color: COLORS.error,
               description: errorStr ? errorStr.length > 4096 ? errorStr.slice(0, 4093) + "..." : errorStr : void 0,
-              fields: buildFields([["sessionID", sessionID]], false)
+              fields: buildFields(
+                filterSendFields([["sessionID", sessionID]], sendParams),
+                false
+              )
             };
             if (!sessionID) return;
             const mention = buildCompleteMention();
@@ -400,7 +467,10 @@ var plugin = async () => {
             const embed = {
               title: "Todo updated",
               color: COLORS.info,
-              fields: buildFields([["sessionID", sessionID]], false),
+              fields: buildFields(
+                filterSendFields([["sessionID", sessionID]], sendParams),
+                false
+              ),
               description: buildTodoChecklist(p?.todos)
             };
             enqueueToThread(sessionID, { embeds: [embed] });
@@ -441,15 +511,18 @@ var plugin = async () => {
                       firstUserTextBySession.set(sessionID, normalized);
                   }
                   const embed = {
-                    title: role === "user" ? "Message part updated: text (user)" : "Message part updated: text (assistant)",
+                    title: getTextPartEmbedTitle(role),
                     color: COLORS.info,
                     fields: buildFields(
-                      [
-                        ["sessionID", sessionID],
-                        ["messageID", messageID],
-                        ["partID", partID],
-                        ["role", role]
-                      ],
+                      filterSendFields(
+                        [
+                          ["sessionID", sessionID],
+                          ["messageID", messageID],
+                          ["partID", partID],
+                          ["role", role]
+                        ],
+                        sendParams
+                      ),
                       false
                     ),
                     description: truncateText(text || "(empty)", 4096)
@@ -498,15 +571,18 @@ var plugin = async () => {
                   firstUserTextBySession.set(sessionID, normalized);
               }
               const embed = {
-                title: role === "user" ? "Message part updated: text (user)" : "Message part updated: text (assistant)",
+                title: getTextPartEmbedTitle(role),
                 color: COLORS.info,
                 fields: buildFields(
-                  [
-                    ["sessionID", sessionID],
-                    ["messageID", messageID],
-                    ["partID", partID],
-                    ["role", role]
-                  ],
+                  filterSendFields(
+                    [
+                      ["sessionID", sessionID],
+                      ["messageID", messageID],
+                      ["partID", partID],
+                      ["role", role]
+                    ],
+                    sendParams
+                  ),
                   false
                 ),
                 description: truncateText(text || "(empty)", 4096)
@@ -532,8 +608,6 @@ var plugin = async () => {
   };
 };
 var index_default = plugin;
-var DiscordNotificationPlugin = plugin;
 export {
-  DiscordNotificationPlugin,
   index_default as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-discord-notify",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A plugin that posts OpenCode events to a Discord webhook.",
   "license": "MIT",
   "type": "module",