@dragonwize/opencode-event-push 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Doucette
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# opencode-event-push
+
+An [OpenCode](https://opencode.ai) plugin that forwards a configurable set of events to one or more URLs via HTTP POST.
+
+Use it to integrate OpenCode with webhooks, logging pipelines, monitoring systems, or any custom backend.
+
+## Installation
+
+Add the plugin to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-event-push"]
+}
+```
+
+OpenCode installs the package automatically at startup using Bun. The package lands in:
+
+```
+~/.cache/opencode/node_modules/opencode-event-push/
+```
+
+## Configuration
+
+The plugin reads its config from `event-push.json` in the **same directory as the installed plugin package** (i.e. next to `package.json`). Copy the bundled example and edit it:
+
+```sh
+cp ~/.cache/opencode/node_modules/opencode-event-push/event-push.example.json \
+   ~/.cache/opencode/node_modules/opencode-event-push/event-push.json
+```
+
+Then open `event-push.json` and replace the placeholder URLs, events, and credentials.
+
+### Config schema
+
+```json
+{
+  "targets": [
+    {
+      "url": "https://your-endpoint.example.com/events",
+      "events": ["session.idle", "session.error"],
+      "retry": {
+        "attempts": 3,
+        "delayMs": 500
+      },
+      "headers": {
+        "Authorization": "Bearer your-token"
+      }
+    }
+  ]
+}
+```
+
+#### `targets` (required)
+
+An array of target objects. Each target is independent — it gets its own URL, event filter, retry policy, and headers.
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `url` | yes | — | URL to `POST` events to |
+| `events` | no | all events | Allowlist of event types to forward to this target. Omit or leave empty to receive all events. |
+| `retry.attempts` | no | `3` | Maximum number of attempts (including the first try) |
+| `retry.delayMs` | no | `500` | Base delay in ms between retries. Uses exponential backoff: `delayMs * 2^attempt` |
+| `headers` | no | `{}` | Extra HTTP headers sent with every request to this target |
+
+### Multiple targets
+
+Each target filters and delivers events independently. One slow or failing target does not block the others — all targets for a given event are pushed in parallel.
+
+```json
+{
+  "targets": [
+    {
+      "url": "https://webhook.example.com/opencode",
+      "events": ["session.created", "session.idle", "session.error"],
+      "headers": { "Authorization": "Bearer secret1" }
+    },
+    {
+      "url": "https://logging.example.com/ingest",
+      "events": ["tool.execute.after", "file.edited"],
+      "headers": { "X-API-Key": "secret2" }
+    },
+    {
+      "url": "https://catch-all.example.com/events"
+    }
+  ]
+}
+```
+
+## Available events
+
+Any event from the OpenCode plugin API can be forwarded. Common ones:
+
+**Session:** `session.created` `session.updated` `session.deleted` `session.idle` `session.error` `session.status` `session.compacted` `session.diff`
+
+**Message:** `message.updated` `message.removed` `message.part.updated` `message.part.removed`
+
+**Tool:** `tool.execute.before` `tool.execute.after`
+
+**File:** `file.edited` `file.watcher.updated`
+
+**Permission:** `permission.asked` `permission.replied`
+
+**Other:** `command.executed` `server.connected` `todo.updated` `lsp.updated` `lsp.client.diagnostics` `installation.updated` `tui.prompt.append` `tui.command.execute` `tui.toast.show` `shell.env`
+
+## Payload format
+
+Each event is POSTed as JSON with `Content-Type: application/json`. The payload is the raw event object from OpenCode, e.g.:
+
+```json
+{
+  "type": "session.idle",
+  "sessionID": "abc123",
+  "properties": { ... }
+}
+```
+
+## Testing
+
+A test server is included that accepts incoming events and prints them live to the terminal with color-coded output.
+
+### Start the test server
+
+```sh
+bun run test-server.ts
+```
+
+By default it listens on port `34567`. Pass an alternative port as the first argument:
+
+```sh
+bun run test-server.ts 9000
+```
+
+### Point the plugin at it
+
+Add a target to your `event-push.json` (the catch-all form with no `events` filter is most useful for testing):
+
+```json
+{
+  "targets": [
+    { "url": "http://localhost:34567" }
+  ]
+}
+```
+
+Then start OpenCode normally. Events will appear in the test server terminal as they fire.
+
+### Send a test event manually
+
+You can also POST events directly with `curl` to verify the server is running before starting OpenCode:
+
+```sh
+curl -X POST http://localhost:34567 \
+  -H "Content-Type: application/json" \
+  -d '{"type":"session.idle","sessionID":"test","properties":{"title":"hello"}}'
+```
+
+### Sample output
+
+```
+opencode-event-push test server
+Listening on http://localhost:34567
+Waiting for events…
+
+────────────────────────────────────────────────────────────
+[2026-02-27 10:00:01.234]  #1  session.idle
+  sessionID="abc123"  properties={"title":"My session"}
+  {
+    "type": "session.idle",
+    "sessionID": "abc123",
+    "properties": {
+      "title": "My session"
+    }
+  }
+```
+
+Event types are color-coded by namespace: `session.*` (cyan), `tool.*` (yellow), `message.*` (magenta), `file.*` (green), `permission.*` (red).
+
+## Error handling
+
+On a failed request the plugin retries with exponential backoff (500ms, 1000ms, 2000ms, …). After exhausting all attempts it logs a `warn`-level message via OpenCode's structured log — it does not throw or block the session in any way.
+
+## Local plugin usage
+
+If you prefer to use this as a local file plugin rather than via npm, drop `src/index.ts` into `.opencode/plugins/` and place `event-push.json` in the same `.opencode/plugins/` directory.
+
+## License
+
+MIT

package/event-push.example.json

@@ -0,0 +1,30 @@
+{
+  "targets": [
+    { "url": "http://localhost:34567" },
+    {
+      "url": "https://webhook.example.com/opencode",
+      "events": [
+        "session.created",
+        "session.idle",
+        "session.error"
+      ],
+      "retry": {
+        "attempts": 3,
+        "delayMs": 500
+      },
+      "headers": {
+        "Authorization": "Bearer your-secret-token"
+      }
+    },
+    {
+      "url": "https://logging.example.com/ingest",
+      "events": [
+        "tool.execute.after",
+        "file.edited"
+      ],
+      "headers": {
+        "X-API-Key": "your-api-key"
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dragonwize/opencode-event-push",
+  "version": "0.5.0",
+  "description": "OpenCode plugin that forwards a configurable set of events to one or more URLs via HTTP POST.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "webhook",
+    "events"
+  ],
+  "homepage": "https://github.com/dragonwize/opencode-event-push",
+  "bugs": {
+    "url": "https://github.com/dragonwize/opencode-event-push/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dragonwize/opencode-event-push.git"
+  },
+  "license": "MIT",
+  "author": "dragonwize",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src/",
+    "event-push.example.json"
+  ],
+  "scripts": {
+    "test-server": "bun run test-server.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "@types/bun": "^1.3.9",
+    "@types/node": "^25.3.2",
+    "bun-types": "^1.3.9",
+    "typescript": "^5",
+    "undici-types": "^7.18.2",
+    "zod": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,135 @@
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import type { Plugin } from "@opencode-ai/plugin"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// ── Config types ──────────────────────────────────────────────────────────────
+
+interface RetryConfig {
+  /** Maximum number of attempts (including the first). Default: 3 */
+  attempts?: number
+  /** Base delay in milliseconds for exponential backoff. Default: 500 */
+  delayMs?: number
+}
+
+interface TargetConfig {
+  /** Required. URL to POST events to. */
+  url: string
+  /**
+   * Optional allowlist of event types to forward to this target.
+   * Omit (or set to an empty array) to forward all events.
+   */
+  events?: string[]
+  /** Optional retry policy. */
+  retry?: RetryConfig
+  /** Optional extra HTTP headers (e.g. Authorization, X-API-Key). */
+  headers?: Record<string, string>
+}
+
+interface PluginConfig {
+  targets: TargetConfig[]
+}
+
+// ── Config loading ────────────────────────────────────────────────────────────
+
+function loadConfig(): PluginConfig {
+  // The config file lives alongside the plugin (one level up from src/)
+  const configPath = join(__dirname, "..", "event-push.json")
+  try {
+    const raw = readFileSync(configPath, "utf-8")
+    const parsed = JSON.parse(raw) as PluginConfig
+    if (!Array.isArray(parsed.targets)) {
+      console.warn(
+        "[opencode-event-push] event-push.json is missing a 'targets' array — plugin is a no-op",
+      )
+      return { targets: [] }
+    }
+    return parsed
+  } catch (err: unknown) {
+    const isNotFound =
+      err instanceof Error && "code" in err && (err as NodeJS.ErrnoException).code === "ENOENT"
+    if (!isNotFound) {
+      console.warn(
+        `[opencode-event-push] Could not read event-push.json: ${String(err)}`,
+      )
+    }
+    return { targets: [] }
+  }
+}
+
+// ── HTTP push with retry ──────────────────────────────────────────────────────
+
+async function pushToTarget(
+  target: TargetConfig,
+  payload: unknown,
+  log: (msg: string, extra?: Record<string, unknown>) => Promise<void>,
+): Promise<void> {
+  const { url, retry = {}, headers = {} } = target
+  const maxAttempts = retry.attempts ?? 3
+  const baseDelay = retry.delayMs ?? 500
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify(payload),
+      })
+
+      if (res.ok) return
+
+      throw new Error(`HTTP ${res.status} ${res.statusText}`)
+    } catch (err) {
+      const isLastAttempt = attempt === maxAttempts - 1
+      if (isLastAttempt) {
+        await log(
+          `Failed to push event to ${url} after ${maxAttempts} attempt(s): ${String(err)}`,
+          { url, error: String(err), attempts: maxAttempts },
+        )
+        return
+      }
+
+      // Exponential backoff: 500ms, 1000ms, 2000ms, …
+      const delay = baseDelay * 2 ** attempt
+      await new Promise((resolve) => setTimeout(resolve, delay))
+    }
+  }
+}
+
+// ── Plugin ────────────────────────────────────────────────────────────────────
+
+export const EventPushPlugin: Plugin = async ({ client }) => {
+  const { targets } = loadConfig()
+
+  if (targets.length === 0) return {}
+
+  async function log(message: string, extra?: Record<string, unknown>) {
+    await client.app.log({
+      body: {
+        service: "opencode-event-push",
+        level: "warn",
+        message,
+        extra,
+      },
+    })
+  }
+
+  return {
+    event: async ({ event }) => {
+      const matchingTargets = targets.filter(
+        (t) =>
+          !t.events || t.events.length === 0 || t.events.includes(event.type),
+      )
+
+      if (matchingTargets.length === 0) return
+
+      await Promise.allSettled(
+        matchingTargets.map((target) => pushToTarget(target, event, log)),
+      )
+    },
+  }
+}
+
+export default EventPushPlugin