@brimveyn/aimux 1.20.4 → 1.22.0

package/src/platform/open-url.ts

@@ -0,0 +1,39 @@
+import { logDebug } from '../debug/input-log'
+import { toast } from '../state/toast-store'
+import { detectClipboardPlatform } from './clipboard'
+
+/**
+ * URLs here come from the GitHub API, i.e. outside the process. Handing an
+ * arbitrary scheme to the OS opener is a code-execution path (`file://`,
+ * `javascript:`, custom app handlers), so only plain https is allowed through.
+ */
+function isSafeUrl(url: string): boolean {
+  return /^https:\/\/[^\s]+$/.test(url)
+}
+
+export function openUrlCommand(platform: string, isWsl: boolean, url: string): string[] | null {
+  if (!isSafeUrl(url)) return null
+  if (platform === 'darwin') return ['open', url]
+  // Under WSL the browser lives on the Windows side; explorer.exe is the one
+  // bridge present on every install (wslview/xdg-open often are not).
+  if (platform === 'win32' || isWsl) return ['explorer.exe', url]
+  return ['xdg-open', url]
+}
+
+export function openUrl(url: string): void {
+  const { isWsl, platform } = detectClipboardPlatform()
+  const argv = openUrlCommand(platform, isWsl, url)
+  if (!argv) {
+    logDebug('platform.openUrl.rejected', { url })
+    return
+  }
+  try {
+    Bun.spawn(argv, { stderr: 'ignore', stdin: 'ignore', stdout: 'ignore' })
+  } catch (error) {
+    logDebug('platform.openUrl.error', {
+      argv,
+      error: error instanceof Error ? error.message : String(error),
+    })
+    toast.error(`Could not open ${argv[0]}`)
+  }
+}

package/src/platform/play-sound.ts

