api

Author: kommander

packages/opencode/specs/tui-plugins.md

@@ -264,13 +264,14 @@ Top-level API groups exposed to `tui(api, options, meta)`:
 
 ### Attention
 
-- `api.attention.notify({ title?, message, sound?, when? })` requests user attention while keeping terminal focus, notifications, and audio owned by the host.
-- `message` is required; `title` defaults to `"opencode"`; `when` defaults to `"always"`; `sound` defaults to `false`.
+- `api.attention.notify({ title?, message, notification?, sound? })` requests user attention while keeping terminal focus, notifications, and audio owned by the host.
+- `message` is required; `title` defaults to `"opencode"`; `notification` defaults to enabled with `when: "blurred"`; `sound` defaults to enabled with `when: "always"`.
 - `when: "always"` requests delivery regardless of terminal focus state.
 - `when: "focused"` only requests delivery after the terminal is known focused; `when: "blurred"` only requests delivery after the terminal is known blurred.
+- Example: `notification: { when: "blurred" }, sound: { name: "question", when: "always" }` plays sound while focused but only triggers system notifications when blurred.
 - Semantic sound names are `"default"`, `"question"`, `"permission"`, `"error"`, and `"done"`.
-- `sound: true` plays the `"default"` sound; `sound: "question"` or `sound: { name: "question" }` plays a named semantic sound.
-- `sound: { volume }` overrides volume for that call; `sound: { enabled: false }` disables sound for that call.
+- `sound: true` plays the `"default"` sound; `sound: { name: "question" }` plays a named semantic sound.
+- `sound: { volume }` overrides volume for that call; `sound: false` disables sound for that call; `notification: false` disables system notification for that call.
 - `api.attention.soundboard.registerPack({ id, name?, sounds })` registers a sound pack and returns a disposer. Relative paths resolve from the plugin root and are cleaned up on plugin deactivation.
 - `api.attention.soundboard.activate(id, { persist })` selects the active pack. `persist: true` writes the selected pack id to TUI KV state, not `tui.json`.
 - `api.attention.soundboard.current()` and `list()` expose the active/registered packs for plugin UX.

packages/opencode/src/cli/cmd/tui/attention.ts

@@ -4,6 +4,7 @@ import type {
   TuiAttentionNotifyInput,
   TuiAttentionNotifyResult,
   TuiAttentionNotifySkipReason,
+  TuiAttentionWhen,
   TuiKV,
   TuiAttentionSoundName,
   TuiAttentionSoundPack,
@@ -95,19 +96,32 @@ function clampVolume(volume: number) {
 
 function soundVolume(input: TuiAttentionNotifyInput, config: Pick<TuiConfig.Resolved, "attention">) {
   if (!config.attention.sound) return
-  if (input.sound === undefined || input.sound === false) return
+  if (input.sound === false) return
+  if (input.sound === undefined) return clampVolume(config.attention.volume)
   if (input.sound === true) return clampVolume(config.attention.volume)
-  if (typeof input.sound === "string") return clampVolume(config.attention.volume)
-  if (input.sound.enabled === false) return
   return clampVolume(input.sound.volume ?? config.attention.volume)
 }
 
 function soundName(input: TuiAttentionNotifyInput): TuiAttentionSoundName {
-  if (typeof input.sound === "string") return isSoundName(input.sound) ? input.sound : "default"
   if (typeof input.sound === "object") return input.sound.name && isSoundName(input.sound.name) ? input.sound.name : "default"
   return "default"
 }
 
+function notificationEnabled(input: TuiAttentionNotifyInput) {
+  if (input.notification === false) return false
+  return true
+}
+
+function notificationWhen(input: TuiAttentionNotifyInput) {
+  if (typeof input.notification === "object" && input.notification.when) return input.notification.when
+  return "blurred"
+}
+
+function soundWhen(input: TuiAttentionNotifyInput) {
+  if (typeof input.sound === "object" && input.sound.when) return input.sound.when
+  return "always"
+}
+
 function isSoundName(value: string): value is TuiAttentionSoundName {
   return SOUND_NAMES.includes(value as TuiAttentionSoundName)
 }
@@ -127,8 +141,8 @@ function normalizePack(pack: TuiAttentionSoundPack): RegisteredSoundPack | undef
   }
 }
 
