@nm156/opencode-notifier 0.3.1 → 0.4.0

package/README.md

@@ -1,35 +1,50 @@
 # opencode-notifier
 
 > [!NOTE]
-> This is a fork of [`@mohak34/opencode-notifier`](https://github.com/mohak34/opencode-notifier) that adds
-> OpenCode 2 support from [mohak34/opencode-notifier#110](https://github.com/mohak34/opencode-notifier/pull/110),
-> rebased onto 0.3.0. Use the upstream package once it supports OpenCode 2.
+> This is a fork of [`@mohak34/opencode-notifier`](https://github.com/mohak34/opencode-notifier) 0.4.0 that adds a
+> `{sessionID}` custom command placeholder from
+> [mohak34/opencode-notifier#124](https://github.com/mohak34/opencode-notifier/pull/124). Use the upstream package once
+> it includes that change.
 
 OpenCode plugin that plays sounds and sends system notifications when permission is needed, generation completes, errors occur, or the question tool is invoked. Works on macOS, Linux, and Windows.
 
 ## Quick Start
 
-Install the plugin via the CLI: `opencode plug -g @nm156/opencode-notifier`.
+For OpenCode 1, add the package to `opencode.json`:
 
-Or add manually to your `opencode.json`:
+```json
+{
+  "plugin": ["@nm156/opencode-notifier@latest"]
+}
+```
 
-  ```json
-  {
-    "plugin": ["@nm156/opencode-notifier@latest"]
-  }
-  ```
+For OpenCode 2, use `plugins`:
 
-Restart OpenCode. Done.
+```json
+{
+  "plugins": ["@nm156/opencode-notifier@latest"]
+}
+```
 
-## OpenCode version support
+Restart OpenCode. The package contains both implementations; you do not select a version manually. V2 loads the package's terminal component automatically in the interactive CLI.
 
-This plugin supports both OpenCode 1 and OpenCode 2 from the same package:
+### OpenCode 2 delivery
 
-- **OpenCode 1** loads the legacy `server()` entrypoint.
-- **OpenCode 2** loads the `setup()` entrypoint introduced with the V2 plugin API.
+Sounds, desktop popups, terminal bells, Ghostty notifications, and focus detection run in the terminal client. Custom commands run once per event on the server, including when no terminal is open. This uses the existing `command` configuration; no external notification service is bundled.
 
-Install it the same way for both. On OpenCode 2, `opencode notifier` appears in `opencode plugin list` without any
-extra configuration.
+With a remote server, put sound and popup settings on your local computer and custom-command settings on the server. Script paths refer to the server's filesystem. Focus suppression applies to local alerts, not server commands. Each attached terminal receives alerts for its project.
+
+`opencode run` and Desktop/Web clients do not load this terminal component, so they receive no plugin sound, popup, or bell. Server commands still run. V1 delivery and its `enableOnDesktop` behavior are unchanged.
+
+V2 already includes a notification plugin. To avoid duplicate built-in alerts, add `"-opencode.notifications"` to the existing `plugins` list in `~/.config/opencode/cli.json`:
+
+```json
+{
+  "plugins": ["*", "-opencode.notifications"]
+}
+```
+
+Keep any other entries in that list. `plan_exit` remains a V1 event; V2 has no equivalent plan-ready signal, so that setting is inactive there. `client_connected` is best-effort: terminal startup for local alerts, server plugin startup for custom commands.
 
 ## What it does
 
@@ -184,7 +199,7 @@ Create `~/.config/opencode/opencode-notifier.json` with the defaults:
 - `showIcon` - Show OpenCode icon, Windows/Linux only (default: true)
 - `customIconPath` - Path to a custom icon for notifications. Useful on WSL where Windows paths are needed (default: null)
 - `suppressWhenFocused` - Skip notifications and sounds when the terminal is the active window (default: true). See [Focus detection](#focus-detection) for platform details
-- `enableOnDesktop` - Run the plugin on Desktop and Web clients (default: false). When false, the plugin only runs on CLI. Set to true if you want notifications/sounds/commands on Desktop/Web — useful if you want custom commands (Telegram, webhooks) but don't care about built-in notifications
+- `enableOnDesktop` - V1 only: run the plugin on Desktop and Web clients (default: false). V2 runs commands on the server and local alerts in its terminal component; this flag does not control V2 delivery.
 - `notificationSystem` - macOS only: `"osascript"`, `"node-notifier"`, or `"ghostty"` (default: "osascript"). Use `"ghostty"` if you're running Ghostty terminal for native OSC 9 notifications
 - `suppressGhosttySound` - macOS only: when `true` with `notificationSystem: "ghostty"`, skips the plugin's sound to avoid duplicating macOS Notification Center's default sound (default: false)
 - `minDuration` - Suppress `complete` and `subagent_complete` notifications when session finishes faster than this many seconds (default: 0). See [Minimum duration threshold](#minimum-duration-threshold)
@@ -213,7 +228,7 @@ Control each event separately:
 
 `user_cancelled` fires when you press ESC to abort a session. It's silent by default so intentional cancellations don't trigger error alerts. Set `sound` or `notification` to `true` if you want confirmation when cancelling.
 
-`session_started` fires when a new top-level session is created. `user_message` fires when a user message is submitted in a top-level session. `client_connected` fires shortly after the plugin initializes and is best-effort (there is no dedicated SDK connection event from plugin context).
+`session_started` fires when a new top-level session is created. `user_message` fires when a user message is submitted in a top-level session. `client_connected` is best-effort. On V1 it fires shortly after plugin initialization. On V2, terminal initialization triggers local alerts and server plugin initialization triggers the custom command; it does not track every client reconnection.
 
 The `command` property controls whether the custom command (see [Custom commands](#custom-commands)) runs for that event. Defaults to `true` for all events. Set it to `false` to suppress the command for specific events without disabling it globally.
 
@@ -318,7 +333,7 @@ Set per-event volume from `0` to `1`:
 
 ### Custom commands
 
-Run your own script when something happens. Use `{event}`, `{message}`, `{sessionTitle}`, `{agentName}`, `{projectName}`, `{timestamp}`, and `{turn}` as placeholders:
+Run your own script when something happens. Use `{event}`, `{message}`, `{sessionTitle}`, `{sessionID}`, `{agentName}`, `{projectName}`, `{timestamp}`, and `{turn}` as placeholders:
 
 ```json
 {
@@ -333,9 +348,11 @@ Run your own script when something happens. Use `{event}`, `{message}`, `{sessio
 
 - `enabled` - Turn command on/off
 - `path` - Path to your script/executable
-- `args` - Arguments to pass, can use `{event}`, `{message}`, `{sessionTitle}`, `{agentName}`, `{projectName}`, `{timestamp}`, and `{turn}` tokens
+- `args` - Arguments to pass, can use `{event}`, `{message}`, `{sessionTitle}`, `{sessionID}`, `{agentName}`, `{projectName}`, `{timestamp}`, and `{turn}` tokens
 - `minDuration` - Skip if response was quick, avoids spam (seconds)
 
+`{sessionID}` is the ID of the session that triggered the event (e.g. `ses_0048b8aa...`), so a script can tell concurrent sessions in the same project apart. It is empty for events without a session, such as `client_connected`.
+
 Token values are passed as argv values and are not shell-escaped for use inside
 script source. Do not put `{message}`, `{sessionTitle}`, or other dynamic tokens
 inside a `sh -c`, `bash -c`, `powershell -Command`, or similar script string.
@@ -663,13 +680,23 @@ This is a known Bun issue on Windows. Disable native notifications and use Power
 **Plugin installed but no notifications/sounds?**
 
 - Check `suppressWhenFocused`: when `true` (default), notifications are skipped while OpenCode terminal is focused. Set to `false` to always notify.
-- Check `enableOnDesktop`: defaults to `false`, so the plugin won't run on Desktop/Web clients. Set to `true` if you need it there.
+- On V1, check `enableOnDesktop`: it defaults to `false`. On V2, Desktop/Web and headless clients use server commands; local sounds and popups require the terminal component described above.
 - Verify the package version OpenCode cached:
   ```bash
   cat ~/.cache/opencode/packages/@nm156/opencode-notifier@latest/node_modules/@nm156/opencode-notifier/package.json | grep version
   ```
   If you use `@beta` or a pinned version, replace `latest` in the path with `beta` or the exact version.
 
+## TypeScript imports
+
+Loading this plugin through OpenCode configuration does not require installing SDKs separately. If a TypeScript project imports the package directly, its declarations reference both OpenCode SDK generations. Install the optional type peers in that project:
+
+```bash
+bun add -d '@opencode-ai/plugin@^1.18.25' '@opencode/plugin@^2.0.18' '@opencode/client@^2.0.18'
+```
+
+These peers are optional to keep runtime-only installs lightweight. They are not automatically installed, so a V1-only TypeScript project importing the dual entrypoint also needs the V2 type peers. Adding peer metadata alone does not resolve missing type packages.
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md)

package/dist/bell.d.ts

@@ -0,0 +1,2 @@
+export declare function ringBell(now?: number): Promise<void>;
+export declare function resetBellState(): void;

package/dist/command.d.ts

@@ -0,0 +1,2 @@
+import type { EventType, NotifierConfig } from "./config";
+export declare function runCommand(config: NotifierConfig, event: EventType, message: string, sessionTitle?: string | null, agentName?: string | null, projectName?: string | null, timestamp?: string | null, turn?: number | null, sessionID?: string | null): void;

package/dist/config.d.ts

@@ -0,0 +1,109 @@
+export type EventType = "permission" | "complete" | "subagent_complete" | "error" | "question" | "interrupted" | "user_cancelled" | "plan_exit" | "session_started" | "user_message" | "client_connected";
+export interface EventConfig {
+    sound: boolean;
+    notification: boolean;
+    command: boolean;
+    bell: boolean;
+}
+export interface CommandConfig {
+    enabled: boolean;
+    path: string;
+    args?: string[];
+    minDuration?: number;
+}
+export interface LinuxConfig {
+    grouping: boolean;
+}
+export interface WindowsConfig {
+    appID: string;
+}
+export interface MessageContext {
+    sessionTitle?: string | null;
+    agentName?: string | null;
+    projectName?: string | null;
+    timestamp?: string | null;
+    turn?: number | null;
+}
+export interface NotifierConfig {
+    sound: boolean;
+    notification: boolean;
+    bell: boolean;
+    timeout: number;
+    showProjectName: boolean;
+    showFullPath: boolean;
+    showSessionTitle: boolean;
+    showIcon: boolean;
+    customIconPath: string | null;
+    suppressWhenFocused: boolean;
+    enableOnDesktop: boolean;
+    notificationSystem: "osascript" | "node-notifier" | "ghostty";
+    suppressGhosttySound: boolean;
+    linux: LinuxConfig;
+    windows: WindowsConfig;
+    minDuration: number;
+    command: CommandConfig;
+    events: {
+        permission: EventConfig;
+        complete: EventConfig;
+        subagent_complete: EventConfig;
+        error: EventConfig;
+        question: EventConfig;
+        interrupted: EventConfig;
+        user_cancelled: EventConfig;
+        plan_exit: EventConfig;
+        session_started: EventConfig;
+        user_message: EventConfig;
+        client_connected: EventConfig;
+    };
+    messages: {
+        permission: string;
+        complete: string;
+        subagent_complete: string;
+        error: string;
+        question: string;
+        interrupted: string;
+        user_cancelled: string;
+        plan_exit: string;
+        session_started: string;
+        user_message: string;
+        client_connected: string;
+    };
+    sounds: {
+        permission: string | null;
+        complete: string | null;
+        subagent_complete: string | null;
+        error: string | null;
+        question: string | null;
+        interrupted: string | null;
+        user_cancelled: string | null;
+        plan_exit: string | null;
+        session_started: string | null;
+        user_message: string | null;
+        client_connected: string | null;
+    };
+    volumes: {
+        permission: number;
+        complete: number;
+        subagent_complete: number;
+        error: number;
+        question: number;
+        interrupted: number;
+        user_cancelled: number;
+        plan_exit: number;
+        session_started: number;
+        user_message: number;
+        client_connected: number;
+    };
+}
+export declare function getConfigPath(): string;
+export declare function getStatePath(): string;
+export declare function loadConfig(): NotifierConfig;
+export declare function isEventSoundEnabled(config: NotifierConfig, event: EventType): boolean;
+export declare function isEventNotificationEnabled(config: NotifierConfig, event: EventType): boolean;
+export declare function isEventCommandEnabled(config: NotifierConfig, event: EventType): boolean;
+export declare function isEventBellEnabled(config: NotifierConfig, event: EventType): boolean;
+export declare function getMessage(config: NotifierConfig, event: EventType): string;
+export declare function getSoundPath(config: NotifierConfig, event: EventType): string | null;
+export declare function getSoundVolume(config: NotifierConfig, event: EventType): number;
+export declare function getIconPath(config: NotifierConfig): string | undefined;
+export declare function interpolateMessage(message: string, context: MessageContext): string;

package/dist/delivery.d.ts

@@ -0,0 +1,4 @@
+import type { EventType, NotifierConfig } from "./config";
+export declare function extractAgentNameFromSessionTitle(sessionTitle: unknown): string;
+export declare function shouldResolveAgentNameForEvent(config: NotifierConfig, eventType: EventType): boolean;
+export declare function handleEvent(config: NotifierConfig, eventType: EventType, projectName: string | null, elapsedSeconds?: number | null, sessionTitle?: string | null, sessionID?: string | null, agentName?: string | null): Promise<void>;

package/dist/focus.d.ts

@@ -0,0 +1,34 @@
+export declare function parseWezTermFocusedPaneId(output: string): string | null;
+export declare function isGnomeLikeSession(env?: NodeJS.ProcessEnv): boolean;
+export declare function getLinuxFocusBackendName(env?: NodeJS.ProcessEnv): string;
+export declare function parseAtspiString(output: string | null): string | null;
+export interface AtspiObjectRef {
+    bus: string;
+    path: string;
+}
+export declare function parseAtspiObjectRefs(output: string | null): AtspiObjectRef[];
+export declare function parseAtspiStateActive(output: string | null): boolean | null;
+export declare function isAtspiTerminalWindow(appName: string | null, windowPath: string): boolean;
+export declare function isAtspiWindowRoleAccepted(role: string | null): boolean;
+export declare function getGnomeAtspiActiveWindowKey(): string | null;
+export declare function debugFocusState(message: string): void;
+export declare function buildOsascriptActivateAppArgs(appName: string): string[];
+export declare function isMacTerminalAppFocused(frontmostAppName: string | null, env?: NodeJS.ProcessEnv): boolean;
+export declare function getCachedWindowTitle(): string | null;
+export declare function isTmuxPaneFocused(tmuxPane: string | null | undefined, probeResult: string | null): boolean;
+export declare function isLinuxTerminalFocused(params: {
+    cachedWindowId: string | null;
+    currentWindowId: string | null;
+    wezTermPaneActive: boolean;
+    tmuxPaneActive: boolean | null;
+}): boolean;
+export declare function isWindowsTerminalFocused(params: {
+    className: string | null;
+    processName: string | null;
+}): boolean;
+export declare function isTerminalFocused(): boolean;
+export declare function isKDEJumpBackSupported(): boolean;
+export declare function findQdbusBinary(candidates?: readonly string[], isExecutable?: (name: string) => boolean): string | null;
+export declare function resolveQdbusBinary(): string | null;
+export declare function captureStartupWindowId(): void;
+export declare function focusTerminal(): Promise<void>;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export { extractAgentNameFromSessionTitle } from "./delivery";
+export { PERMISSION_PENDING_GRACE_MS } from "./notifier";
+export declare function isCLIClient(clientEnv?: string): boolean;
+export declare function getPermissionIDFromEvent(event: unknown): string | null;
+export declare function isPermissionStillPending(client: unknown, permissionID: string): Promise<boolean>;
+export declare const NotifierPlugin: Plugin;
+declare const _default: {
+    id: string;
+    server: Plugin;
+    setup: (context: import("@opencode/plugin/promise/plugin").Context) => Promise<import("@opencode/plugin/promise/plugin").Cleanup | void> | import("@opencode/plugin/promise/plugin").Cleanup | void;
+};
+export default _default;