@raidiant/notifai 7.0.2 → 9.0.0

package/src/send.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import {
+  accidentalEscapedNewlineMessage,
+  hasAccidentalEscapedNewlines,
+  rejectAccidentalEscapedNewlines,
+} from './send.js'
+
+describe('accidental escaped newlines', () => {
+  it('catches a shell-quoted backslash-n body', () => {
+    expect(hasAccidentalEscapedNewlines('line1\\nline2')).toBe(true)
+    expect(rejectAccidentalEscapedNewlines('line1\\nline2', false)).toBe(
+      accidentalEscapedNewlineMessage(),
+    )
+  })
+
+  it('preserves real multiline Markdown', () => {
+    expect(hasAccidentalEscapedNewlines('line1\nline2')).toBe(false)
+    expect(rejectAccidentalEscapedNewlines('line1\nline2', false)).toBeNull()
+  })
+
+  it('lets an explicit flag keep visible backslash-n text', () => {
+    expect(rejectAccidentalEscapedNewlines('use \\n in the sample', true)).toBeNull()
+  })
+
+  it('does not treat an escaped backslash plus n as accidental', () => {
+    expect(hasAccidentalEscapedNewlines('escape as \\\\n')).toBe(false)
+  })
+})

package/src/send.ts

@@ -6,6 +6,7 @@ import {
   NOTIFICATION_SCHEMA_VERSION,
   QUESTION_TEXT_MAX_LENGTH,
   bannerExcerpt,
+  type AndroidOptionsT,
   type IosOptionsT,
   type LifecycleT,
   type MacosOptionsT,
@@ -30,7 +31,6 @@ export interface SendFlags {
   /** The one canonical Markdown body. */
   body: string
   subtitle?: string
-  event?: string
   /** What this notification is; absent means update. */
   kind?: string
   project?: string
@@ -44,7 +44,8 @@ export interface SendFlags {
   collapseKey?: string
   sound?: string
   threadId?: string
-  level?: string
+  /** Apple interruption level; null is reserved for internal callers that must suppress config. */
+  level?: string | null
   data?: string[]
   /** Ready media ids in author-supplied order. Commands resolve paths and URLs first. */
   image?: string[]
@@ -63,9 +64,9 @@ export interface SendFlags {
    * Answer labels; turns the reply into a closed question. One flag occurrence
    * per label, always — a label is a label, whatever characters it contains.
    */
-  replyChoice?: string[]
+  choice?: string[]
   /** The user may select several of the offered answers. */
-  replyMulti?: boolean
+  multi?: boolean
   /**
    * A full question set, overriding the single question the flags describe.
    * Not a user-facing flag: `ask --form` and the hooks build it.
@@ -78,6 +79,34 @@ export interface SendFlags {
    * questions and their retirements ride the wire as what they are.
    */
   lifecycle?: LifecycleT
+  /**
+   * Allow the two-character sequence backslash-n to be sent as visible text.
+   * Without this, a likely accidental escaped newline is refused.
+   */
+  literalBackslashN?: boolean
+}
+
+/** A backslash-n pair that was not itself escaped as a literal backslash. */
+const ACCIDENTAL_ESCAPED_NEWLINE = /(?:^|[^\\])\\n/
+
+export function hasAccidentalEscapedNewlines(body: string): boolean {
+  return ACCIDENTAL_ESCAPED_NEWLINE.test(body)
+}
+
+export function accidentalEscapedNewlineMessage(): string {
+  return [
+    'This body contains the two-character sequence \\n, which is sent literally and shows as \\n on the device.',
+    'To send a real line break, pass a multiline --body or --body-file -.',
+    'If you meant the visible characters \\n, pass --literal-backslash-n.',
+  ].join('\n')
+}
+
+export function rejectAccidentalEscapedNewlines(
+  body: string | undefined,
+  allowLiteral: boolean | undefined,
+): string | null {
+  if (allowLiteral === true || body === undefined) return null
+  return hasAccidentalEscapedNewlines(body) ? accidentalEscapedNewlineMessage() : null
 }
 
 export type DraftBuild =
@@ -200,7 +229,8 @@ export function buildDraft(
       error: `Unknown sound "${sound}" — supported: ${CLI_SOUNDS.map((value) => `"${value}"`).join(', ')}.`,
     }
   }
-  const level = flags.level ?? config.interruption_level.value
+  const level =
+    flags.level !== undefined ? flags.level : config.interruption_level.value
   if (
     level !== null &&
     level !== undefined &&
@@ -208,15 +238,30 @@ export function buildDraft(
   ) {
     return { ok: false, error: `Unknown interruption level "${level}".` }
   }
+  if (platform === 'android' && level !== null && level !== undefined) {
+    return {
+      ok: false,
+      error:
+        'Android does not support caller-selected interruption levels. Remove --level or unset the configured interruption_level; kind, notification channels, and device settings own attention on Android.',
+    }
+  }
 
-  const options: IosOptionsT & MacosOptionsT = {}
-  if (sound === 'none') options.sound = null
-  else if (sound !== null && sound !== undefined) {
-    options.sound = sound as Exclude<(typeof CLI_SOUNDS)[number], 'none'>
+  const appleOptions: IosOptionsT & MacosOptionsT = {}
+  const androidOptions: AndroidOptionsT = {}
+  if (sound === 'none') {
+    appleOptions.sound = null
+    androidOptions.sound = null
+  } else if (sound !== null && sound !== undefined) {
+    const semanticSound = sound as Exclude<(typeof CLI_SOUNDS)[number], 'none'>
+    appleOptions.sound = semanticSound
+    androidOptions.sound = semanticSound
+  }
+  if (flags.threadId !== undefined) {
+    appleOptions.thread_id = flags.threadId
+    androidOptions.thread_id = flags.threadId
   }
-  if (flags.threadId !== undefined) options.thread_id = flags.threadId
   if (level !== null && level !== undefined) {
-    options.interruption_level = level as (typeof INTERRUPTION_LEVELS)[number]
+    appleOptions.interruption_level = level as (typeof INTERRUPTION_LEVELS)[number]
   }
   if (flags.data?.length) {
     const data: Record<string, string> = {}
@@ -225,7 +270,8 @@ export function buildDraft(
       if (eq <= 0) return { ok: false, error: `--data expects key=value, got "${pair}".` }
       data[pair.slice(0, eq)] = pair.slice(eq + 1)
     }
-    options.custom_data = data
+    appleOptions.custom_data = data
+    androidOptions.custom_data = data
   }
 
   const ttl = flags.ttl ?? config.ttl_seconds.value
@@ -245,15 +291,15 @@ export function buildDraft(
 
   // Ids are derived from labels so an agent writing a one-liner does not have
   // to invent them, but they stay the stable thing it branches on afterwards.
-  const choices = parseChoices(flags.replyChoice)
+  const choices = parseChoices(flags.choice)
   if (choices === 'invalid') {
     return {
       ok: false,
-      error: REPLY_CHOICE_USAGE,
+      error: CHOICE_USAGE,
     }
   }
-  if (flags.replyMulti && choices === null && flags.questions === undefined) {
-    return { ok: false, error: '--reply-multi needs answers to select between; add --reply-choice.' }
+  if (flags.multi && choices === null && flags.questions === undefined) {
+    return { ok: false, error: '--multi needs answers to select between; add --choice.' }
   }
   // A single reply question is the first readable block of the canonical body.
   // Context may follow after a blank line without changing what the user answers.
@@ -271,9 +317,25 @@ export function buildDraft(
     }
   }
 
+  const hasAppleOptions = Object.keys(appleOptions).length > 0
+  const hasAndroidOptions = Object.keys(androidOptions).length > 0
+  let platformOptions: NonNullable<NotificationDraftT['platform']> | undefined
+  if (flags.platform === undefined) {
+    if (hasAppleOptions || hasAndroidOptions) {
+      platformOptions = {
+        ...(hasAppleOptions ? { ios: appleOptions, macos: appleOptions } : {}),
+        ...(hasAndroidOptions ? { android: androidOptions } : {}),
+      }
+    }
+  } else if (platform === 'android') {
+    if (hasAndroidOptions) platformOptions = { android: androidOptions }
+  } else if (hasAppleOptions) {
+    platformOptions =
+      platform === 'ios' ? { ios: appleOptions } : { macos: appleOptions }
+  }
+
   const draft: NotificationDraftT = {
     schema_version: NOTIFICATION_SCHEMA_VERSION,
-    ...(flags.event !== undefined ? { event: flags.event } : {}),
     ...(flags.kind !== undefined
       ? { kind: flags.kind as (typeof NOTIFICATION_KINDS)[number] }
       : {}),
@@ -297,19 +359,13 @@ export function buildDraft(
                 id: 'q1',
                 text: derivedQuestion,
                 ...(choices !== null ? { choices } : {}),
-                ...(flags.replyMulti ? { multi: true } : {}),
+                ...(flags.multi ? { multi: true } : {}),
               },
             ],
           },
         }
       : {}),
-    ...(Object.keys(options).length > 0
-      ? flags.platform === undefined
-        ? { platform: { ios: options, macos: options } }
-        : platform === 'ios'
-          ? { platform: { ios: options } }
-          : { platform: { macos: options } }
-      : {}),
+    ...(platformOptions !== undefined ? { platform: platformOptions } : {}),
   }
   return { ok: true, draft, platform }
 }
