@raidiant/notifai 9.3.0 → 10.1.0

package/src/commands-hooks.ts

@@ -12,6 +12,8 @@ import {
   lstatSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
+  rmdirSync,
   rmSync,
 } from 'node:fs'
 import path from 'node:path'
@@ -21,7 +23,14 @@ import { ApiCallError } from './client.js'
 import { codexWakeRoute } from './codex-wake.js'
 import { loadConfig, type CliConfig } from './config.js'
 import { withTargetFileLock } from './file-lock.js'
-import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js'
+import {
+  HARNESS_LABELS,
+  HERMES_QUESTION_ROUTING_UNAVAILABLE,
+  HOOK_INSTALLABLE_HARNESSES,
+  isHookInstallableHarness,
+  questionRoutingCapability,
+  type HookInstallableHarness,
+} from './harnesses.js'
 import {
   inspectHookAdapter,
   installHookAdapter,
@@ -51,7 +60,6 @@ import {
 } from './hooks.js'
 import {
   NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
-  HARNESSES,
   applyPlan,
   buildCursorHookConfig,
   buildHookConfig,
@@ -75,13 +83,24 @@ import {
   removeHooks,
   settingsFile,
   withCodexLayerTransaction,
-  type Harness,
   type Installation,
 } from './install-hooks.js'
 import { QUESTION_WAITER_CEILING_SECONDS } from './question-timing.js'
 import { inferInvocationContext } from './invocation-context.js'
 import { logConfigResolved, logSettingsFrom } from './logging.js'
 import { isOurOpencodePlugin, opencodePluginSource } from './opencode-plugin.js'
+import {
+  OPENCLAW_PLUGIN_MANIFEST,
+  OPENCLAW_PLUGIN_PACKAGE,
+  isOurOpenclawPlugin,
+  mergeOpenclawNotifaiEntry,
+  openclawConfigPath,
+  openclawPluginManifest,
+  openclawPluginPackage,
+  openclawPluginSource,
+  parseOpenclawConfig,
+  removeOpenclawNotifaiEntry,
+} from './openclaw-plugin.js'
 import { packageVersion } from './release.js'
 import { enableProject, projectBinding, projectEnabled } from './project-enablement.js'
 import { rejectAccidentalEscapedNewlines } from './send.js'
@@ -99,6 +118,7 @@ import {
 } from './send.js'
 import {
   EXIT,
+  SETUP_COMMAND,
   authedClient,
   diagnoseIgnoredOriginOverride,
   loadLoggedConfig,
@@ -138,8 +158,8 @@ export const HOOK_EVENTS = [
 export type HookEvent = (typeof HOOK_EVENTS)[number]
 
 /** Lifecycle handlers one installed harness must carry in this CLI build. */
-export function requiredHookEvents(harness: Harness): readonly HookEvent[] {
-  if (harness === 'opencode') return []
+export function requiredHookEvents(harness: HookInstallableHarness): readonly HookEvent[] {
+  if (harness === 'opencode' || harness === 'openclaw') return []
   return harness === 'cursor'
     ? ['session-start', 'activation-stop', 'user-prompt-submit', 'stop', 'session-end']
     : ['session-start', 'subagent-start', 'user-prompt-submit', 'stop', 'session-end']
@@ -464,7 +484,7 @@ export async function hookRunCommand(
     const credential = deps.store.load()
     if (!credential) {
       logger.error('hook.end', { hook: event, outcome: 'not-paired' })
-      deps.io.err('notifai: hook skipped: this machine is not paired; run `notifai login`')
+      deps.io.err(`notifai: hook skipped: this machine is not paired; run \`${SETUP_COMMAND}\``)
       return EXIT.ok
     }
     // Pin authenticated traffic to the origin the credential was issued for. A
@@ -572,7 +592,7 @@ export async function hookRunCommand(
  */
 function stopWakeRoute(
   deps: CommandDeps,
-  harness: Harness | undefined,
+  harness: HookInstallableHarness | undefined,
   sessionId: string | undefined,
   cwd: string,
 ): EscalationDeliveryRoute | undefined {
@@ -1102,6 +1122,17 @@ export function askCommand(
         'run the ask from a shell with one exact active harness session',
       )
     }
+    if (!isHookInstallableHarness(active.harness)) {
+      const capability = HERMES_QUESTION_ROUTING_UNAVAILABLE
+      return askFailure(
+        deps,
+        flags,
+        'question_routing_unavailable',
+        'hook_contract',
+        `${active.label}: ${capability.deliveryContract}`,
+        'use a blocking `notifai send --reply` question',
+      )
+    }
     const exactState = active.sessionId === undefined
       ? null
       : readSessionState(active.sessionId, deps.env)
@@ -1253,7 +1284,9 @@ export function activeQuestionRouteProblems(
       `the active ${active.label} shell does not expose an exact session id; a project-level last-writer pointer can cross-wire two sessions. Use a blocking \`notifai send --reply\` question`,
     )
   }
-  const capability = HARNESS_CAPABILITIES[active.harness]
+  const capability = isHookInstallableHarness(active.harness)
+    ? questionRoutingCapability(active.harness)
+    : HERMES_QUESTION_ROUTING_UNAVAILABLE
   if (capability.stopContinuation === 'unsupported') {
     problems.push(`${active.label}: ${capability.deliveryContract}`)
   }
@@ -1330,6 +1363,11 @@ export function hookActivationAdvice(installations: Installation[]): string {
       'OpenCode: restart it, then send one prompt; plugins load at startup, but non-blocking question continuation is intentionally unsupported',
     )
   }
+  if (harnesses.has('openclaw')) {
+    advice.push(
+      'OpenClaw: restart the Gateway, then send one prompt; plugins load at startup, but non-blocking question continuation is intentionally unsupported',
+    )
+  }
   return `${advice.join('. ')}.`
 }
 
@@ -1683,7 +1721,7 @@ function resolveHookAdapterTarget(deps: CommandDeps, flags: HooksInstallFlags):
   return { execPath, scriptPath }
 }
 
-function printHooksInstallClose(deps: CommandDeps, harness: Harness, file: string): void {
+function printHooksInstallClose(deps: CommandDeps, harness: HookInstallableHarness, file: string): void {
   const label = HARNESS_LABELS[harness]
   const activation =
     harness === 'codex'
@@ -1692,6 +1730,8 @@ function printHooksInstallClose(deps: CommandDeps, harness: Harness, file: strin
         ? 'Start one fresh Cursor conversation, send one prompt, finish its first turn, then run `notifai doctor`.'
         : harness === 'opencode'
           ? 'Restart OpenCode, start one fresh session, send one prompt, then run `notifai doctor`.'
+          : harness === 'openclaw'
+            ? 'Restart the OpenClaw Gateway, start one fresh Agent Session, send one prompt, then run `notifai doctor`.'
           : `Start one fresh ${label} session, send one prompt, then run \`notifai doctor\`.`
   if (deps.io.interactive === true && deps.io.note) {
     void deps.io.note(`${file}\n${activation}`, `${label} hooks installed`)
@@ -1705,7 +1745,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   if (flags.harness === undefined) {
     const detected = detectedHarnesses(deps.cwd, deps.env)
     if (detected.length === 0) {
-      deps.io.err(`Could not tell which harness you mean — pass --harness <${HARNESSES.join('|')}>.`)
+      deps.io.err(`Could not tell which harness you mean — pass --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>.`)
       return EXIT.usage
     }
     let ok = true
@@ -1784,6 +1824,16 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       ...(flags.narrate === undefined ? {} : { narrate: flags.narrate }),
     })
   }
+  if (harness === 'openclaw') {
+    return installOpenclawPlugin(deps, settingsTarget, {
+      adapterPath,
+      timeoutSeconds: NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
+      platform: hookPlatform,
+      nodePath,
+      global: wantGlobal,
+      ...(flags.narrate === undefined ? {} : { narrate: flags.narrate }),
+    })
+  }
 
   if (harness === 'cursor') {
     try {
@@ -1930,6 +1980,113 @@ function installOpencodePlugin(
   return EXIT.ok
 }
 
+function installOpenclawPlugin(
+  deps: CommandDeps,
+  file: string,
+  options: {
+    adapterPath: string
+    timeoutSeconds: number
+    platform?: NodeJS.Platform
+    nodePath?: string
+    global: boolean
+    narrate?: boolean
+  },
+): number {
+  const pluginDir = path.dirname(file)
+  try {
+    withTargetFileLock(file, () => {
+      if (existsSync(file)) {
+        assertOwnedRegularFile(file)
+        const existing = readFileSync(file, 'utf8')
+        if (!isOurOpenclawPlugin(existing)) {
+          throw new Error(`${file} exists and was not written by Notifai; move it aside first.`)
+        }
+      }
+      atomicWriteFileSync(file, openclawPluginSource(options), {
+        mode: 0o600,
+        preserveMode: false,
+        requireCurrentUserOwner: true,
+      })
+      atomicWriteFileSync(path.join(pluginDir, OPENCLAW_PLUGIN_MANIFEST), openclawPluginManifest(), {
+        mode: 0o600,
+        preserveMode: false,
+        requireCurrentUserOwner: true,
+      })
+      atomicWriteFileSync(path.join(pluginDir, OPENCLAW_PLUGIN_PACKAGE), openclawPluginPackage(), {
+        mode: 0o600,
+        preserveMode: false,
+        requireCurrentUserOwner: true,
+      })
+    })
+    writeOpenclawEnablement(deps, pluginDir, options.global)
+  } catch (err) {
+    deps.io.err(String(err))
+    return EXIT.failed
+  }
+  if (options.narrate !== false) printHooksInstallClose(deps, 'openclaw', file)
+  return EXIT.ok
+}
+
+function writeOpenclawEnablement(deps: CommandDeps, pluginDir: string, global: boolean): void {
+  const configFile = openclawConfigPath(deps.env, deps.hookPlatform)
+  withTargetFileLock(configFile, () => {
+    let config: Record<string, unknown> = {}
+    if (existsSync(configFile)) {
+      assertOwnedRegularFile(configFile)
+      config = parseOpenclawConfig(readFileSync(configFile, 'utf8'))
+    }
+    const merged = mergeOpenclawNotifaiEntry(config, pluginDir, global)
+    atomicWriteFileSync(configFile, `${JSON.stringify(merged, null, 2)}\n`, {
+      mode: 0o600,
+      preserveMode: true,
+      requireCurrentUserOwner: true,
+    })
+  })
+}
+
+function uninstallOpenclawPlugin(deps: CommandDeps, file: string): number {
+  const pluginDir = path.dirname(file)
+  try {
+    const removed = withTargetFileLock(file, () => {
+      if (!existsSync(file)) return false
+      assertOwnedRegularFile(file)
+      if (!isOurOpenclawPlugin(readFileSync(file, 'utf8'))) {
+        deps.io.out(`Left ${file} alone: Notifai did not write it.`)
+        return false
+      }
+      rmSync(file, { force: true })
+      rmSync(path.join(pluginDir, OPENCLAW_PLUGIN_MANIFEST), { force: true })
+      rmSync(path.join(pluginDir, OPENCLAW_PLUGIN_PACKAGE), { force: true })
+      if (existsSync(pluginDir) && readdirSync(pluginDir).length === 0) {
+        rmdirSync(pluginDir)
+      }
+      return true
+    })
+    if (removed) {
+      const configFile = openclawConfigPath(deps.env, deps.hookPlatform)
+      if (existsSync(configFile)) {
+        withTargetFileLock(configFile, () => {
+          assertOwnedRegularFile(configFile)
+          const config = parseOpenclawConfig(readFileSync(configFile, 'utf8'))
+          const next = removeOpenclawNotifaiEntry(config, pluginDir)
+          atomicWriteFileSync(configFile, `${JSON.stringify(next, null, 2)}\n`, {
+            mode: 0o600,
+            preserveMode: true,
+            requireCurrentUserOwner: true,
+          })
+        })
+      }
+      deps.io.out(`Removed the Notifai OpenClaw plugin at ${file}`)
+    } else if (!existsSync(file)) {
+      deps.io.out(`Nothing to remove: ${file} does not exist.`)
+    }
+    return EXIT.ok
+  } catch (err) {
+    deps.io.err(String(err))
+    return EXIT.failed
+  }
+}
+
 export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlags): number {
   const harness = resolveHarness(deps, flags.harness)
   if (!harness) return EXIT.usage
@@ -1963,6 +2120,9 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
       return EXIT.failed
     }
   }
+  if (harness === 'openclaw') {
+    return uninstallOpenclawPlugin(deps, file)
+  }
   if (harness === 'cursor') {
     let stripped: ReturnType<typeof removeCursorHooks> | null
     try {
@@ -2049,17 +2209,17 @@ function assertOwnedRegularFile(file: string): void {
   }
 }
 
-function resolveHarness(deps: CommandDeps, requested: string | undefined): Harness | null {
+function resolveHarness(deps: CommandDeps, requested: string | undefined): HookInstallableHarness | null {
   if (requested !== undefined) {
-    if ((HARNESSES as readonly string[]).includes(requested)) return requested as Harness
+    if ((HOOK_INSTALLABLE_HARNESSES as readonly string[]).includes(requested)) return requested as HookInstallableHarness
     deps.io.err(
-      `Unknown harness "${requested}". Supported: ${HARNESSES.join(', ')}.`,
+      `Unknown harness "${requested}". Supported: ${HOOK_INSTALLABLE_HARNESSES.join(', ')}.`,
     )
     return null
   }
   const detected = detectHarness(deps.cwd, deps.env)
   if (!detected) {
-    deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`)
+    deps.io.err(`Could not tell which harness to install for — pass --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>.`)
     return null
   }
   return detected
@@ -2073,7 +2233,7 @@ function resolveHarness(deps: CommandDeps, requested: string | undefined): Harne
 export async function pickHarnessesToInstall(
   deps: CommandDeps,
   requested?: string,
-): Promise<Harness[] | null> {
+): Promise<HookInstallableHarness[] | null> {
   if (requested !== undefined) {
     const harness = resolveHarness(deps, requested)
     return harness === null ? null : [harness]
@@ -2083,7 +2243,7 @@ export async function pickHarnessesToInstall(
   if (deps.io.interactive === true && deps.io.multiselect) {
     const picked = await deps.io.multiselect(
       'Which agent harnesses should Notifai wire here?',
-      HARNESSES.map((name) => ({
+      HOOK_INSTALLABLE_HARNESSES.map((name) => ({
         value: name,
         label: HARNESS_LABELS[name],
         ...(detected.includes(name) ? { hint: 'detected on this machine' } : {}),
@@ -2091,16 +2251,16 @@ export async function pickHarnessesToInstall(
       detected,
     )
     if (picked === null) return null
-    const unknown = picked.filter((name) => !(HARNESSES as readonly string[]).includes(name))
+    const unknown = picked.filter((name) => !(HOOK_INSTALLABLE_HARNESSES as readonly string[]).includes(name))
     if (unknown.length > 0) {
-      deps.io.err(`Unknown harness "${unknown[0]}". Supported: ${HARNESSES.join(', ')}.`)
+      deps.io.err(`Unknown harness "${unknown[0]}". Supported: ${HOOK_INSTALLABLE_HARNESSES.join(', ')}.`)
       return null
     }
-    return picked as Harness[]
+    return picked as HookInstallableHarness[]
   }
   if (detected.length === 0) {
     deps.io.err(
-      `Could not tell which harness to wire. Run: notifai hooks install --harness <${HARNESSES.join('|')}>`,
+      `Could not tell which harness to wire. Run: notifai hooks install --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>`,
     )
     return null
   }

package/src/commands-init.ts

@@ -25,6 +25,7 @@ import { buildDraft, formatReceipt } from './send.js'
 import { loginCommand } from './commands-auth.js'
 import {
   EXIT,
+  SETUP_COMMAND,
   UPDATE_CLI_COMMAND,
   authedClient,
   loadLoggedConfig,
@@ -848,8 +849,8 @@ async function printInitClose(
     await deps.io.note?.(`${blocker.title} — ${blocker.detail}\n${remedyLine(blocker)}`, 'Next')
     deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`)
     deps.io.out(`  ${remedyLine(blocker)}`)
-    if (blocker.remedy?.by === 'user-elsewhere' || blocker.remedy?.by === 'user-here') {
-      deps.io.out('  Then re-run `notifai init` and it will pick up from here.')
+    if (shouldRestateInit(blocker)) {
+      deps.io.out(`  Then re-run \`${SETUP_COMMAND}\` and it will pick up from here.`)
     }
     await deps.io.outro?.('One step remains (above)')
     return
@@ -866,7 +867,12 @@ async function printInitClose(
   }
   deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`)
   deps.io.out(`  ${remedyLine(blocker)}`)
-  if (blocker.remedy?.by === 'user-elsewhere' || blocker.remedy?.by === 'user-here') {
-    deps.io.out('  Then re-run `notifai init` and it will pick up from here.')
+  if (shouldRestateInit(blocker)) {
+    deps.io.out(`  Then re-run \`${SETUP_COMMAND}\` and it will pick up from here.`)
   }
 }
+
+function shouldRestateInit(blocker: ReadinessState): boolean {
+  if (blocker.remedy?.by !== 'user-elsewhere' && blocker.remedy?.by !== 'user-here') return false
+  return !('command' in blocker.remedy) || blocker.remedy.command !== SETUP_COMMAND
+}

package/src/commands-send-support.ts

@@ -5,16 +5,38 @@ import path from 'node:path'
 import { isRetryableReplyPollError, type ApiClient } from './client.js'
 import { fetchMediaUrl } from './url-policy.js'
 import { buildSourceContext, inferInvocationContext } from './invocation-context.js'
+import { readOrcaSessionTitle } from './orca-session-title.js'
 import { type DraftInvocation, type SendFlags } from './send.js'
 import { EXIT, reportError, type CommandDeps } from './commands-core.js'
 import type { ActiveHarnessSession } from './commands-harness-context.js'
 
+function managedSessionTitle(
+  deps: CommandDeps,
+  flags: Pick<SendFlags, 'sessionLabel'>,
+  active: ActiveHarnessSession | null,
+): string | undefined {
+  if (active?.sessionLabel !== undefined) return active.sessionLabel
+  if (
+    active?.sessionId === undefined ||
+    flags.sessionLabel !== undefined ||
+    deps.env['NOTIFAI_SESSION_LABEL'] !== undefined
+  ) {
+    return undefined
+  }
+  try {
+    return (deps.orcaSessionTitle ?? readOrcaSessionTitle)(deps.env)
+  } catch {
+    return undefined
+  }
+}
+
 export function resolveDraftInvocation(
   deps: CommandDeps,
   flags: Pick<SendFlags, 'sessionId' | 'sessionLabel'>,
   active: ActiveHarnessSession | null,
 ): { ok: true; invocation: DraftInvocation } | { ok: false; error: string } {
   const inferred = inferInvocationContext(deps.cwd)
+  const sessionTitle = managedSessionTitle(deps, flags, active)
   const source = buildSourceContext({
     env: deps.env,
     invocation: inferred,
@@ -26,7 +48,7 @@ export function resolveDraftInvocation(
           activeHarness: {
             harness: active.harness,
             ...(active.sessionId === undefined ? {} : { sessionId: active.sessionId }),
-            ...(active.sessionLabel === undefined ? {} : { sessionLabel: active.sessionLabel }),
+            ...(sessionTitle === undefined ? {} : { sessionLabel: sessionTitle }),
             ...(active.sessionLabelPending === true ? { sessionLabelPending: true } : {}),
           },
         }),

package/src/commands-send.ts

@@ -27,7 +27,7 @@ import {
   reportError,
   type CommandDeps,
 } from './commands-core.js'
-import { activeHarnessSession } from './commands-harness-context.js'
+import { sourceContextHarnessSession } from './commands-harness-context.js'
 import { resolveCommandSession } from './command-session.js'
 import {
   beginSendAttempt,
@@ -143,7 +143,7 @@ export async function sendCommand(
   const source = resolveDraftInvocation(
     deps,
     flags,
-    activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)()),
+    sourceContextHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)()),
   )
   if (!source.ok) {
     deps.io.err(source.error)

package/src/commands-sounds.test.ts

@@ -0,0 +1,106 @@
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { ApiClient } from './client.js'
+import { EXIT, type CommandDeps, type CommandIo } from './commands-core.js'
+import { soundsCommand } from './commands-sounds.js'
+
+class CapturedIo implements CommandIo {
+  readonly outLines: string[] = []
+  readonly errLines: string[] = []
+  out(line: string): void {
+    this.outLines.push(line)
+  }
+  err(line: string): void {
+    this.errLines.push(line)
+  }
+  async confirm(): Promise<boolean> {
+    return true
+  }
+  openUrl(): void {}
+}
+
+function makeDeps(io: CapturedIo, client: ApiClient): CommandDeps {
+  const testRoot = path.join(os.tmpdir(), 'notifai-cli-sounds-tests')
+  return {
+    io,
+    store: {
+      load: () => ({
+        machineId: 'mac_test',
+        secret: 'test-secret',
+        baseUrl: 'https://test.notifai.invalid',
+        machineName: 'test-machine',
+      }),
+      save: () => {},
+      clear: () => {},
+      describe: () => 'test credential store',
+    },
+    env: {
+      XDG_CONFIG_HOME: testRoot,
+      XDG_STATE_HOME: path.join(os.tmpdir(), 'notifai-cli-sounds-tests-state'),
+    },
+    cwd: os.tmpdir(),
+    clientFactory: () => client,
+  }
+}
+
+const kitchenTimer = {
+  sound_id: 'snd_kitchen',
+  name: 'Kitchen timer',
+  duration_ms: 2400,
+  content_hash: 'a'.repeat(64),
+  url: 'https://wav.example/kitchen.wav',
+}
+
+describe('soundsCommand', () => {
+  it('lists shipped names and Account custom sounds', async () => {
+    const io = new CapturedIo()
+    const client = {
+      listSounds: async () => ({ sounds: [kitchenTimer] }),
+    } as unknown as ApiClient
+
+    expect(await soundsCommand(makeDeps(io, client), {})).toBe(EXIT.ok)
+    expect(io.outLines[0]).toBe('default  Device default')
+    expect(io.outLines).toContain('done  completion chime')
+    expect(io.outLines).toContain('none  silent')
+    expect(io.outLines.at(-1)).toBe('snd_kitchen  Kitchen timer  2.4s')
+  })
+
+  it('prints the catalog as JSON when asked', async () => {
+    const io = new CapturedIo()
+    const client = {
+      listSounds: async () => ({ sounds: [kitchenTimer] }),
+    } as unknown as ApiClient
+
+    expect(await soundsCommand(makeDeps(io, client), { json: true })).toBe(EXIT.ok)
+    const parsed = JSON.parse(io.outLines.join('\n')) as {
+      shipped: { ref: string; name: string }[]
+      custom: typeof kitchenTimer[]
+    }
+    expect(parsed.shipped[0]).toEqual({ ref: 'default', name: 'Device default' })
+    expect(parsed.custom).toEqual([kitchenTimer])
+  })
+
+  it('refuses to list custom sounds when this machine is not signed in', async () => {
+    const io = new CapturedIo()
+    let calls = 0
+    const deps: CommandDeps = {
+      ...makeDeps(io, {
+        listSounds: async () => {
+          calls += 1
+          return { sounds: [] }
+        },
+      } as unknown as ApiClient),
+      store: {
+        load: () => null,
+        save: () => {},
+        clear: () => {},
+        describe: () => 'empty store',
+      },
+    }
+
+    expect(await soundsCommand(deps, {})).toBe(EXIT.auth)
+    expect(calls).toBe(0)
+    expect(io.errLines.join('\n')).toMatch(/not signed in/i)
+  })
+})

package/src/commands-sounds.ts

@@ -0,0 +1,49 @@
+import type { ListSoundsResponse, SoundView } from '@raidiant/notifai-protocol'
+import {
+  EXIT,
+  authedClient,
+  loadLoggedConfig,
+  reportError,
+  type CommandDeps,
+} from './commands-core.js'
+import { SHIPPED_SOUND_LISTING } from './sound-ref.js'
+
+export interface SoundsListing {
+  shipped: readonly { ref: string; name: string }[]
+  custom: SoundView[]
+}
+
+function formatSoundDuration(ms: number): string {
+  const seconds = ms / 1000
+  const text = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(1)
+  return `${text}s`
+}
+
+export async function soundsCommand(
+  deps: CommandDeps,
+  flags: { json?: boolean },
+): Promise<number> {
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  try {
+    const result: ListSoundsResponse = await authed.client.listSounds()
+    const listing: SoundsListing = {
+      shipped: SHIPPED_SOUND_LISTING,
+      custom: result.sounds,
+    }
+    if (flags.json) {
+      deps.io.out(JSON.stringify(listing, null, 2))
+      return EXIT.ok
+    }
+    for (const sound of listing.shipped) {
+      deps.io.out(`${sound.ref}  ${sound.name}`)
+    }
+    for (const sound of listing.custom) {
+      deps.io.out(`${sound.sound_id}  ${sound.name}  ${formatSoundDuration(sound.duration_ms)}`)
+    }
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err)
+  }
+}