@raidiant/notifai 9.3.0 → 10.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "9.3.0",
+  "version": "10.1.0",
   "type": "module",
   "description": "Send native device notifications from agents and local programs",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "5.0.2",
+    "@raidiant/notifai-protocol": "6.0.1",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"
@@ -31,7 +31,7 @@
     "vitest": "^3.2.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "license": "Apache-2.0",
   "author": "Rafael Vidaurre",

package/src/client.test.ts

@@ -110,6 +110,18 @@ describe('a server that never answers', () => {
     ])
   })
 
+  it('lists Account custom sounds from the catalog endpoint', async () => {
+    let seen: string | undefined
+    const baseUrl = await serving((request, response) => {
+      seen = `${request.method} ${request.url}`
+      response.setHeader('content-type', 'application/json')
+      response.end(JSON.stringify({ sounds: [] }))
+    })
+    const result = await createClient(baseUrl, 'Bearer test').listSounds()
+    expect(seen).toBe('GET /api/v1/sounds')
+    expect(result).toEqual({ sounds: [] })
+  })
+
   it('refuses redirects on bearer-authenticated calls', async () => {
     let followed = false
     const baseUrl = await serving((request, response) => {

package/src/client.ts

@@ -9,6 +9,7 @@ import type {
   EvidenceSnapshot,
   GetAgentAcknowledgementResponse,
   ListDevicesResponse,
+  ListSoundsResponse,
   ClientCapability,
   CompatibilityResponse,
   RecoveryAction,
@@ -17,6 +18,8 @@ import type {
   PollPairingResponse,
   PutAgentAcknowledgementRequestT,
   PutAgentAcknowledgementResponse,
+  PutAgentSessionLabelRequestT,
+  AgentSessionView,
   SubmissionReceipt,
   SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
@@ -76,6 +79,7 @@ export interface ApiClient {
   pollPairing(pairingId: string, pollVerifier: string): Promise<PollPairingResponse>
   accessStatus(): Promise<AccountAccessResponse>
   listDevices(): Promise<ListDevicesResponse>
+  listSounds(): Promise<ListSoundsResponse>
   capabilities(
     platform?: Platform,
     appVersion?: string,
@@ -94,6 +98,7 @@ export interface ApiClient {
     requestId: string,
     body: PutAgentAcknowledgementRequestT,
   ): Promise<PutAgentAcknowledgementResponse>
+  putAgentSessionLabel(body: PutAgentSessionLabelRequestT): Promise<AgentSessionView>
   agentAcknowledgement(
     requestId: string,
     options: { waitSeconds: number },
@@ -250,6 +255,7 @@ export function createClient(
       }),
     accessStatus: () => call('GET', '/api/v1/account/access'),
     listDevices: () => call('GET', '/api/v1/devices'),
+    listSounds: () => call('GET', '/api/v1/sounds'),
     capabilities: (platform = 'ios', appVersion, appBuild) => {
       const query = new URLSearchParams()
       if (appVersion !== undefined) query.set('app_version', appVersion)
@@ -279,6 +285,8 @@ export function createClient(
         `/api/v1/notifications/${encodeURIComponent(requestId)}/agent-acknowledgement`,
         body,
       ),
+    putAgentSessionLabel: (body) =>
+      call<AgentSessionView>('PUT', '/api/v1/agent-sessions/label', body),
     agentAcknowledgement: (requestId, { waitSeconds }) =>
       call<GetAgentAcknowledgementResponse>(
         'GET',

package/src/commands-agent-sessions.ts

@@ -0,0 +1,72 @@
+import { resolveActiveHarness } from './commands-harness-context.js'
+import {
+  authedClient,
+  EXIT,
+  loadLoggedConfig,
+  reportError,
+  type CommandDeps,
+} from './commands-core.js'
+import {
+  normalizeExplicitSessionLabel,
+  renameStoredSessionLabel,
+} from './session-labels.js'
+
+export interface AgentSessionRenameFlags {
+  json?: boolean
+}
+
+/** Rename only the exact harness-owned Agent Session running this command. */
+export async function agentSessionRenameCommand(
+  deps: CommandDeps,
+  label: string,
+  flags: AgentSessionRenameFlags = {},
+): Promise<number> {
+  const now = deps.now?.() ?? Date.now()
+  const resolution = resolveActiveHarness(deps.env, deps.cwd, now)
+  const active = resolution.active
+  if (resolution.contested.length > 0 || active?.sessionId === undefined) {
+    deps.io.err(
+      'No exact active Agent Session can be proven here. Run this command inside the Agent Session you intend to rename.',
+    )
+    return EXIT.usage
+  }
+
+  const normalized = normalizeExplicitSessionLabel({
+    env: deps.env,
+    sessionId: active.sessionId,
+    label,
+  })
+  if (!normalized.ok) {
+    deps.io.err(normalized.error)
+    return EXIT.usage
+  }
+
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const auth = authedClient(deps, config)
+  if (!auth) return EXIT.auth
+  try {
+    const renamed = await auth.client.putAgentSessionLabel({
+      session_id: active.sessionId,
+      label: normalized.label,
+    })
+    const local = renameStoredSessionLabel({
+      env: deps.env,
+      sessionId: active.sessionId,
+      label: renamed.label,
+      harness: active.harness,
+      now,
+    })
+    if (!local.ok) {
+      deps.io.err(local.error)
+      return EXIT.failed
+    }
+    deps.io.out(
+      flags.json
+        ? JSON.stringify(renamed)
+        : `Agent Session renamed to "${renamed.label}" across your Notifai account.`,
+    )
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err, { operation: 'agent_session_rename' })
+  }
+}

package/src/commands-auth.ts

@@ -7,6 +7,7 @@ import { type FlagOverrides } from './config.js'
 import { checkApproveUrl } from './url-policy.js'
 import {
   EXIT,
+  SETUP_COMMAND,
   authedClient,
   loadLoggedConfig,
   makeClient,
@@ -128,14 +129,14 @@ export async function loginCommand(
       spinner?.error('Account has no Alpha access')
       deps.io.err('This account has no active plan or temporary Alpha access.')
       deps.io.err(`next: ${next}`)
-      deps.io.err('After access is granted, run `notifai login` again.')
+      deps.io.err(`After access is granted, run \`${SETUP_COMMAND}\` again.`)
       return EXIT.auth
     }
     if (poll.status === 'expired') break
     spinner?.message(approvalWaitMessage())
   }
   spinner?.error('Pairing expired')
-  deps.io.err('Pairing expired before it was approved. Run `notifai login` again.')
+  deps.io.err(`Pairing expired before it was approved. Run \`${SETUP_COMMAND}\` again.`)
   return EXIT.auth
 }
 
@@ -166,7 +167,7 @@ export function authStatusCommand(deps: CommandDeps, flags: { json?: boolean }):
     return credential ? EXIT.ok : EXIT.auth
   }
   if (!credential) {
-    deps.io.err('Not signed in. Run `notifai login`.')
+    deps.io.err(`Not signed in. Run \`${SETUP_COMMAND}\`; it will coordinate machine login and device setup.`)
     return EXIT.auth
   }
   deps.io.out(`Signed in as machine "${credential.machineName}" (${credential.machineId})`)

package/src/commands-config.ts

@@ -26,6 +26,7 @@ import {
 import { normalizeOrigin } from './url-policy.js'
 import { renderConfigExplain, renderConfigList, renderConfigPlain } from './ui/config-view.js'
 import { EXIT, loadLoggedConfig, type CommandDeps } from './commands-core.js'
+import { isCliSoundRef } from './sound-ref.js'
 
 // ---------------------------------------------------------------------------
 // config show / set / unset
@@ -186,10 +187,15 @@ export async function configSetCommand(
     }
     value = rawValue === 'true'
   }
-  // Enum keys were accepted unchecked, so `config set sound whatever` wrote a
-  // value the sender would later reject — a typo that only surfaces at the
-  // moment a notification fails to carry the sound you asked for.
-  if (info.kind === 'enum' && info.choices !== undefined && !info.choices.includes(rawValue)) {
+  // Sound is listed as an enum of shipped names so the interactive picker has
+  // choices, but it also accepts an Account custom name or id. Other enum keys
+  // stay closed: an unrecognised value used to be written and only fail at send.
+  if (configKey === 'sound') {
+    if (!isCliSoundRef(rawValue)) {
+      deps.io.err(`${key} takes ${acceptedValues(configKey)} — not "${rawValue}".`)
+      return EXIT.usage
+    }
+  } else if (info.kind === 'enum' && info.choices !== undefined && !info.choices.includes(rawValue)) {
     deps.io.err(`${key} takes one of: ${info.choices.join(', ')} — not "${rawValue}".`)
     return EXIT.usage
   }

package/src/commands-core.ts

@@ -13,6 +13,7 @@ import type { CredentialStore, MachineCredential } from './credentials.js'
 import { type HookAdapterTarget } from './hook-adapter.js'
 import { logConfigResolved, logSettingsFrom, nullLogger, type Logger } from './logging.js'
 import type { NativeSkills } from './native-skills.js'
+import type { OrcaSessionTitleLookup } from './orca-session-title.js'
 import { packageVersion } from './release.js'
 import type { Tone } from './ui/theme.js'
 
@@ -81,6 +82,8 @@ export interface CommandDeps {
   codexSourcePid?: number
   /** Test seam and production adapter for the external native skills installer. */
   nativeSkills?: NativeSkills
+  /** Test seam for Orca's exact-worktree task/session title lookup. */
+  orcaSessionTitle?: OrcaSessionTitleLookup
   /** Test seam for registry reads; production uses fetch. */
   fetchImpl?: typeof fetch
   /**
@@ -183,6 +186,9 @@ export function authedClient(deps: CommandDeps, config: CliConfig): { client: Ap
 
 export const UPDATE_CLI_COMMAND = 'npm install -g @raidiant/notifai'
 
+/** The one first-run command an unsigned machine is told to run. */
+export const SETUP_COMMAND = 'notifai init'
+
 function affectedDeviceNames(details: unknown): string[] {
   if (typeof details !== 'object' || details === null || !('device_names' in details)) return []
   const names = (details as { device_names?: unknown }).device_names

package/src/commands-doctor.ts

@@ -5,7 +5,12 @@ import { inspectClaudeInbox, systemClaudeWakeAdapters } from './claude-wake.js'
 import { ApiCallError, type ApiClient } from './client.js'
 import { inspectCodexResume } from './codex-wake.js'
 import { type CliConfig } from './config.js'
-import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js'
+import {
+  HARNESS_CAPABILITIES,
+  HARNESS_LABELS,
+  HERMES_QUESTION_ROUTING_UNAVAILABLE,
+  isHookInstallableHarness,
+} from './harnesses.js'
 import { inspectHookAdapter } from './hook-adapter.js'
 import {
   readLiveProjectSessionPointers,
@@ -43,6 +48,7 @@ import type { Tone } from './ui/theme.js'
 import type { MachineCredential } from './credentials.js'
 import {
   EXIT,
+  SETUP_COMMAND,
   UPDATE_CLI_COMMAND,
   diagnoseIgnoredOriginOverride,
   loadLoggedConfig,
@@ -52,7 +58,6 @@ import {
 } from './commands-core.js'
 import { deviceInstallRemedy, readyCompanionDevices, supportPageUrl } from './commands-devices.js'
 import {
-  activeHarnessSession,
   claudeSessionPid,
   resolveActiveHarness,
   type ActiveHarnessSession,
@@ -299,6 +304,94 @@ function remoteInvalidatedByConfig(
   return server === undefined || !server.detail.includes(origin)
 }
 
+function isNoActivePlanError(err: unknown): err is ApiCallError {
+  return err instanceof ApiCallError && err.code === 'no_active_plan'
+}
+
+/**
+ * Device listing is grant-gated; access status is not. A paired Account whose
+ * plan lapsed must not be diagnosed as a revoked machine.
+ */
+async function probeAccount(
+  client: ApiClient,
+  credential: MachineCredential,
+  baseUrl: string,
+): Promise<{
+  email: string | null
+  devices: RoutableDevice[] | null
+  lookupFailed: boolean
+  auth: ReadinessState
+}> {
+  const [devicesOutcome, accessOutcome] = await Promise.allSettled([
+    Promise.resolve().then(() => client.listDevices()),
+    Promise.resolve().then(() => client.accessStatus()),
+  ])
+  const access = accessOutcome.status === 'fulfilled' ? accessOutcome.value : null
+  const devices = devicesOutcome.status === 'fulfilled' ? devicesOutcome.value.devices : null
+  const email = access?.email ?? null
+  const devicesErr = devicesOutcome.status === 'rejected' ? devicesOutcome.reason : null
+  const noActivePlan =
+    access?.status === 'no_active_plan' || isNoActivePlanError(devicesErr)
+
+  if (noActivePlan) {
+    const next =
+      (isNoActivePlanError(devicesErr) ? devicesErr.nextAction : null) ??
+      `Open ${supportPageUrl(baseUrl)} to request Alpha access, then retry.`
+    return {
+      email,
+      devices: null,
+      lookupFailed: true,
+      auth: {
+        id: 'auth',
+        title: 'Account',
+        status: 'gap',
+        detail: email
+          ? `no active plan or temporary Alpha access (${email})`
+          : 'no active plan or temporary Alpha access',
+        remedy: {
+          by: 'user-elsewhere',
+          summary: next,
+        },
+      },
+    }
+  }
+
+  if (devices !== null) {
+    return {
+      email,
+      devices,
+      lookupFailed: false,
+      auth: {
+        id: 'auth',
+        title: 'Account',
+        status: 'ready',
+        detail: email
+          ? `machine ${credential.machineId} accepted (${email})`
+          : `machine ${credential.machineId} accepted`,
+      },
+    }
+  }
+
+  const err = devicesErr ?? (accessOutcome.status === 'rejected' ? accessOutcome.reason : null)
+  return {
+    email: null,
+    devices: null,
+    lookupFailed: true,
+    auth: {
+      id: 'auth',
+      title: 'Account',
+      status: 'gap',
+      detail: err instanceof ApiCallError ? `${err.code}: ${err.message}` : String(err),
+      remedy: {
+        by: 'user-here',
+        summary: 'this machine is no longer recognised; pair it again',
+        command: SETUP_COMMAND,
+        interactive: true,
+      },
+    },
+  }
+}
+
 /**
  * Read the whole setup once, in dependency order.
  *
@@ -374,7 +467,7 @@ export async function assessReadiness(
           remedy: {
             by: 'user-here',
             summary: 'sign in — this opens your browser to approve the machine',
-            command: 'notifai login',
+            command: SETUP_COMMAND,
             interactive: true,
           },
         },
@@ -433,39 +526,11 @@ export async function assessReadiness(
   } else {
     const client = makeClient(deps, baseUrl, `Bearer nfm_${credential.machineId}.${credential.secret}`)
     accountClient = client
-    try {
-      const [{ devices }, email] = await Promise.all([
-        client.listDevices(),
-        Promise.resolve()
-          .then(async () => (await client.accessStatus()).email)
-          .catch(() => null as string | null),
-      ])
-      accountDevices = devices
-      accountEmail = email
-      states.push({
-        id: 'auth',
-        title: 'Account',
-        status: 'ready',
-        detail: accountEmail
-          ? `machine ${credential.machineId} accepted (${accountEmail})`
-          : `machine ${credential.machineId} accepted`,
-      })
-    } catch (err) {
-      // A credential the server rejects is revocation, not absence, and the
-      // remedy is the same sign-in either way.
-      accountLookupFailed = true
-      states.push({
-        id: 'auth',
-        title: 'Account',
-        status: 'gap',
-        detail: err instanceof ApiCallError ? `${err.code}: ${err.message}` : String(err),
-        remedy: {
-          by: 'user-here',
-          summary: 'this machine is no longer recognised; pair it again',
-          command: 'notifai login',
-        },
-      })
-    }
+    const probed = await probeAccount(client, credential, baseUrl)
+    accountDevices = probed.devices
+    accountEmail = probed.email
+    accountLookupFailed = probed.lookupFailed
+    states.push(probed.auth)
   }
 
   // Optional setup that works without a companion device must appear before the
@@ -761,7 +826,11 @@ export function remedyLine(state: ReadinessState): string {
  */
 function hookStates(deps: CommandDeps): ReadinessState[] {
   const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform)
-  const active = activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)())
+  const { active, contested } = resolveActiveHarness(
+    deps.env,
+    deps.cwd,
+    (deps.now ?? Date.now)(),
+  )
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const settings: ReadinessState = {
     id: 'question-routing-settings',
@@ -782,6 +851,28 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
         }),
   }
   if (installations.length === 0) {
+    if (contested.length > 1) {
+      return [
+        {
+          id: 'hooks',
+          title: 'Question routing',
+          status: 'optional-gap',
+          detail: `Several harness sessions could own this shell (${contested.map((candidate) => candidate.label).join(', ')}); routing readiness is intentionally not attributed to either one`,
+        },
+        settings,
+      ]
+    }
+    if (active !== null && !isHookInstallableHarness(active.harness)) {
+      return [
+        {
+          id: 'hooks',
+          title: 'Question routing',
+          status: 'optional-gap',
+          detail: `${active.label}: ${HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryContract}`,
+        },
+        settings,
+      ]
+    }
     return [
       {
         id: 'hooks',
@@ -925,7 +1016,21 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
     active === null
       ? []
       : installations.filter((installation) => installation.harness === active.harness)
-  if (active !== null) {
+  if (contested.length > 1) {
+    checks.push({
+      name: 'hooks (active harness)',
+      ok: false,
+      informational: true,
+      detail: `Several harness sessions could own this shell (${contested.map((candidate) => candidate.label).join(', ')}); routing readiness is intentionally not attributed to either one`,
+    })
+  } else if (active !== null && !isHookInstallableHarness(active.harness)) {
+    checks.push({
+      name: 'hooks (active harness)',
+      ok: true,
+      informational: true,
+      detail: `${active.label}: ${HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryContract}`,
+    })
+  } else if (active !== null) {
     checks.push({
       name: 'hooks (active harness)',
       ok: activeInstallations.length > 0,

package/src/commands-harness-context.ts

@@ -1,5 +1,10 @@
+import {
+  hermesClassicCliLocalInstance,
+  isHookInstallableHarness,
+  type HermesClassicCliLocalInstance,
+  type SourceContextHarness,
+} from './harnesses.js'
 import { readLiveProjectSessionPointers, readSessionState } from './hooks.js'
-import { type Harness } from './install-hooks.js'
 
 /**
  * Exact evidence that this shell command is running inside one supported
@@ -7,11 +12,17 @@ import { type Harness } from './install-hooks.js'
  * describe where a tool stores files, not which tool owns the current shell.
  * OpenCode's generated plugin supplies the Notifai-owned marker because its
  * plugin API exposes Agent Session identity but the ordinary environment does not.
+ *
+ * Hermes contributes `HERMES_SESSION_ID` only — the durable Agent Session id
+ * bridged into tool subprocesses. `HERMES_SESSION_KEY` is a gateway routing
+ * key and must never be treated as Agent Session identity.
  */
 export interface ActiveHarnessSession {
-  harness: Harness
+  harness: SourceContextHarness
   label: string
   sessionId?: string
+  /** Exact surface/backend cell proven for this marker envelope. */
+  integrationInstance?: HermesClassicCliLocalInstance
   /** Trusted human title published by this harness's managed adapter. */
   sessionLabel?: string
   /** The harness has only a temporary placeholder title so far. */
@@ -40,6 +51,14 @@ function harnessEnvCandidates(env: NodeJS.ProcessEnv): ActiveHarnessSession[] {
       ...(sessionLabelPending ? { sessionLabelPending: true } : {}),
     })
   }
+  if (env['NOTIFAI_ACTIVE_HARNESS'] === 'openclaw') {
+    const sessionId = env['NOTIFAI_ACTIVE_SESSION_ID']
+    candidates.push({
+      harness: 'openclaw',
+      label: 'OpenClaw',
+      ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
+    })
+  }
   if (env['CLAUDECODE'] === '1') {
     const sessionId = env['CLAUDE_CODE_SESSION_ID']
     candidates.push({
@@ -53,6 +72,16 @@ function harnessEnvCandidates(env: NodeJS.ProcessEnv): ActiveHarnessSession[] {
     candidates.push({ harness: 'codex', label: 'Codex', sessionId: codexSession })
   }
   if ((env['CURSOR_AGENT'] ?? '') !== '') candidates.push({ harness: 'cursor', label: 'Cursor' })
+  const hermesSession = env['HERMES_SESSION_ID']
+  if (hermesSession !== undefined && hermesSession !== '') {
+    const integrationInstance = hermesClassicCliLocalInstance(env)
+    candidates.push({
+      harness: 'hermes',
+      label: 'Hermes',
+      sessionId: hermesSession,
+      ...(integrationInstance === null ? {} : { integrationInstance }),
+    })
+  }
   return candidates
 }
 
@@ -97,6 +126,12 @@ export function resolveActiveHarness(
   if (first === undefined) return { active: null, contested: [] }
   if (candidates.length === 1) return { active: first, contested: [] }
 
+  // A send-only harness has no hook evidence, so live pointer/state of a
+  // hook-installable parent cannot prove which nested process owns this
+  // shell. Mixing Hermes with another marker therefore stays contested.
+  const mixedWithSendOnly = candidates.some((candidate) => !isHookInstallableHarness(candidate.harness))
+  if (mixedWithSendOnly) return { active: first, contested: candidates }
+
   // Exact lifecycle state is machine-global and survives a command moving to
   // another linked checkout. Prefer it before the checkout-local
   // pointer. A unique newest hook event proves which nested harness owns this
@@ -133,6 +168,25 @@ export function activeHarnessSession(
   return resolveActiveHarness(env, cwd, now).active
 }
 
+/**
+ * Source Context attribution. Hook-installable nesting still uses declared
+ * order when nothing has fired — that existing send behavior is preserved.
+ * A contested mix that includes a send-only harness (Hermes) fails closed:
+ * the wrong Agent Session would otherwise be named as the owner.
+ */
+export function sourceContextHarnessSession(
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  now: number,
+): ActiveHarnessSession | null {
+  const { active, contested } = resolveActiveHarness(env, cwd, now)
+  if (contested.some((candidate) => !isHookInstallableHarness(candidate.harness))) {
+    return null
+  }
+  if (active?.harness === 'hermes' && active.integrationInstance === undefined) return null
+  return active
+}
+
 /**
  * The pid of the Claude Code session this hook belongs to.
  *