@raidiant/notifai 7.0.2 → 8.0.0

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,
@@ -44,7 +45,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 +65,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.
@@ -200,7 +202,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 +211,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 +243,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 +264,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,6 +290,23 @@ 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 } : {}),
@@ -297,19 +333,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 +399,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-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)),
       )

package/src/skill.test.ts

@@ -60,11 +60,11 @@ describe('Notifai agent skill', () => {
     expect(decide).toBeLessThan(compose)
   })
 
-  it('keeps session instructions out of config and agent paraphrase out of criteria', () => {
+  it('keeps session instructions out of config and agent paraphrase out of guidance', () => {
     // The rule this pins: a conversational instruction is followed, not
-    // persisted, and criteria are stored in the user's words verbatim. An
-    // agent once turned "guide me when you need me" into a persisted
-    // notify_criteria in its own wording, silently via --yes.
+    // persisted, and persisted guidance holds the user's words verbatim. An
+    // agent once turned "guide me when you need me" into a persisted standing
+    // instruction in its own wording, silently via --yes.
     const decide = section('## Decide whether to notify')
     expect(decide).toMatch(/never touches config/i)
     expect(decide).toMatch(/words\s+verbatim/i)
@@ -72,6 +72,18 @@ describe('Notifai agent skill', () => {
     expect(decide).toMatch(/`--yes` skips the\s+CLI's confirmation/i)
   })
 
+  it('sends the agent to the resolved guidance before it writes anything', () => {
+    // The writing guidance itself lives in `notifai guidance` (shipped topics,
+    // user-overridable per layer); the skill's job is to make reading it the
+    // first step and user layers authoritative.
+    const decide = section('## Decide whether to notify')
+    expect(decide).toContain('notifai guidance')
+    for (const topic of ['when-to-notify', 'titles', 'bodies', 'questions', 'acknowledgements']) {
+      expect(decide).toContain(`\`${topic}\``)
+    }
+    expect(decide).toMatch(/outranks the shipped\s+default and your judgement/i)
+  })
+
   it('names every notification kind the CLI accepts', () => {
     for (const kind of NOTIFICATION_KINDS) {
       expect(skill).toContain(`\`${kind}\``)
@@ -106,7 +118,7 @@ describe('Notifai agent skill', () => {
     expect(send).toMatch(/one canonical Markdown body/i)
     expect(send).toContain('media:1')
     // Type and project are structured fields, never title text.
-    expect(send).toMatch(/never\s+put the kind or the project in it/i)
+    expect(send).toMatch(/kind and the project travel as their own\s+fields, never in it/i)
   })
 
   it('names each immutable session once without asking the agent for its id', () => {
@@ -114,14 +126,26 @@ describe('Notifai agent skill', () => {
     expect(send).toContain('--session-label')
     expect(send).toMatch(/first Notification\s+Request/i)
     expect(send).toMatch(/2-6 words/i)
-    expect(send).toMatch(/Managed OpenCode and Orca-managed Claude Code/i)
-    expect(send).toMatch(/omit `--session-label` there/i)
-    expect(send).toMatch(/Outside those managed sources/i)
-    expect(send).toMatch(/Claude Code, Codex,\s+and Cursor/i)
-    expect(send).toMatch(/freezes the first accepted name/i)
-    expect(send).toMatch(/omit the\s+flag on later sends and questions/i)
+    // The rule is unconditional: the environment's name wins, so the flag is
+    // safe everywhere and the agent never branches on where it is running.
+    expect(send).toMatch(/safe in every environment/i)
+    expect(send).toMatch(/name the\s+environment supplies wins/i)
+    expect(send).toMatch(/freezes one semantic name/i)
+    expect(send).toMatch(/omit the flag on later sends and\s+questions/i)
+    // The one exception to permanence: garbage names are recoverable.
+    expect(send).toMatch(/generated fallback name[\s\S]*replaced by a later\s+semantic name/i)
     expect(send).toMatch(/never pass\s+`--session-id`/i)
-    expect(send).toMatch(/identifier, hash, or filesystem path/i)
+    expect(send).toMatch(/identifier, hash, or\s+filesystem path/i)
+  })
+
+  it('never teaches by enumerating environments the CLI can detect itself', () => {
+    // "What if we had 24 different plugins, are we gonna list them all?" —
+    // guidance states one rule; the mechanism owns environment detection.
+    // Harness names may appear only in setup/routing material, where the
+    // harness IS the subject.
+    for (const heading of ['## Decide whether to notify', '## Send', '## Ask a question', '## When the answer arrives']) {
+      expect(section(heading), heading).not.toMatch(/OpenCode|Orca|Cursor|Codex/)
+    }
   })
 
   it('separates how long the command waits from how long an answer is accepted', () => {
@@ -234,6 +258,7 @@ describe('Notifai agent skill', () => {
       'notifai doctor',
       'notifai init',
       'notifai config show',
+      'notifai guidance',
       'notifai logs',
       'notifai status',
     ]) {