opencode-termux-notify 0.1.0

package/src/dedup.ts

@@ -0,0 +1,58 @@
+import { readFile, writeFile, rename } from "node:fs/promises"
+import type { ResolvedOpts } from "./types.js"
+
+type SharedState = {
+  seen: Record<string, number>
+  lastBySession: Record<string, number>
+  lastGlobal: number
+}
+
+export async function shouldNotifyShared(evtId: string, sessionKey: string, opts: ResolvedOpts): Promise<boolean> {
+  const now = Date.now()
+  let state: SharedState = {
+    seen: {},
+    lastBySession: {},
+    lastGlobal: 0,
+  }
+  try {
+    const raw = await readFile(opts.sharedPath, "utf8")
+    state = JSON.parse(raw)
+    for (const [k, exp] of Object.entries(state.seen || {})) {
+      if (now > exp) delete state.seen[k]
+    }
+  } catch {}
+  state.seen ??= {}
+  state.lastBySession ??= {}
+
+  if (evtId && state.seen[evtId] && now < (state.seen[evtId] as number)) return false
+
+  const lastForKey: number = state.lastBySession[sessionKey] || 0
+  if (now - lastForKey < opts.sessionCooldown) return false
+  if (now - (state.lastGlobal || 0) < opts.globalCooldown) return false
+
+  if (evtId) state.seen[evtId] = now + opts.seenTTL
+  state.lastBySession[sessionKey] = now
+  state.lastGlobal = now
+
+  const seenKeys = Object.keys(state.seen)
+  if (seenKeys.length > 300) {
+    const sorted = seenKeys.sort((a, b) => (state.seen[b] as number) - (state.seen[a] as number))
+    const keep = new Set(sorted.slice(0, 200))
+    for (const k of seenKeys) if (!keep.has(k)) delete state.seen[k]
+  }
+  const sessionKeys = Object.keys(state.lastBySession)
+  if (sessionKeys.length > 200) {
+    const cutoff = now - opts.sessionCooldown * 4
+    for (const k of sessionKeys) if ((state.lastBySession[k] as number) < cutoff) delete state.lastBySession[k]
+  }
+
+  try {
+    const tmp = opts.sharedPath + ".tmp." + process.pid
+    await writeFile(tmp, JSON.stringify(state), "utf8")
+    await rename(tmp, opts.sharedPath)
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e)
+    console.error("[termux-notify] shared state write failed:", msg)
+  }
+  return true
+}

package/src/env.ts

@@ -0,0 +1,3 @@
+export function isTermuxEnvironment(): boolean {
+  return Boolean(process.env.TERMUX_VERSION || process.env.PREFIX?.includes("com.termux"))
+}

package/src/events.ts

