feat: add SDK v2 support, voice caching, VS Code focus detection, and MCI playback

Introduce four major capabilities in a single coordinated release:

- SDK v2 client shape compatibility: auto-detect v1/v2 session.get and
  tui.showToast call shapes at runtime with transparent fallback, add
  v2 event types (permission.v2.asked, question.v2.asked, etc.) with
  immediate flush for v2 asked events, and expand PluginInput/Session
  types for upstream SDK 1.17.3 surface area.
- Voice caching: new enableVoiceCache, voiceCacheDir, and
  voiceCacheMaxSizeMB config options; LRU-pruned SHA-256-keyed disk
  cache for OpenAI, ElevenLabs, Edge TTS, and SAPI engines.
- VS Code focus detection: recognise VS Code, VS Code Insiders, and
  VSCodium across Windows, macOS, and Linux via TERM_PROGRAM, xdotool
  window class, and expanded known-terminal lists.
- Windows MCI playback: replace System.Windows.Media.MediaPlayer with
  winmm.dll mciSendString for loop-count support and direct PowerShell
  fallback when the OpenCode shell runner is unavailable.

Additional improvements: config hot-reload via file-stat signature
checking, plugin dispose lifecycle cleanup, and updated README
documentation for SDK v2 event surfaces.

Add 5 new test suites (performance-regression, upstream-v2-event-types,
v2-client-shape-compat, voice-caching, vscode-focus) and update
existing tests for MCI playback assertions.

Author: MasuRii

README.md