@@ -369,19 +425,10 @@ export function parseChoices(
 }
 
 /** Message shared by every surface that accepts choice labels. */
-/** `ask` spells this flag `--choice`. */
 export const CHOICE_USAGE =
   'Offer 2-6 answers, one --choice flag per answer, unique once slugified — ' +
   'e.g. --choice "Yes, ship it" --choice "Not yet".'
 
-/**
- * `send` spells the same flag `--reply-choice`, and a remedy that names the
- * other command's flag reproduces the error it is trying to fix.
- */
-export const REPLY_CHOICE_USAGE =
-  'Offer 2-6 answers, one --reply-choice flag per answer, unique once slugified — ' +
-  'e.g. --reply-choice "Yes, ship it" --reply-choice "Not yet".'
-
 export function slugify(label: string): string {
   return label
     .toLowerCase()

package/src/session-activation.ts

@@ -0,0 +1,45 @@
+import type { HookHarness } from './hooks.js'
+
+/**
+ * Model-visible session bootstrap. It names the installed capability and its
+ * authoritative sources without restating any notification policy that the
+ * user may have overridden.
+ */
+export const SESSION_ACTIVATION_CONTEXT =
+  'Notifai is active for this session, even when the user did not mention it. ' +
+  'Before beginning task work, use the Notifai skill and run `notifai guidance`; its resolved guidance governs notification decisions for Agent Events. ' +
+  'Missing skill or CLI readiness is handled through `notifai init` and its diagnosis. ' +
+  'For delegated work, the parent owns User-visible Notification Requests unless it explicitly delegates that ownership; workers report Agent Events to the parent and do not send independently.'
+
+/** One lifecycle meaning, encoded for each harness output contract. */
+export function sessionActivationOutput(
+  harness: HookHarness | undefined,
+  hookEventName: 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit',
+): string | undefined {
+  if (harness === 'cursor') {
+    return JSON.stringify({ additional_context: SESSION_ACTIVATION_CONTEXT })
+  }
+  if (harness === 'claude-code' || harness === 'codex') {
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName,
+        additionalContext: SESSION_ACTIVATION_CONTEXT,
+      },
+    })
+  }
+  return undefined
+}
+
+/**
+ * Cursor currently accepts sessionStart context without reliably delivering it
+ * to the model. Its native post-Stop follow-up is the narrow fallback and is
+ * claimed once per conversation by the hook-state layer.
+ */
+export function cursorStopActivationOutput(): string {
+  return JSON.stringify({
+    followup_message: SESSION_ACTIVATION_CONTEXT.replace(
+      'Before beginning task work,',
+      'Before finalizing the Agent Event from the turn that just ended,',
+    ),
+  })
+}