@@ -0,0 +1,184 @@
+// Notification sounds: the shipped three, plus whatever the user drops in
+// their profile's `sounds/` directory. Shaped like `open-url.ts` — a pure
+// command builder the tests can read, and one impure function that spawns it.
+//
+// Everything here fails quietly. A missing player or an unreadable file is a
+// silent notification, never a toast per event.
+
+import { existsSync, readdirSync } from 'node:fs'
+import { dirname, extname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { logDebug } from '../debug/input-log'
+import { getProfileConfigDir } from '../profile-paths'
+
+/** The value `notifications.sound` holds when the user wants silence. */
+export const SOUND_OFF = 'off'
+
+/** Shipped sounds, in the order the settings row offers them. */
+export const BUILTIN_SOUND_IDS = ['plane', 'bell', 'ding'] as const
+
+/**
+ * Extensions offered from the drop-in directory. `afplay` and `ffplay` handle
+ * all of them; `paplay`/`aplay` only really handle wav — which is why the
+ * shipped three are wav.
+ */
+const SOUND_EXTENSIONS = new Set(['.wav', '.m4a', '.mp3', '.aiff', '.aif', '.ogg', '.flac'])
+
+/** No more than one sound per window, however many tabs finish at once. */
+const THROTTLE_MS = 700
+
+/**
+ * Percent of the file's own level. These are notifications for someone sitting
+ * in front of the terminal, not an alarm across the room, and the shipped three
+ * are loud at their own scale — hence a default well under full.
+ */
+export const DEFAULT_VOLUME = 35
+
+/** Where a user drops their own sounds. Named in the settings row. */
+export function getCustomSoundsDir(): string {
+  return join(getProfileConfigDir(), 'sounds')
+}
+
+/**
+ * Absolute path to a shipped sound. Resolved from this module's URL, the same
+ * walk-up `resolveHookScriptPath` does, so it works wherever aimux is installed.
+ */
+function builtinSoundPath(id: string): string | null {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const candidates = [
+    resolve(here, '..', 'assets', 'sounds', `${id}.wav`),
+    resolve(here, '..', '..', 'assets', 'sounds', `${id}.wav`),
+  ]
+  return candidates.find((candidate) => existsSync(candidate)) ?? null
+}
+
+/**
+ * Ids of the files the user has dropped in, without their extension. Deduped:
+ * `bell-2.wav` and `bell-2.mp3` are one option, and `resolveSoundPath` picks
+ * between them the same way every time.
+ */
+export function listCustomSoundIds(): string[] {
+  try {
+    const ids = readdirSync(getCustomSoundsDir())
+      .filter((name) => SOUND_EXTENSIONS.has(extname(name).toLowerCase()))
+      .map((name) => name.slice(0, -extname(name).length))
+      .filter(
+        (id) => id !== '' && !BUILTIN_SOUND_IDS.includes(id as (typeof BUILTIN_SOUND_IDS)[number])
+      )
+    return [...new Set(ids)].sort()
+  } catch {
+    // No directory is the common case, not an error.
+    return []
+  }
+}
+
+/** The file behind a sound id, shipped or dropped in, or null when there is none. */
+export function resolveSoundPath(id: string): string | null {
+  if (id === '' || id === SOUND_OFF) return null
+  if (BUILTIN_SOUND_IDS.includes(id as (typeof BUILTIN_SOUND_IDS)[number])) {
+    return builtinSoundPath(id)
+  }
+  const dir = getCustomSoundsDir()
+  for (const extension of SOUND_EXTENSIONS) {
+    const candidate = join(dir, `${id}${extension}`)
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+/**
+ * How to invoke one player on one file, at `volume` percent. `bin` is whichever
+ * player was found; the caller does the looking, so this stays pure.
+ *
+ * Every player spells volume differently, and two of them cannot say it at all
+ * — `aplay` and PowerShell's `SoundPlayer` play at the system level whatever we
+ * ask, which the setting's description admits rather than pretending otherwise.
+ */
+export function soundPlayerArgv(
+  platform: string,
+  bin: string,
+  path: string,
+  volume: number
+): string[] {
+  const percent = Math.min(100, Math.max(0, Math.round(volume)))
+  if (platform === 'win32') {
+    // The path is a filename the user chose. PowerShell escapes a quote inside
+    // a single-quoted string by doubling it; without this a name containing one
+    // ends the string and the rest of it is executed.
+    const quoted = path.replaceAll("'", "''")
+    return [
+      bin,
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      `(New-Object Media.SoundPlayer '${quoted}').PlaySync()`,
+    ]
+  }
+  if (bin.endsWith('afplay')) return [bin, '-v', String(percent / 100), path]
+  if (bin.endsWith('paplay')) return [bin, `--volume=${Math.round((percent / 100) * 65_536)}`, path]
+  if (bin.endsWith('ffplay')) {
+    return [bin, '-nodisp', '-autoexit', '-loglevel', 'quiet', '-volume', String(percent), path]
+  }
+  if (bin.endsWith('mpv')) return [bin, '--no-video', '--really-quiet', `--volume=${percent}`, path]
+  return [bin, path]
+}
+
+/**
+ * Players in preference order. macOS ships afplay; on Linux nothing is
+ * guaranteed, so we take the first one installed. `Bun.which` is the lookup —
+ * spawning a missing binary would throw once per notification.
+ */
+function findPlayer(platform: string): string | null {
+  let candidates = ['paplay', 'aplay', 'ffplay', 'mpv']
+  if (platform === 'darwin') candidates = ['afplay']
+  if (platform === 'win32') candidates = ['powershell.exe', 'powershell']
+  for (const candidate of candidates) {
+    const found = Bun.which(candidate)
+    if (found != null && found !== '') return found
+  }
+  return null
+}
+
+let lastPlayedAt = 0
+
+/**
+ * Whether enough time has passed since the last sound. Separate from the play
+ * itself so the window is testable without a clock.
+ */
+export function shouldPlayNow(now: number, previous: number): boolean {
+  return now - previous >= THROTTLE_MS
+}
+
+/**
+ * Play a sound file. Returns whether a player was actually spawned, which is
+ * what the settings screen's "Test sound" row reports.
+ */
+export function playSoundFile(
+  path: string,
+  options?: { ignoreThrottle?: boolean; volume?: number }
+): boolean {
+  const now = Date.now()
+  const throttled = options?.ignoreThrottle !== true
+  if (throttled && !shouldPlayNow(now, lastPlayedAt)) return false
+  const platform = process.platform
+  const bin = findPlayer(platform)
+  if (bin == null) {
+    logDebug('platform.playSound.noPlayer', { platform })
+    return false
+  }
+  const argv = soundPlayerArgv(platform, bin, path, options?.volume ?? DEFAULT_VOLUME)
+  try {
+    Bun.spawn(argv, { stderr: 'ignore', stdin: 'ignore', stdout: 'ignore' })
+    // A test press does not start the window: it would swallow a real
+    // notification arriving in the next few hundred milliseconds.
+    if (throttled) lastPlayedAt = now
+    return true
+  } catch (error) {
+    logDebug('platform.playSound.error', {
+      argv,
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return false
+  }
+}

package/src/platform/project-search.ts

@@ -9,7 +9,7 @@ import { logDebug } from '../debug/input-log'
 
 interface DirectoryCache {
   repoPaths: string[]
-  workspaceSet: Set<string>
+  projectSet: Set<string>
   cachedAt: number
 }
 
@@ -38,16 +38,16 @@ async function buildCache(): Promise<DirectoryCache> {
         parentCount.set(parent, (parentCount.get(parent) ?? 0) + 1)
       }
     }
-    const workspacePaths = [...parentCount.entries()]
+    const projectPaths = [...parentCount.entries()]
       .filter(([, count]) => count >= 2)
       .map(([p]) => p)
 
-    return { cachedAt: Date.now(), repoPaths, workspaceSet: new Set(workspacePaths) }
+    return { cachedAt: Date.now(), projectSet: new Set(projectPaths), repoPaths }
   } catch (error) {
     logDebug('platform.projectSearch.buildCache.error', {
       error: error instanceof Error ? error.message : String(error),
     })
-    return { cachedAt: Date.now(), repoPaths: [], workspaceSet: new Set() }
+    return { cachedAt: Date.now(), projectSet: new Set(), repoPaths: [] }
   }
 }
 
@@ -70,7 +70,7 @@ export async function searchProjectDirectories(query: string): Promise<Directory
 
   try {
     const cache = await getOrBuildCache()
-    const allPaths = [...cache.repoPaths, ...cache.workspaceSet].join('\n')
+    const allPaths = [...cache.repoPaths, ...cache.projectSet].join('\n')
 
     const filtered =
       await $`printf '%s' ${allPaths} | fzf --filter=${query} --no-sort | head -50`.quiet()
@@ -89,12 +89,12 @@ export async function searchProjectDirectories(query: string): Promise<Directory
 
     return Promise.all(
       resultPaths.map(async (path) => {
-        if (cache.workspaceSet.has(path)) {
-          return { path, type: 'workspace' as const }
+        if (cache.projectSet.has(path)) {
+          return { path, type: 'project' as const }
         }
         const gitPath = join(path, '.git')
         const st = await stat(gitPath).catch(() => null)
-        const type = st !== null && st.isFile() ? 'worktree' : 'git-repo'
+        const type = st !== null && st.isFile() ? 'workspace' : 'git-repo'
         return { path, type } as const
       })
     )

package/src/platform/worktree-paths.ts

@@ -23,18 +23,20 @@ function shortHash(input: string, length = 8): string {
   return createHash('sha1').update(input).digest('hex').slice(0, length)
 }
 
+// Params speak the app's vocabulary (a workspace); the directory layout keeps
+// git's, so existing worktrees on disk stay exactly where they are.
 export function makeWorktreePath({
   repoRoot,
-  worktreeId,
-  worktreeName,
+  workspaceId,
+  workspaceName,
 }: {
   repoRoot: string
-  worktreeName: string
-  worktreeId: string
+  workspaceName: string
+  workspaceId: string
 }): string {
   const repoKey = `r-${shortHash(resolve(repoRoot))}`
-  const idSuffix = shortHash(worktreeId, 5)
-  const slug = `${sanitizePathSegment(worktreeName)}-${idSuffix}`
+  const idSuffix = shortHash(workspaceId, 5)
+  const slug = `${sanitizePathSegment(workspaceName)}-${idSuffix}`
   return join(getAimuxWorktreeRoot(), repoKey, slug)
 }
 

package/src/pty/assistant-question-extractor.ts

@@ -49,7 +49,7 @@ const PERMISSION_SIGNALS: readonly string[] = [
   'write this file?',
   'apply these edits?',
   'ready to build with this plan?',
-  'approve for session',
+  'approve for project',
   'stop this task?',
 ]
 

package/src/pty/assistant-status-detection-loop.ts

@@ -3,17 +3,17 @@
  *
  * Backends drive this loop to monitor every known terminal at a fixed cadence:
  * every tick we pull each tab's current viewport, run the detector on the last
- * ~10 non-blank lines, and report per-tab + per-session statuses to the
+ * ~10 non-blank lines, and report per-tab + per-project statuses to the
  * backend's transport. The loop is the single source of truth so that idle
  * tabs can't erase a sibling's waiting-input, and so that clients receive
- * status for every session the backend owns, not just the attached one.
+ * status for every project the backend owns, not just the attached one.
  *
- * Per-session status is a pair of independent booleans:
+ * Per-project status is a pair of independent booleans:
  *   - `working`: at least one tab is working.
  *   - `waiting`: at least one tab is waiting for user input.
  * Both can be true at the same time — the chip renders one glyph per flag.
  */
-import type { AssistantId, SessionStatus, TabActivity, TerminalSnapshot } from '../state/types'
+import type { AssistantId, ProjectStatus, TabActivity, TerminalSnapshot } from '../state/types'
 
 import { logDebug } from '../debug/input-log'
 import { getLineText } from '../input/terminal-text-extraction'
@@ -50,22 +50,36 @@ export interface LoopTabView {
   assistant: AssistantId
   command: string
   viewport?: TerminalSnapshot
+  /** The workspace this tab belongs to, when its owner knows one. Passed
+   *  straight through to the status callbacks so a client can group tabs it
+   *  does not itself hold — see the `workspaceId` note in `src/ipc/protocol.ts`. */
+  workspaceId?: string
 }
 
 export interface StatusDetectionLoopOptions {
-  listSessions: () => string[]
-  listTabs: (sessionId: string) => LoopTabView[]
+  listProjects: () => string[]
+  listTabs: (projectId: string) => LoopTabView[]
   /** Emitted when a tab's status changes. */
-  onTabStatus: (tabId: string, status: TabActivity, sessionId: string) => void
-  /** Emitted when either flag on a session changes. */
-  onSessionStatus: (sessionId: string, status: SessionStatus) => void
+  onTabStatus: (
+    tabId: string,
+    status: TabActivity,
+    projectId: string,
+    workspaceId: string | undefined
+  ) => void
+  /** Emitted when either flag on a project changes. */
+  onProjectStatus: (projectId: string, status: ProjectStatus) => void
   /**
    * Emitted once per turn, when a tab's `idle` activity has held continuously
    * for `turnSettleMs`. Edge-triggered: re-armed only after the tab leaves
    * `idle`, so a driver receives exactly one signal per turn. `idleMs` is how
    * long idle had held when the signal fired.
    */
-  onTurnComplete?: (tabId: string, sessionId: string, idleMs: number) => void
+  onTurnComplete?: (
+    tabId: string,
+    projectId: string,
+    idleMs: number,
+    workspaceId: string | undefined
+  ) => void
   /**
    * Emitted when a tab transitions into `waiting-input`. Edge-triggered: fires
    * once per transition, carrying the captured prompt text and any parsed
@@ -74,7 +88,7 @@ export interface StatusDetectionLoopOptions {
    */
   onTabQuestion?: (
     tabId: string,
-    sessionId: string,
+    projectId: string,
     detail: { kind: 'question' | 'permission'; prompt: string; options?: string[] }
   ) => void
   tickMs?: number
@@ -89,18 +103,18 @@ export interface StatusDetectionLoopHandle {
   stop: () => void
   /** Last classified status for a tab, for on-attach replay. */
   getTabStatus: (tabId: string) => TabActivity | undefined
-  /** Last session flags, for on-attach replay. */
-  getSessionStatus: (sessionId: string) => SessionStatus | undefined
-  /** Snapshot of every known session's flags. */
-  snapshotSessions: () => { sessionId: string; status: SessionStatus }[]
-  /** Snapshot of every known tab's status plus its session. */
-  snapshotTabs: () => { tabId: string; sessionId: string; status: TabActivity }[]
+  /** Last project flags, for on-attach replay. */
+  getProjectStatus: (projectId: string) => ProjectStatus | undefined
+  /** Snapshot of every known project's flags. */
+  snapshotProjects: () => { projectId: string; status: ProjectStatus }[]
+  /** Snapshot of every known tab's status plus its project. */
+  snapshotTabs: () => { tabId: string; projectId: string; status: TabActivity }[]
   /**
-   * Synchronously run classification for a single session. Used on client
+   * Synchronously run classification for a single project. Used on client
    * attach so the replay snapshot is populated *before* the client reads it,
    * rather than relying on the next scheduled tick.
    */
-  classifyNow: (sessionId: string, tabs: LoopTabView[]) => void
+  classifyNow: (projectId: string, tabs: LoopTabView[]) => void
   /**
    * Feed a Claude Code hook event into the arbiter. The next tick will
    * combine it with the visual detector's verdict. Called by the daemon's
@@ -117,8 +131,11 @@ export function runStatusDetectionLoop(
   const now = options.nowFn ?? Date.now
   const detector = new AssistantStatusDetector()
   const arbiter = new AssistantStatusArbiter()
-  const lastTabStatus = new Map<string, { status: TabActivity; sessionId: string }>()
-  const lastSessionStatus = new Map<string, SessionStatus>()
+  const lastTabStatus = new Map<
+    string,
+    { status: TabActivity; projectId: string; workspaceId?: string }
+  >()
+  const lastProjectStatus = new Map<string, ProjectStatus>()
   // Timestamp when a tab most recently entered `idle`. Cleared when it leaves
   // idle. `turnEmitted` guards against re-firing `onTurnComplete` within the
   // same idle episode; it's cleared alongside `idleSince` so the next turn
@@ -138,7 +155,7 @@ export function runStatusDetectionLoop(
   timer.unref?.()
 
   function classifySession(
-    sessionId: string,
+    projectId: string,
     tabs: LoopTabView[],
     now: number,
     source: 'tick' | 'classifyNow',
@@ -159,21 +176,21 @@ export function runStatusDetectionLoop(
       if (status === 'working') working = true
       if (status === 'waiting-input') waiting = true
       const prev = lastTabStatus.get(tab.id)
-      const changed = !prev || prev.status !== status || prev.sessionId !== sessionId
+      const changed = !prev || prev.status !== status || prev.projectId !== projectId
       logDebug('statusLoop.classify', {
         assistant: tab.assistant,
         changed,
-        prevSessionId: prev?.sessionId,
+        prevProjectId: prev?.projectId,
         prevStatus: prev?.status,
-        sessionId,
+        projectId,
         source,
         status,
         tabId: tab.id,
         tailPreview: tailPreview(tab.viewport),
       })
       if (changed) {
-        lastTabStatus.set(tab.id, { sessionId, status })
-        options.onTabStatus(tab.id, status, sessionId)
+        lastTabStatus.set(tab.id, { projectId, status, workspaceId: tab.workspaceId })
+        options.onTabStatus(tab.id, status, projectId, tab.workspaceId)
       }
 
       // Turn-complete bookkeeping. The emission itself is gated to `tick` so a
@@ -189,7 +206,7 @@ export function runStatusDetectionLoop(
         }
         if (source === 'tick' && !turnEmitted.has(tab.id) && now - since >= turnSettleMs) {
           turnEmitted.add(tab.id)
-          options.onTurnComplete?.(tab.id, sessionId, now - since)
+          options.onTurnComplete?.(tab.id, projectId, now - since, tab.workspaceId)
         }
       } else {
         idleSince.delete(tab.id)
@@ -205,59 +222,66 @@ export function runStatusDetectionLoop(
         options.onTabQuestion
       ) {
         const detail = extractQuestion(tab.assistant, tab.viewport)
-        if (detail) options.onTabQuestion(tab.id, sessionId, detail)
+        if (detail) options.onTabQuestion(tab.id, projectId, detail)
       }
     }
-    const next: SessionStatus = { waiting, working }
-    const prevSession = lastSessionStatus.get(sessionId)
-    const sessionChanged =
-      !prevSession || prevSession.working !== working || prevSession.waiting !== waiting
+    const next: ProjectStatus = { waiting, working }
+    const prevProject = lastProjectStatus.get(projectId)
+    const projectChanged =
+      !prevProject || prevProject.working !== working || prevProject.waiting !== waiting
     logDebug('statusLoop.classifySession', {
-      prev: prevSession,
-      sessionChanged,
-      sessionId,
+      prev: prevProject,
+      projectChanged,
+      projectId,
       source,
       status: next,
       tabCount: tabs.length,
     })
-    if (sessionChanged) {
-      lastSessionStatus.set(sessionId, next)
-      options.onSessionStatus(sessionId, next)
+    if (projectChanged) {
+      lastProjectStatus.set(projectId, next)
+      options.onProjectStatus(projectId, next)
     }
   }
 
   function tick(): void {
     const ts = now()
-    const sessionIds = options.listSessions()
-    const seenSessions = new Set<string>()
+    const projectIds = options.listProjects()
+    const seenProjects = new Set<string>()
     const seenTabs = new Set<string>()
 
-    for (const sessionId of sessionIds) {
-      seenSessions.add(sessionId)
-      classifySession(sessionId, options.listTabs(sessionId), ts, 'tick', seenTabs)
+    for (const projectId of projectIds) {
+      seenProjects.add(projectId)
+      classifySession(projectId, options.listTabs(projectId), ts, 'tick', seenTabs)
     }
 
-    for (const tabId of lastTabStatus.keys()) {
+    for (const [tabId, entry] of lastTabStatus) {
       if (!seenTabs.has(tabId)) {
         detector.forget(tabId)
         arbiter.forget(tabId)
         lastTabStatus.delete(tabId)
         idleSince.delete(tabId)
         turnEmitted.delete(tabId)
+        // A gone tab is no longer working or waiting on anyone. Only clients
+        // attached to its project hear its `tabExit`, so without this last
+        // word a tab that died mid-turn leaves every other client holding a
+        // status that will never be corrected.
+        if (entry.status !== 'idle') {
+          options.onTabStatus(tabId, 'idle', entry.projectId, entry.workspaceId)
+        }
       }
     }
-    for (const sessionId of lastSessionStatus.keys()) {
-      if (!seenSessions.has(sessionId)) {
-        lastSessionStatus.delete(sessionId)
+    for (const projectId of lastProjectStatus.keys()) {
+      if (!seenProjects.has(projectId)) {
+        lastProjectStatus.delete(projectId)
       }
     }
   }
 
   return {
-    classifyNow: (sessionId, tabs) => {
-      classifySession(sessionId, tabs, now(), 'classifyNow')
+    classifyNow: (projectId, tabs) => {
+      classifySession(projectId, tabs, now(), 'classifyNow')
     },
-    getSessionStatus: (sessionId) => lastSessionStatus.get(sessionId),
+    getProjectStatus: (projectId) => lastProjectStatus.get(projectId),
     getTabStatus: (tabId) => lastTabStatus.get(tabId)?.status,
     recordHookEvent: (input) => {
       const mapped = arbiter.recordHookEvent(input)
@@ -267,11 +291,11 @@ export function runStatusDetectionLoop(
         paneId: input.paneId,
       })
     },
-    snapshotSessions: () =>
-      [...lastSessionStatus.entries()].map(([sessionId, status]) => ({ sessionId, status })),
+    snapshotProjects: () =>
+      [...lastProjectStatus.entries()].map(([projectId, status]) => ({ projectId, status })),
     snapshotTabs: () =>
       [...lastTabStatus.entries()].map(([tabId, entry]) => ({
-        sessionId: entry.sessionId,
+        projectId: entry.projectId,
         status: entry.status,
         tabId,
       })),
@@ -280,7 +304,7 @@ export function runStatusDetectionLoop(
       detector.clear()
       arbiter.clear()
       lastTabStatus.clear()
-      lastSessionStatus.clear()
+      lastProjectStatus.clear()
       idleSince.clear()
       turnEmitted.clear()
     },