@@ -18,6 +18,11 @@ A smart voice notification plugin for [OpenCode](https://opencode.ai) with **mul
 
 <img width="1456" height="720" alt="image" src="https://github.com/user-attachments/assets/52ccf357-2548-400b-a346-6362f2fc3180" />
 
+### OpenCode's Built-in Notifications
+
+OpenCode provides basic built-in notifications via its `internal:notifications` interface. These cover simple toast alerts for common events (task completion, errors, permission requests).
+
+**This plugin is for users who want more:** multi-engine TTS voice narration, intelligent delayed reminders with exponential backoff, AI-generated contextual messages, Discord/webhook integration, custom sound themes, focus-aware suppression, and per-project sound customization. If you only need a simple desktop toast, OpenCode's built-in notifications may be sufficient. If you want a fully-featured voice notification experience, this plugin delivers it.
 
 ## Features
 
@@ -45,7 +50,7 @@ The plugin automatically tries multiple TTS engines in order, falling back if on
 - Per-notification type delays (permission requests are more urgent)
 - **Smart Quota Handling**: Automatically falls back to free Edge TTS if ElevenLabs quota is exceeded
 - **Permission Batching**: Multiple simultaneous permission requests are batched into a single notification (e.g., "5 permission requests require your attention")
-- **Question Tool Support** (SDK v1.1.7+): Notifies when the agent asks questions and needs user input
+- **Question Tool Support** (SDK v2 event): Notifies when the agent asks questions and needs user input
 
 ### AI-Generated Messages
 - **Dynamic notifications**: Use a local AI to generate unique, contextual messages instead of preset static ones
@@ -395,16 +400,16 @@ Focus detection suppresses sound and desktop notifications when the terminal is
 |-------|--------|
 | `session.idle` | Agent finished working - notify user |
 | `session.error` | Agent encountered an error - alert user |
-| `permission.asked` | Permission request (SDK v1.1.1+) - alert user |
-| `permission.updated` | Permission request (SDK v1.0.x) - alert user |
+| `permission.asked` | Permission request (SDK v2 event) - alert user |
+| `permission.updated` | Permission request (SDK v1 event) - alert user |
 | `permission.replied` | User responded - cancel pending reminders |
-| `question.asked` | Agent asks question (SDK v1.1.7+) - notify user |
+| `question.asked` | Agent asks question (SDK v2 event) - notify user |
 | `question.replied` | User answered question - cancel pending reminders |
 | `question.rejected` | User dismissed question - cancel pending reminders |
 | `message.updated` | New user message - cancel pending reminders |
 | `session.created` | New session - reset state |
 
-> **Note**: The plugin supports OpenCode SDK v1.0.x, v1.1.x, and v1.1.7+ for backward compatibility.
+> **Note**: OpenCode exposes both v1 and v2 SDK event surfaces. This plugin handles both to maintain backward compatibility. `permission.asked` and `question.asked` are v2 SDK events; `permission.updated` is a v1 SDK event. Both are supported regardless of which version `@opencode-ai/plugin` you use (upstream is currently 1.17.3).
 
 ## Development
 

src/index.ts

@@ -88,6 +88,11 @@ export interface PluginConfig {
   openaiTtsFormat: OpenAITtsFormat;
   openaiTtsSpeed: number;
 
+  // Voice cache
+  enableVoiceCache: boolean;
+  voiceCacheDir: string;
+  voiceCacheMaxSizeMB: number;
+
   // Message pools
   idleTTSMessages: string[];
   permissionTTSMessages: string[];

src/types/config.ts

@@ -31,42 +31,108 @@ export interface Project {
   [key: string]: unknown;
 }
 
+export type ToastVariant = 'info' | 'success' | 'warning' | 'error';
+
+export interface TUIToastPayload {
+  message: string;
+  variant?: ToastVariant;
+  duration?: number;
+  title?: string;
+  directory?: string;
+  workspace?: string;
+}
+
+export interface TUIToastBodyPayload {
+  body: TUIToastPayload;
+}
+
+export type TUIShowToastInput = TUIToastPayload | TUIToastBodyPayload;
+
 export interface TUIClient {
-  showToast(input: {
-    body: {
-      message: string;
-      variant?: 'info' | 'success' | 'warning' | 'error';
-      duration?: number;
-      title?: string;
-    };
-  }): Promise<unknown>;
+  showToast(input?: TUIShowToastInput, ...args: Array<unknown>): Promise<unknown> | unknown;
   [key: string]: unknown;
 }
 
 export interface Session {
   id: string;
+  slug?: string;
   projectID?: string;
+  workspaceID?: string;
   directory?: string;
+  path?: string;
   parentID?: string | null;
   title?: string;
+  agent?: string;
+  model?: {
+    id?: string;
+    providerID?: string;
+    variant?: string;
+    [key: string]: unknown;
+  };
   version?: string;
   status?: string;
+  metadata?: Record<string, unknown>;
   summary?: {
     additions?: number;
     deletions?: number;
     files?: number;
+    diffs?: Array<unknown>;
+    [key: string]: unknown;
+  };
+  cost?: number;
+  tokens?: {
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cache?: {
+      read?: number;
+      write?: number;
+    };
+    [key: string]: unknown;
+  };
+  share?: {
+    url?: string;
+    [key: string]: unknown;
+  };
+  permission?: Array<unknown>;
+  revert?: {
+    messageID?: string;
+    partID?: string;
+    snapshot?: string;
+    diff?: string;
     [key: string]: unknown;
   };
   time?: {
     created?: number;
     updated?: number;
     compacting?: number;
+    archived?: number;
   };
   [key: string]: unknown;
 }
 
+export interface SessionGetV1Input {
+  path: {
+    id: string;
+  };
+  query?: {
+    directory?: string;
+    workspace?: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface SessionGetV2Input {
+  sessionID: string;
+  directory?: string;
+  workspace?: string;
+}
+
+export type SessionGetInput = SessionGetV1Input | SessionGetV2Input;
+export type SessionGetResult = { data?: Session | null } | Session | null | undefined;
+
 export interface SessionClient {
-  get(input: { path: { id: string } }): Promise<{ data?: Session }>;
+  get(input: SessionGetInput, ...args: Array<unknown>): Promise<SessionGetResult> | SessionGetResult;
   [key: string]: unknown;
 }
 
@@ -138,19 +204,63 @@ export interface OpenCodeClient {
   [key: string]: unknown;
 }
 
-export interface PluginInitParams {
+export interface WorkspaceInfo {
+  id: string;
+  type: string;
+  name: string;
+  branch: string | null;
+  directory: string | null;
+  extra: unknown | null;
+  projectID: string;
+}
+
+export type WorkspaceTarget =
+  | {
+      type: 'local';
+      directory: string;
+    }
+  | {
+      type: 'remote';
+      url: string | URL;
+      headers?: Record<string, string>;
+    };
+
+export interface WorkspaceAdapter {
+  name: string;
+  description: string;
+  configure(config: WorkspaceInfo): WorkspaceInfo | Promise<WorkspaceInfo>;
+  create(config: WorkspaceInfo, env: Record<string, string | undefined>, from?: WorkspaceInfo): Promise<void>;
+  remove(config: WorkspaceInfo): Promise<void>;
+  target(config: WorkspaceInfo): WorkspaceTarget | Promise<WorkspaceTarget>;
+}
+
+export interface ExperimentalWorkspaceRegistry {
+  register(type: string, adapter: WorkspaceAdapter): void;
+}
+
+export interface PluginInput {
   project: Project;
   client: OpenCodeClient;
   $: ShellRunner;
   directory: string;
   worktree: string;
   serverUrl?: URL;
+  experimental_workspace?: ExperimentalWorkspaceRegistry;
 }
 
+export type PluginInitParams = PluginInput;
+
 export type EventType =
   | 'server.instance.disposed'
+  | 'global.disposed'
+  | 'models-dev.refreshed'
+  | 'plugin.added'
+  | 'catalog.model.updated'
   | 'installation.updated'
   | 'installation.update-available'
+  | 'account.added'
+  | 'account.removed'
+  | 'account.switched'
   | 'lsp.client.diagnostics'
   | 'lsp.updated'
   | 'message.updated'
@@ -160,10 +270,15 @@ export type EventType =
   | 'message.part.removed'
   | 'permission.updated'
   | 'permission.asked'
+  | 'permission.v2.asked'
   | 'permission.replied'
+  | 'permission.v2.replied'
   | 'question.asked'
+  | 'question.v2.asked'
   | 'question.replied'
+  | 'question.v2.replied'
   | 'question.rejected'
+  | 'question.v2.rejected'
   | 'session.status'
   | 'session.idle'
   | 'session.compacted'
@@ -172,14 +287,52 @@ export type EventType =
   | 'session.deleted'
   | 'session.diff'
   | 'session.error'
+  | 'session.next.agent.switched'
+  | 'session.next.model.switched'
+  | 'session.next.moved'
+  | 'session.next.prompted'
+  | 'session.next.prompt.admitted'
+  | 'session.next.prompt.promoted'
+  | 'session.next.interrupt.requested'
+  | 'session.next.context.updated'
+  | 'session.next.synthetic'
+  | 'session.next.shell.started'
+  | 'session.next.shell.ended'
+  | 'session.next.step.started'
+  | 'session.next.step.ended'
+  | 'session.next.step.failed'
+  | 'session.next.text.started'
+  | 'session.next.text.ended'
+  | 'session.next.reasoning.started'
+  | 'session.next.reasoning.ended'
+  | 'session.next.tool.input.started'
+  | 'session.next.tool.input.ended'
+  | 'session.next.tool.called'
+  | 'session.next.tool.progress'
+  | 'session.next.tool.success'
+  | 'session.next.tool.failed'
+  | 'session.next.retried'
+  | 'session.next.compaction.started'
+  | 'session.next.compaction.ended'
   | 'todo.updated'
   | 'command.executed'
   | 'file.edited'
   | 'file.watcher.updated'
+  | 'reference.updated'
+  | 'project.directories.updated'
+  | 'project.updated'
   | 'vcs.branch.updated'
+  | 'worktree.ready'
+  | 'worktree.failed'
+  | 'workspace.ready'
+  | 'workspace.failed'
+  | 'workspace.status'
   | 'tui.prompt.append'
   | 'tui.command.execute'
   | 'tui.toast.show'
+  | 'tui.session.select'
+  | 'mcp.tools.changed'
+  | 'mcp.browser.open.failed'
   | 'pty.created'
   | 'pty.updated'
   | 'pty.exited'
@@ -194,14 +347,34 @@ export interface EventProperties {
   partID?: string;
   permissionID?: string;
   requestID?: string;
+  callID?: string;
   id?: string;
   info?: unknown;
   error?: unknown;
   response?: string;
   reply?: string;
   status?: unknown;
+  action?: string;
+  resources?: Array<string>;
+  save?: Array<string> | boolean;
+  metadata?: Record<string, unknown>;
+  source?: string;
+  permission?: string;
+  patterns?: Array<string>;
+  always?: Array<string>;
   questions?: Array<unknown>;
-  answers?: Array<Array<string>>;
+  answers?: Array<Array<string>> | Array<unknown>;
+  tool?: unknown;
+  file?: string;
+  event?: string;
+  command?: string;
+  arguments?: string;
+  version?: string;
+  branch?: string;
+  title?: string;
+  message?: string;
+  variant?: ToastVariant;
+  duration?: number;
   [key: string]: unknown;
 }
 
@@ -212,5 +385,6 @@ export interface PluginEvent {
 
 export interface PluginHandlers {
   event?: (input: { event: PluginEvent }) => Promise<void>;
+  dispose?: () => void | Promise<void>;
   [key: string]: unknown;
 }

src/types/opencode-sdk.ts

@@ -164,6 +164,9 @@ export const getDefaultConfigObject = (): PluginConfig => ({
   openaiTtsVoice: 'alloy',
   openaiTtsFormat: 'mp3',
   openaiTtsSpeed: 1.0,
+  enableVoiceCache: false,
+  voiceCacheDir: 'voice-cache',
+  voiceCacheMaxSizeMB: 100,
   idleTTSMessages: [
     'All done! Your task has been completed successfully.',
     'Hey there! I finished working on your request.',
@@ -559,6 +562,21 @@ const generateDefaultConfig = (overrides: Partial<PluginConfig> = {}, version =
     // Speech speed: 0.25 to 4.0 (1.0 = normal)
     "openaiTtsSpeed": ${overrides.openaiTtsSpeed !== undefined ? overrides.openaiTtsSpeed : 1.0},
     
+    // ============================================================
+    // VOICE CACHE SETTINGS (Optional local TTS audio cache)
+    // ============================================================
+    // Cache generated TTS audio locally so repeated messages can replay
+    // without calling cloud/self-hosted TTS services again.
+    // Disabled by default to preserve existing behavior and disk usage.
+    "enableVoiceCache": ${overrides.enableVoiceCache !== undefined ? overrides.enableVoiceCache : false},
+    
+    // Directory for cached voice audio. Relative paths are resolved from
+    // ~/.config/opencode/; absolute paths are used as-is.
+    "voiceCacheDir": ${JSON.stringify(overrides.voiceCacheDir !== undefined ? overrides.voiceCacheDir : 'voice-cache')},
+    
+    // Maximum cache size in megabytes. Oldest cached audio is removed first.
+    "voiceCacheMaxSizeMB": ${overrides.voiceCacheMaxSizeMB !== undefined ? overrides.voiceCacheMaxSizeMB : 100},
+    
     // ============================================================
     // INITIAL TTS MESSAGES (Used immediately or after sound)
     // These are randomly selected each time for variety