package/src/session-labels.test.ts

@@ -46,6 +46,38 @@ describe('semantic session labels', () => {
     ).toEqual({ ok: true, label: 'Semantic session names', source: 'explicit' })
   })
 
+  it('prefers the environment-supplied title over an explicit label, making the flag safe everywhere', () => {
+    // An agent must never need to know which environments name their own
+    // sessions: where one does, the explicit label is simply not used.
+    const { env, now } = fixture()
+    expect(
+      resolveSessionLabel({
+        env,
+        now,
+        sessionId: 'managed-session',
+        harness: 'opencode',
+        harnessLabel: 'NotifAI question lifecycle',
+        explicitLabel: 'Agent-chosen name',
+      }),
+    ).toEqual({ ok: true, label: 'NotifAI question lifecycle', source: 'harness' })
+  })
+
+  it('upgrades a frozen fallback to the environment title even when an explicit label rides along', () => {
+    const { env, now } = fixture()
+    const frozen = resolveSessionLabel({ env, now, sessionId: 'late-title' })
+    expect(frozen).toMatchObject({ ok: true, source: 'fallback' })
+    expect(
+      resolveSessionLabel({
+        env,
+        now: now + 1,
+        sessionId: 'late-title',
+        harness: 'opencode',
+        harnessLabel: 'Worktree semantic title',
+        explicitLabel: 'Agent-chosen name',
+      }),
+    ).toEqual({ ok: true, label: 'Worktree semantic title', source: 'harness' })
+  })
+
   it('uses a trusted harness title when no explicit task label exists', () => {
     const { env, now } = fixture()
     expect(
@@ -59,7 +91,7 @@ describe('semantic session labels', () => {
     ).toEqual({ ok: true, label: 'NotifAI question lifecycle', source: 'harness' })
   })
 
-  it('does not replace a frozen fallback when a managed semantic title appears later', () => {
+  it('replaces a frozen generated fallback when a managed semantic title appears later', () => {
     const { env, now } = fixture()
     const frozen = resolveSessionLabel({
       env,
@@ -77,6 +109,82 @@ describe('semantic session labels', () => {
         harness: 'claude-code',
         harnessLabel: 'Worker - semantic session implementation',
       }),
+    ).toEqual({
+      ok: true,
+      label: 'Worker - semantic session implementation',
+      source: 'harness',
+    })
+  })
+
+  it('replaces a frozen generated fallback with a later explicit task name, once', () => {
+    const { env, now } = fixture()
+    const frozen = resolveSessionLabel({ env, now, sessionId: 'late-named', harness: 'codex' })
+    expect(frozen.ok && frozen.source).toBe('fallback')
+
+    expect(
+      resolveSessionLabel({
+        env,
+        now: now + 1_000,
+        sessionId: 'late-named',
+        harness: 'codex',
+        explicitLabel: 'Fix checkout retries',
+      }),
+    ).toEqual({ ok: true, label: 'Fix checkout retries', source: 'explicit' })
+    expect(
+      resolveSessionLabel({
+        env,
+        now: now + 2_000,
+        sessionId: 'late-named',
+        harness: 'codex',
+        explicitLabel: 'A different later name',
+      }),
+    ).toEqual({ ok: true, label: 'Fix checkout retries', source: 'explicit' })
+  })
+
+  it('disambiguates an upgraded name against every other stored session', () => {
+    const { env, now } = fixture()
+    expect(
+      resolveSessionLabel({
+        env,
+        now,
+        sessionId: 'other-session',
+        harness: 'codex',
+        explicitLabel: 'Release preparation',
+      }),
+    ).toEqual({ ok: true, label: 'Release preparation', source: 'explicit' })
+    const frozen = resolveSessionLabel({ env, now, sessionId: 'upgraded', harness: 'codex' })
+    expect(frozen.ok && frozen.source).toBe('fallback')
+
+    expect(
+      resolveSessionLabel({
+        env,
+        now: now + 1_000,
+        sessionId: 'upgraded',
+        harness: 'codex',
+        explicitLabel: 'Release preparation',
+      }),
+    ).toEqual({ ok: true, label: 'Release preparation · Codex', source: 'explicit' })
+  })
+
+  it('rejects an invalid explicit name instead of silently keeping the fallback', () => {
+    const { env, now } = fixture()
+    const frozen = resolveSessionLabel({ env, now, sessionId: 'still-fallback', harness: 'codex' })
+    expect(frozen.ok && frozen.source).toBe('fallback')
+
+    expect(
+      resolveSessionLabel({
+        env,
+        now: now + 1_000,
+        sessionId: 'still-fallback',
+        harness: 'codex',
+        explicitLabel: 'x'.repeat(65),
+      }),
+    ).toEqual({
+      ok: false,
+      error: '--session-label (or NOTIFAI_SESSION_LABEL) must be at most 64 characters.',
+    })
+    expect(
+      resolveSessionLabel({ env, now: now + 2_000, sessionId: 'still-fallback', harness: 'codex' }),
     ).toEqual(frozen)
   })
 
@@ -142,7 +250,7 @@ describe('semantic session labels', () => {
     expect(stored).not.toContain('opaque-thread-1234567890')
   })
 
-  it('migrates a frozen date fallback without reopening semantic precedence', () => {
+  it('migrates a frozen date fallback when no semantic candidate exists', () => {
     const { env, now } = fixture()
     const file = path.join(stateDir(env), 'session-labels.json')
     expect(
@@ -164,10 +272,19 @@ describe('semantic session labels', () => {
         now: now + 1_000,
         sessionId: 'opaque-thread-1234567890',
         harness: 'codex',
-        explicitLabel: 'Late semantic override',
       }),
     ).toEqual({ ok: true, label: 'Ivory Koala', source: 'fallback' })
     expect(readFileSync(file, 'utf8')).not.toContain('Codex session ·')
+
+    expect(
+      resolveSessionLabel({
+        env,
+        now: now + 2_000,
+        sessionId: 'opaque-thread-1234567890',
+        harness: 'codex',
+        explicitLabel: 'Late semantic override',
+      }),
+    ).toEqual({ ok: true, label: 'Late semantic override', source: 'explicit' })
   })
 
   it('disambiguates repeated semantic titles without changing session identity', () => {

package/src/session-labels.ts

@@ -289,9 +289,15 @@ function uniqueLabel(
 /**
  * Freeze the first accepted human name for one immutable session.
  *
- * Explicit agent/User input wins, then a title supplied by a trusted harness
- * adapter, then a generated fallback. Later sends reuse the frozen value
- * even when their branch, worktree, title candidate, or notification changes.
+ * A title supplied by a trusted harness adapter wins, then explicit
+ * agent/User input, then a generated fallback. The environment-first order is
+ * what makes `--session-label` safe to pass unconditionally: an agent never
+ * needs to know which environments name their own sessions, because where one
+ * does, the explicit label is simply not used. A frozen generated fallback is
+ * the one exception to permanence: it names nothing, so the first semantic
+ * candidate to arrive later — a trusted harness title first, then explicit —
+ * replaces it once. Semantic names then stay frozen even when their branch,
+ * worktree, title candidate, or notification changes.
  */
 export function resolveSessionLabel(input: SessionLabelInput): SessionLabelResolution {
   const now = input.now ?? Date.now()
@@ -303,14 +309,39 @@ export function resolveSessionLabel(input: SessionLabelInput): SessionLabelResol
       const store = readStore(file)
       const existing = store.sessions[key]
       if (existing !== undefined) {
-        if (!isLegacyDateFallback(existing)) {
-          return { ok: true, label: existing.label, source: existing.source }
-        }
         const used = new Set(
           Object.entries(store.sessions)
             .filter(([storedKey]) => storedKey !== key)
             .map(([, record]) => collisionKey(record.label)),
         )
+        if (existing.source === 'fallback') {
+          const explicit = explicitCandidate(input.explicitLabel, input)
+          if (explicit !== null && 'error' in explicit) {
+            return { ok: false, error: explicit.error }
+          }
+          const native = harnessLabelIsPending(input.harnessLabel, input)
+            ? null
+            : harnessCandidate(input.harnessLabel, input)
+          const upgrade = native ?? explicit
+          if (upgrade !== null) {
+            const label = uniqueLabel(upgrade.label, upgrade.source, input.harness, now, used)
+            store.sessions[key] = {
+              label,
+              source: upgrade.source,
+              first_seen_at: existing.first_seen_at,
+              ...(input.harness === undefined
+                ? existing.harness === undefined
+                  ? {}
+                  : { harness: existing.harness }
+                : { harness: input.harness }),
+            }
+            writeStore(file, store)
+            return { ok: true, label, source: upgrade.source }
+          }
+        }
+        if (!isLegacyDateFallback(existing)) {
+          return { ok: true, label: existing.label, source: existing.source }
+        }
         const label = uniqueLabel(
           generatedSessionLabel(input.sessionId),
           'fallback',
@@ -337,7 +368,7 @@ export function resolveSessionLabel(input: SessionLabelInput): SessionLabelResol
         }
       }
       const candidate: SessionLabelCandidate =
-        explicit ?? native ?? fallbackCandidate(input.sessionId)
+        native ?? explicit ?? fallbackCandidate(input.sessionId)
       const used = new Set(
         Object.values(store.sessions).map((record) => collisionKey(record.label)),
       )