-function focusSkip(when: TuiAttentionNotifyInput["when"], focus: FocusState) {
-  if ((when ?? "always") === "always") return
+function focusSkip(when: TuiAttentionWhen, focus: FocusState) {
+  if (when === "always") return
   if (focus === "unknown") return "focus_unknown"
   if (when === "blurred" && focus === "focused") return "focused"
   if (when === "focused" && focus === "blurred") return "blurred"
@@ -225,10 +239,10 @@ export function createTuiAttention(input: {
         const message = normalizeText(request.message, "", MESSAGE_LIMIT)
         if (!message) return skipped("empty_message")
 
-        const skip = focusSkip(request.when, focus)
-        if (skip) return skipped(skip)
-
-        const notification = input.config.attention.notifications
+        const notificationSkip = focusSkip(notificationWhen(request), focus)
+        const notificationRequested = input.config.attention.notifications && notificationEnabled(request)
+        const shouldNotify = notificationRequested && !notificationSkip
+        const notification = shouldNotify
           ? (() => {
               try {
                 return input.renderer.triggerNotification(message, normalizeText(request.title, DEFAULT_TITLE, TITLE_LIMIT))
@@ -239,7 +253,13 @@ export function createTuiAttention(input: {
             })()
           : false
         const volume = soundVolume(request, input.config)
-        const sound = volume === undefined ? false : await playSound(soundName(request), volume)
+        const soundSkip = volume === undefined ? undefined : focusSkip(soundWhen(request), focus)
+        const sound = volume === undefined || soundSkip ? false : await playSound(soundName(request), volume)
+
+        if (!notification && !sound) {
+          if (notificationRequested && notificationSkip) return skipped(notificationSkip)
+          if (soundSkip) return skipped(soundSkip)
+        }
 
         return {
           ok: notification || sound,

packages/opencode/test/cli/cmd/tui/attention.test.ts

@@ -143,17 +143,17 @@ function config(attention: Partial<AttentionConfig["attention"]> = {}): Attentio
 }
 
 describe("createTuiAttention", () => {
-  test("defaults to always and delivers before focus is known", async () => {
+  test("defaults to sound always and notification blurred", async () => {
     const renderer = new FakeRenderer()
     const audio = new FakeAudio()
     const attention = createTuiAttention({ renderer, config: config(), audio })
 
-    expect(await attention.notify({ message: "hello", sound: true })).toEqual({
+    expect(await attention.notify({ message: "hello" })).toEqual({
       ok: true,
-      notification: true,
+      notification: false,
       sound: true,
     })
-    expect(renderer.notifications).toEqual([{ title: "opencode", message: "hello" }])
+    expect(renderer.notifications).toHaveLength(0)
     expect(audio.createCalls).toBe(1)
   })
 
@@ -162,21 +162,21 @@ describe("createTuiAttention", () => {
     const audio = new FakeAudio()
     const attention = createTuiAttention({ renderer, config: config(), audio })
 
-    expect(await attention.notify({ message: "unknown", sound: true, when: "blurred" })).toEqual({
+    expect(await attention.notify({ message: "unknown", sound: { when: "blurred" } })).toEqual({
       ok: false,
       notification: false,
       sound: false,
       skipped: "focus_unknown",
     })
     renderer.emit("focus")
-    expect(await attention.notify({ message: "focused", sound: true, when: "blurred" })).toEqual({
+    expect(await attention.notify({ message: "focused", sound: { when: "blurred" } })).toEqual({
       ok: false,
       notification: false,
       sound: false,
       skipped: "focused",
     })
     renderer.emit("blur")
-    expect(await attention.notify({ message: "blurred", sound: true, when: "blurred" })).toEqual({
+    expect(await attention.notify({ message: "blurred", sound: { when: "blurred" } })).toEqual({
       ok: true,
       notification: true,
       sound: true,
@@ -188,35 +188,35 @@ describe("createTuiAttention", () => {
     const renderer = new FakeRenderer()
     const attention = createTuiAttention({ renderer, config: config(), audio: new FakeAudio() })
 
-    expect(await attention.notify({ message: "unknown", when: "focused" })).toEqual({
+    expect(await attention.notify({ message: "unknown", notification: { when: "focused" }, sound: false })).toEqual({
       ok: false,
       notification: false,
       sound: false,
       skipped: "focus_unknown",
     })
     renderer.emit("blur")
-    expect(await attention.notify({ message: "blurred", when: "focused" })).toEqual({
+    expect(await attention.notify({ message: "blurred", notification: { when: "focused" }, sound: false })).toEqual({
       ok: false,
       notification: false,
       sound: false,
       skipped: "blurred",
     })
     renderer.emit("focus")
-    expect(await attention.notify({ message: "focused", when: "focused" })).toEqual({
+    expect(await attention.notify({ message: "focused", notification: { when: "focused" }, sound: false })).toEqual({
       ok: true,
       notification: true,
       sound: false,
     })
     expect(renderer.notifications).toEqual([{ title: "opencode", message: "focused" }])
   })
 
-  test("always requests still deliver while focused", async () => {
+  test("notification can deliver while focused when requested", async () => {
     const renderer = new FakeRenderer()
     const audio = new FakeAudio()
     const attention = createTuiAttention({ renderer, config: config(), audio })
     renderer.emit("focus")
 
-    expect(await attention.notify({ message: "hello", sound: true })).toEqual({
+    expect(await attention.notify({ message: "hello", notification: { when: "always" } })).toEqual({
       ok: true,
       notification: true,
       sound: true,
@@ -230,7 +230,7 @@ describe("createTuiAttention", () => {
     const attention = createTuiAttention({ renderer, config: config(), audio: new FakeAudio() })
     renderer.emit("blur")
 
-    expect(await attention.notify({ title: "opencode", message: "hello" })).toEqual({
+    expect(await attention.notify({ title: "opencode", message: "hello", sound: false })).toEqual({
       ok: true,
       notification: true,
       sound: false,
@@ -244,7 +244,7 @@ describe("createTuiAttention", () => {
     const attention = createTuiAttention({ renderer, config: config(), audio })
     renderer.emit("focus")
 
-    expect(await attention.notify({ message: "hello", sound: true, when: "blurred" })).toEqual({
+    expect(await attention.notify({ message: "hello", sound: { when: "blurred" } })).toEqual({
       ok: false,
       notification: false,
       sound: false,
@@ -254,6 +254,53 @@ describe("createTuiAttention", () => {
     expect(audio.createCalls).toBe(0)
   })
 
+  test("can play sound always while notification is blurred-only", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudio()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+    renderer.emit("focus")
+
+    expect(
+      await attention.notify({
+        message: "hello",
+        sound: { name: "question" },
+      }),
+    ).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.createCalls).toBe(1)
+
+    renderer.emit("blur")
+    expect(
+      await attention.notify({
+        message: "hello again",
+        sound: { name: "question" },
+      }),
+    ).toEqual({
+      ok: true,
+      notification: true,
+      sound: true,
+    })
+    expect(renderer.notifications).toEqual([{ title: "opencode", message: "hello again" }])
+  })
+
+  test("can disable notification per call while still playing sound", async () => {
+    const renderer = new FakeRenderer()
+    const audio = new FakeAudio()
+    const attention = createTuiAttention({ renderer, config: config(), audio })
+
+    expect(await attention.notify({ message: "hello", notification: false })).toEqual({
+      ok: true,
+      notification: false,
+      sound: true,
+    })
+    expect(renderer.notifications).toHaveLength(0)
+    expect(audio.createCalls).toBe(1)
+  })
+
   test("skips empty messages and disabled attention", async () => {
     const empty = new FakeRenderer()
     empty.emit("blur")
@@ -312,7 +359,7 @@ describe("createTuiAttention", () => {
     const audio = new FakeAudio()
     const attention = createTuiAttention({ renderer, config: config(), audio })
 
-    await attention.notify({ message: "unknown", sound: true, when: "blurred" })
+    await attention.notify({ message: "unknown", sound: { when: "blurred" } })
     expect(audio.createCalls).toBe(0)
 
     renderer.emit("blur")
@@ -409,7 +456,7 @@ describe("createTuiAttention", () => {
     })
     attention.soundboard.activate("acme.soft")
 
-    expect(await attention.notify({ message: "question", sound: "question" })).toEqual({
+    expect(await attention.notify({ message: "question", sound: { name: "question" } })).toEqual({
       ok: true,
       notification: true,
       sound: true,

packages/plugin/src/tui.ts

@@ -231,11 +231,16 @@ export type TuiAttentionSoundName = "default" | "question" | "permission" | "err
 
 export type TuiAttentionSound =
   | boolean
-  | TuiAttentionSoundName
   | {
-      enabled?: boolean
       name?: TuiAttentionSoundName
       volume?: number
+      when?: TuiAttentionWhen
+    }
+
+export type TuiAttentionNotification =
+  | boolean
+  | {
+      when?: TuiAttentionWhen
     }
 
 export type TuiAttentionSoundPack = {
@@ -265,8 +270,8 @@ export type TuiAttentionSoundboard = {
 export type TuiAttentionNotifyInput = {
   title?: string
   message: string
+  notification?: TuiAttentionNotification
   sound?: TuiAttentionSound
-  when?: TuiAttentionWhen
 }
 
 export type TuiAttentionNotifySkipReason =