@@ -0,0 +1,58 @@
+import type { NotifyKind } from "./types.js"
+
+export async function classifyEvent(
+  event: any,
+  ctx: any,
+): Promise<{ kind: NotifyKind; sound: string; sessionID: string; evtId: string; isSubagent: boolean } | null> {
+  const t: string | undefined = event?.type
+  if (!t) return null
+
+  const sessionID: string = event.properties?.sessionID || event.data?.sessionID || event.sessionID || event.properties?.id || "global"
+  const evtId: string =
+    event.id || event.eventID || `${t}:${sessionID}:${event.created || ""}:${event.properties?.id || event.properties?.requestID || ""}`
+
+  if (t === "question.asked" || t === "question.v2.asked" || t === "question.updated" || t.startsWith("question")) {
+    return { kind: "question", sound: "question", sessionID, evtId, isSubagent: false }
+  }
+  if (t === "permission.asked" || t === "permission.v2.asked" || t.startsWith("permission")) {
+    return { kind: "permission", sound: "permission", sessionID, evtId, isSubagent: false }
+  }
+  if (
+    t === "session.error" ||
+    t === "session.execution.failed" ||
+    t === "session.step.failed" ||
+    t === "error" ||
+    t.endsWith(".error")
+  ) {
+    return { kind: "error", sound: "error", sessionID, evtId, isSubagent: false }
+  }
+  if (t === "session.status" && event.properties?.status?.type === "idle") {
+    let isSubagent = false
+    try {
+      if (ctx?.session?.get) {
+        const info: any = await ctx.session.get({ sessionID })
+        const raw = info?.info || info?.data || info
+        isSubagent = Boolean(raw?.parentID || raw?.parentId || raw?.parent)
+      }
+    } catch {}
+    if (!isSubagent && event.properties?.parentID) isSubagent = true
+    const sound = isSubagent ? "subagent_done" : "done"
+    const kind: NotifyKind = isSubagent ? "subagent_done" : "done"
+    return { kind, sound, sessionID, evtId, isSubagent }
+  }
+  if (t === "session.idle" || t === "session.execution.succeeded") {
+    let isSubagent = false
+    try {
+      if (ctx?.session?.get) {
+        const info: any = await ctx.session.get({ sessionID })
+        const raw = info?.info || info?.data || info
+        isSubagent = Boolean(raw?.parentID || raw?.parentId)
+      }
+    } catch {}
+    const sound = isSubagent ? "subagent_done" : "done"
+    const kind: NotifyKind = isSubagent ? "subagent_done" : "done"
+    return { kind, sound, sessionID, evtId, isSubagent }
+  }
+
+  return null
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+/**
+ * opencode-termux-notify — Termux-native notifications for OpenCode (V2)
+ *
+ * 6 builtin attention sounds:
+ *   default       → bip-bop-01.mp3
+ *   question      → bip-bop-03.mp3
+ *   permission    → staplebops-06.mp3
+ *   error         → nope-03.mp3
+ *   done          → bip-bop-01.mp3
+ *   subagent_done → yup-01.mp3
+ *
+ * Audio bundled at assets/audio/*.mp3, played via `termux-media-player play <file>`
+ * (termux-notification --sound is boolean only — no file arg)
+ */
+
+import { define } from "@opencode-ai/plugin/v2/promise"
+import { playAudio } from "./audio.js"
+import { getEnabledKinds, getContent, getTitle, resolveOpts } from "./config.js"
+import { shouldNotifyShared } from "./dedup.js"
+import { isTermuxEnvironment } from "./env.js"
+import { classifyEvent } from "./events.js"
+import { notify } from "./notify.js"
+import type { TermuxNotifyOptions } from "./types.js"
+
+export type { TermuxNotifyOptions } from "./types.js"
+export { DEFAULTS, PRIORITY_BY_KIND, SOUND_FILES, VIBRATE_PATTERNS } from "./constants.js"
+
+export default define({
+  id: "termux-notify",
+  setup: async (ctx: any): Promise<any> => {
+    const userOpts: TermuxNotifyOptions = (ctx.options ?? {}) as TermuxNotifyOptions
+    const opts = resolveOpts(userOpts)
+    const enabledKinds = getEnabledKinds(userOpts)
+
+    if (opts.requireTermux && !isTermuxEnvironment()) {
+      console.warn("[termux-notify] Not in Termux (TERMUX_VERSION/PREFIX missing) — plugin will still listen but notifications may fail. Set { requireTermux:false } to silence this.")
+    }
+
+    if (!ctx?.event?.subscribe) {
+      console.error("[termux-notify] ctx.event.subscribe not available — check OpenCode version >= 1.18")
+      return () => {}
+    }
+
+    const controller = new AbortController()
+    const events: AsyncIterable<any> = ctx.event.subscribe({ signal: controller.signal })
+
+    const active = new Set<string>()
+    const errored = new Set<string>()
+
+    void (async () => {
+      try {
+        for await (const event of events as AsyncIterable<any>) {
+          if (!event?.type) continue
+
+          if (event.type === "session.status") {
+            const sid: string | undefined = event.properties?.sessionID
+            if (!sid) continue
+            const st: string | undefined = event.properties?.status?.type
+            if (st === "busy" || st === "retry") {
+              active.add(sid)
+              errored.delete(sid)
+              continue
+            }
+            if (st !== "idle") continue
+            if (!active.has(sid)) continue
+            active.delete(sid)
+            if (errored.has(sid)) {
+              errored.delete(sid)
+              continue
+            }
+          }
+          if (event.type === "session.error") {
+            const sid: string | undefined = event.properties?.sessionID
+            if (sid && active.has(sid)) errored.add(sid)
+          }
+
+          const classified = await classifyEvent(event, ctx)
+          if (!classified) continue
+
+          const { kind, sound, sessionID } = classified
+          if (!enabledKinds.has(kind) && !enabledKinds.has(sound)) continue
+
+          const evtId: string = classified.evtId
+          const sessionKey = `${sessionID}:${kind}`
+
+          const ok = await shouldNotifyShared(evtId, sessionKey, opts)
+          if (!ok) continue
+
+          const nid = `opencode-${sessionID}-${kind}`
+
+          let sessionName = sessionID.slice(0, 8)
+          try {
+            if (ctx?.session?.get) {
+              const info: any = await ctx.session.get({ sessionID })
+              const raw = info?.info || info?.data || info
+              const candidate: string | undefined = raw?.title || raw?.slug || raw?.summary?.title || raw?.id
+              if (candidate && typeof candidate === "string" && candidate.trim()) {
+                sessionName = candidate.trim().slice(0, 40)
+              }
+            }
+          } catch {}
+
+          const title = getTitle(kind, sessionName, userOpts)
+          const content = getContent(kind, userOpts)
+
+          const notifySubagents: boolean = (userOpts as any).notifySubagents !== false
+          if (kind === "subagent_done" && !notifySubagents) {
+            await playAudio(sound, opts)
+            continue
+          }
+
+          try {
+            await notify(title, content, nid, sound, opts)
+          } catch (err: unknown) {
+            const msg = err instanceof Error ? err.message : String(err)
+            console.error(`[termux-notify] Failed to send ${kind} notification:`, msg)
+          }
+        }
+      } catch (e: unknown) {
+        const err = e as Error & { name?: string }
+        if (err?.name !== "AbortError") console.error("[termux-notify] event loop error:", e)
+      }
+    })()
+
+    return () => controller.abort()
+  },
+})

package/src/notify.ts

@@ -0,0 +1,25 @@
+import { spawn } from "node:child_process"
+import { VIBRATE_PATTERNS, PRIORITY_BY_KIND } from "./constants.js"
+import { playAudio } from "./audio.js"
+import type { ResolvedOpts } from "./types.js"
+
+export async function notify(title: string, content: string, nid: string, soundName: string, opts: ResolvedOpts): Promise<void> {
+  const vibrate = opts.vibrate ? VIBRATE_PATTERNS[soundName] || VIBRATE_PATTERNS.default : undefined
+  const priority = opts.priority || PRIORITY_BY_KIND[soundName] || "high"
+  const baseArgs = ["--id", nid, "--title", title, "--content", content, "--priority", priority]
+  if (vibrate) baseArgs.push("--vibrate", vibrate)
+
+  const notifPromise = new Promise<void>((resolve, reject) => {
+    const p = spawn(opts.bin, baseArgs, { stdio: "ignore" })
+    p.on("error", reject)
+    p.on("close", (code: number | null) => (code === 0 ? resolve() : reject(new Error(`termux-notification exit ${code}`))))
+  })
+
+  const audioPromise = playAudio(soundName, opts)
+
+  try {
+    await notifPromise
+  } finally {
+    void audioPromise.catch(() => {})
+  }
+}

package/src/types.ts

@@ -0,0 +1,39 @@
+import type { DEFAULTS } from "./constants.js"
+
+export interface TermuxNotifyOptions {
+  bin?: string
+  mediaBin?: string
+  sharedPath?: string
+  seenTTL?: number
+  sessionCooldown?: number
+  globalCooldown?: number
+  sound?: boolean
+  playSound?: boolean
+  vibrate?: boolean
+  requireTermux?: boolean
+  priority?: "high" | "low" | "default" | "max" | (string & {})
+  kinds?: Array<"default" | "question" | "permission" | "error" | "done" | "subagent_done" | "idle">
+  notifySubagents?: boolean
+  title_default?: string
+  title_done?: string
+  title_subagent_done?: string
+  title_question?: string
+  title_permission?: string
+  title_error?: string
+  content_default?: string
+  content_done?: string
+  content_subagent_done?: string
+  content_question?: string
+  content_permission?: string
+  content_error?: string
+  // legacy
+  vibrateIdle?: string
+  vibrateError?: string
+  titleIdle?: string
+  titleError?: string
+  contentIdle?: string
+  contentError?: string
+}
+
+export type NotifyKind = "default" | "question" | "permission" | "error" | "done" | "subagent_done"
+export type ResolvedOpts = typeof DEFAULTS

package/src/v1.ts

@@ -0,0 +1,140 @@
+/**
+ * opencode-termux-notify — Termux-native notifications for OpenCode (V1)
+ *
+ * V1 plugin API: export const TermuxNotify: Plugin = async (input, options) => ({ event })
+ * Loaded via `plugin: ["opencode-termux-notify"]` or `["opencode-termux-notify/v1"]`
+ * V2 is available at `opencode-termux-notify/v2`
+ *
+ * 6 builtin attention sounds:
+ *   default       → bip-bop-01.mp3
+ *   question      → bip-bop-03.mp3
+ *   permission    → staplebops-06.mp3
+ *   error         → nope-03.mp3
+ *   done          → bip-bop-01.mp3
+ *   subagent_done → yup-01.mp3
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { playAudio } from "./audio.js"
+import { getEnabledKinds, getContent, getTitle, resolveOpts } from "./config.js"
+import { shouldNotifyShared } from "./dedup.js"
+import { isTermuxEnvironment } from "./env.js"
+import { classifyEvent } from "./events.js"
+import { notify } from "./notify.js"
+import type { TermuxNotifyOptions } from "./types.js"
+
+export type { TermuxNotifyOptions } from "./types.js"
+export { DEFAULTS, PRIORITY_BY_KIND, SOUND_FILES, VIBRATE_PATTERNS } from "./constants.js"
+
+export const TermuxNotify: Plugin = async (input, options) => {
+  const userOpts: TermuxNotifyOptions = (options ?? {}) as TermuxNotifyOptions
+  const opts = resolveOpts(userOpts)
+  const enabledKinds = getEnabledKinds(userOpts)
+
+  if (opts.requireTermux && !isTermuxEnvironment()) {
+    console.warn(
+      "[termux-notify] Not in Termux (TERMUX_VERSION/PREFIX missing) — plugin will still listen but notifications may fail. Set { requireTermux:false } to silence this.",
+    )
+  }
+
+  const active = new Set<string>()
+  const errored = new Set<string>()
+
+  // Adapter so classifyEvent and session-title logic can use V2-style ctx.session.get
+  // V1 client uses client.session.get({ path: { id } }) -> { data: Session }
+  const ctxAdapter: any = {
+    session: {
+      get: async ({ sessionID }: { sessionID: string }) => {
+        try {
+          const client: any = (input as any).client
+          if (!client?.session?.get) return undefined
+          let raw: any
+          // try V2-style first, then V1-style
+          try {
+            raw = await client.session.get({ sessionID })
+            if (raw && (raw.info || raw.data || raw.title || raw.id)) return raw
+          } catch {}
+          try {
+            raw = await client.session.get({ path: { id: sessionID } })
+          } catch {}
+          // SDK gen returns { data, ... } or direct
+          const data = raw?.data ?? raw
+          return data
+        } catch {
+          return undefined
+        }
+      },
+    },
+  }
+
+  return {
+    event: async ({ event }: { event: any }) => {
+      if (!event?.type) return
+
+      // replicate V2 status tracking to avoid duplicate idle notifications after errors
+      if (event.type === "session.status") {
+        const sid: string | undefined = event.properties?.sessionID
+        if (!sid) return
+        const st: string | undefined = event.properties?.status?.type
+        if (st === "busy" || st === "retry") {
+          active.add(sid)
+          errored.delete(sid)
+          return
+        }
+        if (st !== "idle") return
+        if (!active.has(sid)) return
+        active.delete(sid)
+        if (errored.has(sid)) {
+          errored.delete(sid)
+          return
+        }
+      }
+      if (event.type === "session.error") {
+        const sid: string | undefined = event.properties?.sessionID
+        if (sid && active.has(sid)) errored.add(sid)
+      }
+
+      const classified = await classifyEvent(event, ctxAdapter)
+      if (!classified) return
+
+      const { kind, sound, sessionID } = classified
+      if (!enabledKinds.has(kind) && !enabledKinds.has(sound)) return
+
+      const evtId: string = classified.evtId
+      const sessionKey = `${sessionID}:${kind}`
+
+      const ok = await shouldNotifyShared(evtId, sessionKey, opts)
+      if (!ok) return
+
+      const nid = `opencode-${sessionID}-${kind}`
+
+      let sessionName = sessionID.slice(0, 8)
+      try {
+        const info: any = await ctxAdapter.session.get({ sessionID })
+        const raw = info?.info || info?.data || info
+        const candidate: string | undefined = raw?.title || raw?.slug || raw?.summary?.title || raw?.id
+        if (candidate && typeof candidate === "string" && candidate.trim()) {
+          sessionName = candidate.trim().slice(0, 40)
+        }
+      } catch {}
+
+      const title = getTitle(kind, sessionName, userOpts)
+      const content = getContent(kind, userOpts)
+
+      const notifySubagents: boolean = (userOpts as any).notifySubagents !== false
+      if (kind === "subagent_done" && !notifySubagents) {
+        await playAudio(sound, opts)
+        return
+      }
+
+      try {
+        await notify(title, content, nid, sound, opts)
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        console.error(`[termux-notify] Failed to send ${kind} notification:`, msg)
+      }
+    },
+  }
+}
+
+export default TermuxNotify