@scrylog/opencode-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Joel D. Martinez
+
+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,259 @@
+# @scrylog/opencode-plugin
+
+`@scrylog/opencode-plugin` is an OpenCode plugin that sends session and permission events to the `scrylog` daemon webhook in real time.
+
+This is the recommended OpenCode integration when `scrylog` is running in `hooks` mode.
+
+## When To Use This Plugin
+
+Use this plugin when:
+
+- you run OpenCode inside `tmux`
+- you want `scrylog` to receive immediate session updates
+- you want the best available correlation between OpenCode sessions and `tmux` panes
+- you want `hooks` mode, which is the recommended OpenCode mode in `scrylog`
+
+Do not use this plugin as your primary integration when:
+
+- you are using `opencode.mode: "sse"`
+- you want standalone-only OpenCode monitoring through `opencode --port`, `opencode serve`, or `oc`
+
+In `sse` mode, the `scrylog` daemon accepts the HTTP request but ignores the payload and returns:
+
+```json
+{ "ok": true, "skipped": "opencode-mode-sse" }
+```
+
+## What The Plugin Does
+
+The plugin listens for OpenCode session and permission events and forwards them to:
+
+```text
+http://127.0.0.1:7788/api/webhook/opencode
+```
+
+If OpenCode is running inside `tmux`, the plugin also tries to write the current OpenCode session ID into the pane option:
+
+```text
+@opencode-session
+```
+
+That gives `scrylog` an exact signal for correlating the OpenCode session with the `tmux` pane.
+
+## Requirements
+
+- `@scrylog/cli` installed and reachable through the `scrylog` command
+- `scrylogd` running
+- OpenCode installed
+- `opencode.mode` set to `hooks` in `scrylog`
+- `tmux` installed if you want pane correlation
+
+## Installation
+
+### 1. Install the plugin
+
+```bash
+bun install -g @scrylog/opencode-plugin
+```
+
+You can also use npm:
+
+```bash
+npm install -g @scrylog/opencode-plugin
+```
+
+### 2. Configure `scrylog` for hooks mode
+
+Create or update `~/.config/scrylog/config.json`:
+
+```json
+{
+  "opencode": {
+    "mode": "hooks"
+  }
+}
+```
+
+You can also do this from the main operator CLI:
+
+```bash
+scrylog setup
+```
+
+Choose OpenCode, then choose `hooks` mode.
+
+### 3. Enable the plugin in OpenCode
+
+Create or update `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["@scrylog/opencode-plugin"]
+}
+```
+
+### 4. Start the daemon
+
+```bash
+scrylog daemon install
+scrylog daemon start
+```
+
+Or run the daemon manually in the foreground:
+
+```bash
+scrylogd
+```
+
+### 5. Start OpenCode
+
+Start OpenCode normally. The plugin loads automatically.
+
+### 6. Verify it works
+
+Open another terminal and check the daemon:
+
+```bash
+curl http://127.0.0.1:7788/api/sessions
+```
+
+You should see OpenCode sessions appear when they start receiving events.
+
+You can also run:
+
+```bash
+scrylog doctor
+```
+
+That confirms local daemon reachability and current OpenCode mode.
+
+## Configuration
+
+The plugin uses one environment variable:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SCRYLOG_URL` | `http://127.0.0.1:7788/api/webhook/opencode` | Full webhook URL for the `scrylog` daemon |
+
+### Example: custom daemon port
+
+```bash
+SCRYLOG_URL=http://127.0.0.1:9000/api/webhook/opencode opencode
+```
+
+If you also moved the `scrylog` API port, make sure your `scrylog` config matches it:
+
+```json
+{
+  "api": {
+    "tcpEnabled": true,
+    "host": "127.0.0.1",
+    "port": 9000
+  }
+}
+```
+
+### Example: set it in your shell profile
+
+```bash
+export SCRYLOG_URL=http://127.0.0.1:9000/api/webhook/opencode
+```
+
+## Supported Events
+
+The plugin forwards these OpenCode events:
+
+| Event | Meaning |
+| --- | --- |
+| `session.created` | New session created |
+| `session.updated` | Session metadata changed |
+| `session.deleted` | Session deleted |
+| `session.status` | State changed, such as `busy`, `idle`, or `retry` |
+| `session.idle` | Explicit idle signal |
+| `session.error` | Session error |
+| `permission.updated` | Permission prompt state updated |
+| `permission.asked` | Permission prompt shown |
+| `permission.replied` | Permission prompt answered |
+
+## Request Format
+
+Each event is sent as:
+
+- `POST`
+- `Content-Type: application/json`
+
+Example payload:
+
+```json
+{
+  "event": "session.status",
+  "directory": "/Users/you/projects/my-app",
+  "sessionID": "ses_123",
+  "status": {
+    "type": "busy"
+  }
+}
+```
+
+For `session.created` and `session.updated`, OpenCode may also include richer `info` payloads such as title, timestamps, and `parentID`.
+
+## Hooks Mode Vs SSE Mode
+
+### In `hooks` mode
+
+The daemon uses plugin webhook events as the primary OpenCode signal.
+
+What you get:
+
+- immediate OpenCode state updates
+- permission prompt visibility
+- better `tmux` correlation when the pane option is available
+- child and subagent visibility when OpenCode emits parent session IDs
+
+### In `sse` mode
+
+The daemon ignores this plugin and instead connects to OpenCode over its HTTP server.
+
+Use `sse` mode when you run:
+
+- `opencode --port 4096`
+- `opencode serve`
+- `oc`
+
+In `sse` mode:
+
+- OpenCode is shown as standalone only
+- OpenCode `tmux` panes are hidden in `scrylog`
+- this plugin is optional and effectively inactive
+
+## Limitations
+
+- The plugin can only provide exact `tmux` correlation when it can write `@opencode-session` in the active pane.
+- OpenCode `attach` inside `tmux` still does not have complete exact-session support without an upstream OpenCode signal.
+- If the daemon is down, webhook sends are fire-and-forget and are silently dropped.
+
+## Troubleshooting
+
+### The plugin is installed but OpenCode sessions do not appear
+
+Check all of the following:
+
+1. `scrylogd` is running
+2. `opencode.mode` is `hooks`
+3. OpenCode config includes `"plugin": ["@scrylog/opencode-plugin"]`
+4. `SCRYLOG_URL` points to the correct daemon address
+5. `curl http://127.0.0.1:7788/api/health` succeeds
+6. `scrylog doctor` reports `OpenCode mode: hooks`
+
+### The daemon says webhook events were skipped
+
+Your daemon is probably running with `opencode.mode: "sse"`. Switch it to `hooks` if you want this plugin to drive OpenCode updates.
+
+### I want standalone-only OpenCode monitoring instead
+
+Do not use this plugin as the primary integration. Set `opencode.mode` to `sse` in `scrylog` and start OpenCode with a reachable HTTP endpoint or use `oc`.
+
+## Related
+
+- [`scrylog`](https://github.com/scrylog/scrylog) for the dashboard, daemon, API, MCP server, and `oc`
+- Root documentation: [`README.md`](https://github.com/scrylog/scrylog#readme)

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default as server } from "./server";

package/dist/index.js

@@ -0,0 +1 @@
+export { default as server } from "./server";

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const ScrylogServerPlugin: Plugin;
+export default ScrylogServerPlugin;

package/dist/server.js

@@ -0,0 +1,35 @@
+import { getTmuxPane, getWebhookUrl, post, setTmuxSessionOption } from "./shared";
+export const ScrylogServerPlugin = async (input) => {
+    const { client, directory, $ } = input;
+    const webhookUrl = getWebhookUrl();
+    if (getTmuxPane()) {
+        client.session
+            .list()
+            .then(({ data }) => {
+            if (!data?.length)
+                return;
+            const latest = [...data]
+                .filter((s) => !s.parentID)
+                .sort((a, b) => (b.time.updated ?? 0) - (a.time.updated ?? 0))[0];
+            if (latest?.id)
+                setTmuxSessionOption(latest.id, $);
+        })
+            .catch(() => { });
+    }
+    return {
+        event: async ({ event }) => {
+            post(webhookUrl, {
+                event: event.type,
+                directory,
+                ...event.properties,
+            });
+            if (event.type === "session.created" || event.type === "session.updated") {
+                const sessionID = event.properties.info?.id;
+                const parentID = event.properties.info?.parentID;
+                if (typeof sessionID === "string" && !parentID)
+                    setTmuxSessionOption(sessionID, $);
+            }
+        },
+    };
+};
+export default ScrylogServerPlugin;

package/dist/shared.d.ts

@@ -0,0 +1,6 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare const DEFAULT_WEBHOOK_URL = "http://127.0.0.1:7788/api/webhook/opencode";
+export declare function getWebhookUrl(): string;
+export declare function post(webhookUrl: string, body: Record<string, unknown>): void;
+export declare function getTmuxPane(): string | undefined;
+export declare function setTmuxSessionOption(sessionID: string, $?: PluginInput["$"]): void;

package/dist/shared.js

@@ -0,0 +1,31 @@
+export const DEFAULT_WEBHOOK_URL = "http://127.0.0.1:7788/api/webhook/opencode";
+export function getWebhookUrl() {
+    return process.env["SCRYLOG_URL"] ?? DEFAULT_WEBHOOK_URL;
+}
+export function post(webhookUrl, body) {
+    fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }).catch(() => {
+        // Ignore all errors — daemon may not be running
+    });
+}
+export function getTmuxPane() {
+    const pane = process.env["TMUX_PANE"];
+    if (!pane)
+        return undefined;
+    if (!/^%\d+$/.test(pane))
+        return undefined;
+    return pane;
+}
+export function setTmuxSessionOption(sessionID, $) {
+    const tmuxPane = getTmuxPane();
+    if (!tmuxPane || !$)
+        return;
+    $ `tmux set-option -p -t ${tmuxPane} @opencode-session ${sessionID}`
+        .quiet()
+        .catch(() => {
+        // Ignore errors — tmux may not be installed or pane may be gone
+    });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@scrylog/opencode-plugin",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that pushes session events to scrylog daemon",
+  "author": "Joel D. Martinez",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scrylog/scrylog.git",
+    "directory": "packages/opencode-plugin"
+  },
+  "homepage": "https://github.com/scrylog/scrylog/tree/main/packages/opencode-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/scrylog/scrylog/issues"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check-types": "tsc --noEmit",
+    "clean": "rm -rf .turbo && rm -rf dist",
+    "clean:node-modules": "rm -rf node_modules",
+    "dev": "tsc --watch",
+    "prepack": "npm run build",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "scrylog",
+    "hooks",
+    "webhook"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.4.0",
+    "@opencode-ai/sdk": "1.4.10",
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
+  },
+  "peerDependencies": {
+    "@opencode-ai/sdk": "*"
+  }
+}