@raidiant/notifai 4.0.0 → 5.0.0

package/src/send.ts

@@ -12,6 +12,9 @@ import {
   type MediaItemT,
   type NotificationDraftT,
   NOTIFICATION_KINDS,
+  DEFAULT_NOTIFICATION_KIND,
+  defaultSoundForKind,
+  type NotificationKind,
   PLATFORMS,
   type Platform,
   type QuestionT,
@@ -173,10 +176,24 @@ export function buildDraft(
   const targets: NotificationDraftT['targets'] =
     deviceIds && deviceIds.length > 0 ? { mode: 'selected', device_ids: deviceIds } : { mode: 'all' }
 
-  // Kind is semantic status metadata for Companion presentation. It never
-  // chooses native-banner attention; only an explicit flag or saved preference
-  // may add sound or interruption fields to the platform payload.
-  const sound = flags.sound ?? config.sound.value
+  if (
+    flags.kind !== undefined &&
+    !NOTIFICATION_KINDS.includes(flags.kind as (typeof NOTIFICATION_KINDS)[number])
+  ) {
+    return {
+      ok: false,
+      error: `Unknown kind "${flags.kind}" — supported: ${NOTIFICATION_KINDS.map((kind) => `"${kind}"`).join(', ')}.`,
+    }
+  }
+
+  // Kind states what happened; the sound table turns that truth into the
+  // attention it deserves, so an honest sender gets the right sound without
+  // reasoning about audio. An explicit --sound and the user's saved preference
+  // both outrank it, and `none` still means silent.
+  const kindForSound: NotificationKind = flags.reply
+    ? 'question'
+    : ((flags.kind as NotificationKind | undefined) ?? DEFAULT_NOTIFICATION_KIND)
+  const sound = flags.sound ?? config.sound.value ?? defaultSoundForKind(kindForSound)
   if (sound !== null && sound !== undefined && !CLI_SOUNDS.includes(sound as CliSound)) {
     return {
       ok: false,
@@ -211,16 +228,6 @@ export function buildDraft(
     options.custom_data = data
   }
 
-  if (
-    flags.kind !== undefined &&
-    !NOTIFICATION_KINDS.includes(flags.kind as (typeof NOTIFICATION_KINDS)[number])
-  ) {
-    return {
-      ok: false,
-      error: `Unknown kind "${flags.kind}" — supported: ${NOTIFICATION_KINDS.map((kind) => `"${kind}"`).join(', ')}.`,
-    }
-  }
-
   const ttl = flags.ttl ?? config.ttl_seconds.value
   const collapse = flags.collapseKey ?? config.collapse_key.value
   if (
@@ -242,7 +249,7 @@ export function buildDraft(
   if (choices === 'invalid') {
     return {
       ok: false,
-      error: CHOICE_USAGE,
+      error: REPLY_CHOICE_USAGE,
     }
   }
   if (flags.replyMulti && choices === null && flags.questions === undefined) {
@@ -284,7 +291,7 @@ export function buildDraft(
     ...(flags.reply
       ? {
           reply: {
-            expires_in_seconds: flags.replyWindow ?? 3600,
+            expires_in_seconds: flags.replyWindow ?? config.reply_window_seconds.value,
             questions: flags.questions ?? [
               {
                 id: 'q1',
@@ -362,10 +369,19 @@ 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/skill.test.ts

@@ -1,175 +1,228 @@
 import { readFileSync } from 'node:fs'
 import { describe, expect, it } from 'vitest'
+import { NOTIFICATION_KINDS } from '@raidiant/notifai-protocol'
+import { GATE_REASONS } from './hooks.js'
 
-const skill = readFileSync(new URL('../../../skills/notifai/SKILL.md', import.meta.url), 'utf8')
+/**
+ * These tests assert what the skill has to teach, not the sentences it teaches
+ * it in — as far as that is achievable. Pinning wording makes every
+ * improvement to the guidance look like a regression, which is how guidance
+ * goes stale: the cheapest way to keep a suite green becomes leaving the prose
+ * alone.
+ *
+ * What is genuinely structural: section order, the vocabularies the CLI can
+ * actually emit (`NOTIFICATION_KINDS`, `GATE_REASONS`), the token budget, that
+ * every example would pass the CLI's own validation, and that every command an
+ * agent needs is reachable.
+ *
+ * Some assertions do match on phrases, and honestly so: a rule like "never say
+ * where the answer must arrive" has no structural signature, and the cost of
+ * it silently disappearing is higher than the cost of rewording a regex. Those
+ * are matched case-insensitively and loosely on purpose.
+ */
+
+const skillPath = new URL('../../../skills/notifai/SKILL.md', import.meta.url)
+const skill = readFileSync(skillPath, 'utf8')
 const harnessReference = readFileSync(
   new URL('../../../skills/notifai/references/harness-setup.md', import.meta.url),
   'utf8',
 )
 
+/** Fenced blocks, so examples can be checked as commands rather than as text. */
+const examples = [...skill.matchAll(/```(?:bash|json)?\n([\s\S]*?)```/g)].map((match) => match[1]!)
+const shellExamples = examples.flatMap((block) =>
+  block
+    .replace(/\\\n\s*/g, ' ')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('notifai ')),
+)
+
+const section = (heading: string): string => {
+  const start = skill.indexOf(heading)
+  if (start < 0) return ''
+  const next = skill.indexOf('\n## ', start + heading.length)
+  return skill.slice(start, next < 0 ? undefined : next)
+}
+
 describe('Notifai agent skill', () => {
-  it('leads with the notification decision before message composition', () => {
-    expect(skill.indexOf('## When to notify')).toBeGreaterThan(0)
-    expect(skill.indexOf('## When to notify')).toBeLessThan(skill.indexOf('## Compose and send'))
-  })
-
-  it('separates semantic kind from native-banner attention', () => {
-    expect(skill).toContain('--kind done')
-    expect(skill).toMatch(/Kind never chooses a native-banner sound\s+or\s+interruption level/)
-    expect(skill).toContain('lets the destination use its normal behavior')
-    expect(skill).not.toContain('Kind profiles')
-    expect(skill).not.toMatch(/\| `failed` \| `alert`/)
-    expect(skill).not.toMatch(/\| `blocked` \| `attention`/)
-  })
-
-  it('makes the agent the setup wizard', () => {
-    expect(skill.indexOf('## Set Notifai up')).toBeGreaterThan(skill.indexOf('## When to notify'))
-    expect(skill.indexOf('## Set Notifai up')).toBeLessThan(skill.indexOf('## Compose and send'))
-    expect(skill).toContain('Never tell the user to run')
-    expect(skill).toContain('notifai init')
-    expect(skill).toContain('notifai hooks install')
-    expect(skill).toContain('notifai doctor')
-    expect(skill).toContain('notifai login')
-    expect(skill).toContain('Ask the user only for decisions a process cannot make')
-    expect(skill).not.toContain('relay the exact action')
-    expect(harnessReference).toContain('install hooks yourself')
-    expect(harnessReference).toContain('run `notifai login` yourself')
-    expect(harnessReference).not.toContain('the user must run `notifai login`')
-    expect(harnessReference).not.toContain('do not install them without being asked')
-  })
-
-  it('teaches one Markdown body, ordered media, and substance-only titles', () => {
-    for (const required of [
-      'one canonical Markdown body',
-      '--body-file <path|->',
-      'media:1',
-      'maximum 8',
-      'Never repeat the type or Project in the title',
-      'All 42 tests passed',
-    ]) {
-      expect(skill).toContain(required)
-    }
-    expect(skill).not.toContain('--detail')
-    expect(skill).not.toContain('Done ·')
-    expect(skill).not.toContain('Failed ·')
-    expect(skill).not.toContain('Question ·')
-  })
-
-  it('treats --sound and --level as overrides, not completeness', () => {
-    expect(skill).toMatch(/Do not pass `--sound` or `--level` unless/)
-    const examples = [...skill.matchAll(/```(?:bash)?\n([\s\S]*?)```/g)].map((match) => match[1])
-    const sendExamples = examples.filter((example) => example.includes('notifai send'))
-    expect(sendExamples.length).toBeGreaterThan(0)
-    for (const example of sendExamples) {
-      expect(example).not.toMatch(/(^|\s)--sound\b/)
-      expect(example).not.toMatch(/(^|\s)--level\b/)
-    }
+  it('fits inside the budget a skill is actually read within', () => {
+    // Long skills are truncated in exactly the long sessions that need them.
+    // The old skill sat at ~4,800 tokens; this ceiling keeps a working margin.
+    const approximateTokens = skill.length / 4
+    expect(approximateTokens).toBeLessThan(4_400)
   })
 
-  it('documents reply lifecycle, routing, inferred source context, and doctor exits', () => {
-    for (const required of [
-      '--reply-choice',
-      'notifai close <request_id>',
-      'notifai devices',
-      '--device',
-      '--all',
-      'Project identity from the invocation directory',
-      '--session-id',
-      'NOTIFAI_SESSION_ID',
-      'Do not mint an id',
-      'exit status is nonzero',
-    ]) {
-      expect(skill).toContain(required)
+  it('decides whether to notify before it composes anything', () => {
+    const decide = skill.search(/^## .*notify/im)
+    const compose = skill.search(/^## Send/im)
+    expect(decide).toBeGreaterThan(0)
+    expect(decide).toBeLessThan(compose)
+  })
+
+  it('names every notification kind the CLI accepts', () => {
+    for (const kind of NOTIFICATION_KINDS) {
+      expect(skill).toContain(`\`${kind}\``)
     }
-    expect(skill).not.toContain("require('node:crypto').randomUUID()")
-    expect(skill).not.toMatch(/`NOTIFAI_SESSION`/)
-  })
-
-  it('turns a registered question into a same-turn work-resumption commitment', () => {
-    const askGuidance = skill.slice(
-      skill.indexOf('### Register a turn-ending question'),
-      skill.indexOf('## Verify delivery and readiness'),
-    )
-
-    for (const required of [
-      'same turn',
-      'each offered answer',
-      'unexpected typed answer',
-      'work you resume',
-      'never as approval',
-      'permission prompt',
-      'interactive picker',
-      'question identity',
-      'question text',
-      "user's answer",
-    ]) {
-      expect(askGuidance).toContain(required)
+  })
+
+  it('teaches kind as required, truthful, and attention-bearing', () => {
+    const send = section('## Send')
+    expect(send).toMatch(/`--kind` is required/i)
+    // The rule that replaced "kind never chooses attention": since kind now
+    // selects the sound, the only defensible instruction is to declare the
+    // true one.
+    expect(send).toMatch(/declare the kind\s+that is true/i)
+    expect(skill).not.toMatch(/kind never chooses/i)
+  })
+
+  it('keeps every send example valid against the CLI it documents', () => {
+    const sends = shellExamples.filter((line) => line.startsWith('notifai send'))
+    expect(sends.length).toBeGreaterThan(0)
+    for (const example of sends) {
+      // Exactly the boundary rule `sendCommand` enforces.
+      expect(example, example).toMatch(/--kind |--reply\b/)
+      // Attention overrides belong to the user, so no example models one.
+      expect(example, example).not.toMatch(/(^|\s)--(sound|level)\b/)
     }
-    expect(askGuidance).toMatch(/without asking the user to\s+confirm again/)
-  })
-
-  it('requires concrete Agent Acknowledgements before resumed work or turn end', () => {
-    const askGuidance = skill.slice(
-      skill.indexOf('### Register a turn-ending question'),
-      skill.indexOf('## Verify delivery and readiness'),
-    )
-    const requirement = askGuidance.indexOf('agent_acknowledgement_required')
-    const command = askGuidance.indexOf('notifai acknowledge <request_id> --text')
-    const resume = askGuidance.indexOf('After sending every required Agent Acknowledgement')
-
-    expect(requirement).toBeGreaterThanOrEqual(0)
-    expect(command).toBeGreaterThan(requirement)
-    expect(resume).toBeGreaterThan(command)
-    for (const required of [
-      'immediately',
-      'before doing any',
-      'of the resumed work',
-      'before ending the turn',
-      'must be non-empty',
-      'concrete work you will do',
-      'because of their reply',
-      'bare “acknowledged”',
-      'one for every request id',
-      'disabled',
-      'requires no',
-      'command',
-      'route-neutral and truthful',
-    ]) {
-      expect(askGuidance).toContain(required)
+  })
+
+  it('teaches the summary line, the one canonical body, and ordered evidence', () => {
+    const send = section('## Send')
+    expect(send).toContain('--subtitle')
+    expect(send).toContain('--body-file')
+    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)
+  })
+
+  it('separates how long the command waits from how long an answer is accepted', () => {
+    const ask = section('## Ask a question')
+    expect(ask).toContain('--reply-timeout')
+    expect(ask).toContain('--reply-window')
+    expect(ask).toMatch(/exit code 3/i)
+  })
+
+  it('makes registration the middle of the asking turn, not the end', () => {
+    const ask = section('## Ask a question')
+    expect(ask).toMatch(/registering is not the end of the turn/i)
+    // The pre-commitment, and the route-neutrality that makes it survive.
+    expect(ask).toMatch(/what each answer will make you do/i)
+    expect(ask).toMatch(/never say where the answer must arrive/i)
+    expect(ask).toMatch(/tell me here/i)
+  })
+
+  it('requires an acknowledgement before any resumed work', () => {
+    const answers = section('## When the answer arrives')
+    const acknowledge = answers.indexOf('notifai acknowledge')
+    const resume = answers.search(/then resume/i)
+    expect(acknowledge).toBeGreaterThanOrEqual(0)
+    expect(resume).toBeGreaterThan(acknowledge)
+    expect(answers).toMatch(/acknowledge before you resume/i)
+    // Unconditional: no "if required" escape hatch survives the decision that
+    // the user always learns their reply was read.
+    expect(answers).not.toMatch(/if .{0,24}acknowledgement is required/i)
+    expect(answers).toMatch(/concrete/i)
+  })
+
+  it('keeps the relay honest about transport, authorship, and its limits', () => {
+    const answers = section('## When the answer arrives')
+    expect(answers).toMatch(/latest reply/i)
+    expect(answers).toMatch(/another session/i)
+    expect(answers).toMatch(/permission prompt/i)
+    expect(answers).toMatch(/without asking them to confirm again/i)
+  })
+
+  it('recovers an answer it was never handed', () => {
+    expect(skill).toContain('notifai replies --pending')
+  })
+
+  it('makes the agent the operator and the human only the human', () => {
+    const setup = section('## Set Notifai up')
+    expect(setup).toMatch(/never tell the\s+user to run a command you could have run/i)
+    expect(setup).toMatch(/browser/i)
+    expect(setup).toMatch(/companion/i)
+    expect(setup).toContain('notifai doctor --json')
+    expect(setup).toContain('notifai init')
+  })
+
+  it('offers npx only as a pinned fallback behind a real install', () => {
+    const global = skill.indexOf('npm install -g @raidiant/notifai')
+    const npx = skill.indexOf('npx --yes @raidiant/notifai@')
+    expect(global).toBeGreaterThan(0)
+    expect(global).toBeLessThan(npx)
+    expect(skill).toMatch(/never as the first suggestion/i)
+  })
+
+  it('gives the agent an exit-status branch for every documented outcome', () => {
+    for (const code of ['| 0 |', '| 1 |', '| 2 |', '| 3 |', '| 4 |', '| 5 |']) {
+      expect(skill).toContain(code)
     }
+    expect(skill).toMatch(/`notifai <command> --help` is the authoritative list/i)
+  })
+
+  it('points at the record when something did not happen, and calls it private', () => {
+    const check = section('## Check what happened')
+    expect(check).toContain('notifai logs')
+    expect(check).toContain('hook.gate')
+    expect(check).toMatch(/never leaves the machine/i)
   })
 
-  it('teaches agents to report config JSON fields instead of paraphrasing defaults', () => {
-    expect(skill).toContain('notifai config show --json')
-    expect(skill).toContain('{ value, source, summary }')
-    expect(skill).toContain('Do not paraphrase')
-    expect(skill).not.toContain('config.local.toml')
-    expect(skill).toContain('outside the repository')
+  it('advertises exactly the gate reasons the code can emit', () => {
+    // The drift this replaces: the skill advertised `already-asked` and
+    // `no-devices` for months, neither of which was ever emitted, while
+    // `answered`, `acknowledgement-required` and `proceeding` went undocumented.
+    // Reading the vocabulary from the code makes that impossible to repeat.
+    const check = section('## Check what happened')
+    const documented = [...check.matchAll(/`([a-z]+(?:-[a-z]+)*)`/g)].map((m) => m[1]!)
+    const advertised = new Set(documented.filter((word) => GATE_REASONS.includes(word as never)))
+    for (const reason of GATE_REASONS) {
+      // `elapsed` is debug-only bookkeeping, not a routing verdict an agent acts on.
+      if (reason === 'elapsed') continue
+      expect(advertised, `gate reason ${reason} is not documented`).toContain(reason)
+    }
+    for (const word of documented) {
+      if (!word.includes('-')) continue
+      const looksLikeAReason = /^(no|already|continuation|delivery|claimed|notifications|acknowledgement)-/.test(word)
+      if (!looksLikeAReason) continue
+      expect(GATE_REASONS, `the skill advertises "${word}", which nothing emits`).toContain(word)
+    }
   })
 
-  it('mentions npx only as a pinned alternative to a real install', () => {
-    expect(skill).toContain('npm install -g @raidiant/notifai')
-    expect(skill.indexOf('npm install -g @raidiant/notifai')).toBeLessThan(
-      skill.indexOf('npx --yes @raidiant/notifai@'),
-    )
-    expect(skill).toContain('do not present npx as the default')
+  it('distinguishes acceptance, receipt, and unknown when reporting delivery', () => {
+    const check = section('## Check what happened')
+    expect(check).toMatch(/provider acceptance/i)
+    expect(check).toMatch(/companion receipt/i)
+    expect(check).toMatch(/unknown/i)
   })
 
-  it('tells the agent where to look when something did not happen', () => {
-    // The log's whole value is diagnostic, so the skill has to name the case
-    // that produces it — a question that was registered and never travelled.
-    expect(skill).toContain('notifai logs')
-    expect(skill).toContain('--request <id>')
-    expect(skill).toContain('hook.gate')
-    expect(skill).toContain('notifications-off')
-    // And that it is the user's data, on the user's machine.
-    expect(skill).toContain('stays on this machine')
+  it('covers every command an agent needs to reach the user and recover', () => {
+    for (const command of [
+      'notifai send',
+      'notifai ask',
+      'notifai replies',
+      'notifai acknowledge',
+      'notifai close',
+      'notifai doctor',
+      'notifai init',
+      'notifai config show',
+      'notifai logs',
+      'notifai status',
+    ]) {
+      expect(skill, `${command} is unreachable from the skill`).toContain(command)
+    }
   })
 
   it('moves per-harness mechanics into progressive disclosure', () => {
     expect(skill).toContain('[Harness setup and recovery](references/harness-setup.md)')
+    expect(skill).toMatch(/read it when you are\s+installing hooks or diagnosing routing/i)
     for (const harness of ['Claude Code', 'Codex', 'Cursor', 'OpenCode']) {
       expect(harnessReference).toContain(`**${harness}:**`)
     }
+    // The agent runs what a process can run; the human only does the human part.
+    expect(harnessReference).toContain('install hooks yourself')
+    expect(harnessReference).toMatch(/run `notifai login` yourself/i)
+    expect(harnessReference).toMatch(/only the user can approve/i)
   })
 })

package/src/ui/help.ts

@@ -27,7 +27,6 @@ export const GROUP = {
   daily: 'Everyday:',
   agent: 'For agents and scripts:',
   advanced: 'Account and wiring:',
-  help: 'Help:',
 } as const
 
 /** Option groups for `send`, which carries thirty flags. */
@@ -45,7 +44,6 @@ const GROUP_ORDER: readonly string[] = [
   GROUP.daily,
   GROUP.agent,
   GROUP.advanced,
-  GROUP.help,
 ]
 
 function groupRank(heading: string): number {
@@ -117,7 +115,14 @@ export function rootHelpFooter(): string {
     )}`,
     `  ${style.code('notifai init')}         ${style.dim(`${glyph.arrow} set this project up, step by step`)}`,
     '',
-    style.dim(`Every command takes ${style.code('--help')}. Machine-readable output: ${style.code('--json')}.`),
+    style.heading('First call, for an agent'),
+    `  ${style.code('notifai send --kind done --title "All 42 tests passed" --body "Finished in 3m 10s. Next: review the release candidate."')}`,
+    `  ${style.code('notifai ask "Deploy migration 0007 to production?" --choice Deploy --choice Hold')}`,
+    `  ${style.dim(`${glyph.arrow} ${style.code('ask')} needs question routing installed; ${style.code('notifai doctor --json')} says whether it is.`)}`,
+    '',
+    style.dim(
+      `Every command takes ${style.code('--help')}. Where a command has machine-readable output it takes ${style.code('--json')}.`,
+    ),
     style.dim(`Settings are explained by ${style.code('notifai config show')} and ${style.code('notifai config explain <key>')}.`),
   ]
   return lines.join('\n')

package/src/ui/theme.ts

@@ -25,7 +25,7 @@ export const unicode: boolean =
   process.env['ConEmuTask'] === '{cmd::Cmder}'
 
 /** True when 24-bit colour is available, which the banner gradient needs. */
-export function supportsTrueColor(env: NodeJS.ProcessEnv = process.env): boolean {
+function supportsTrueColor(env: NodeJS.ProcessEnv = process.env): boolean {
   if (!pc.isColorSupported) return false
   const colorterm = env['COLORTERM'] ?? ''
   if (/^(truecolor|24bit)$/i.test(colorterm)) return true
@@ -63,7 +63,7 @@ function mix(a: Rgb, b: Rgb, t: number): Rgb {
  * Sample the brand ramp at `t` in [0, 1]. Multi-stop so the gradient keeps the
  * icon's coral midtones instead of washing straight from pink to magenta.
  */
-export function rampAt(t: number, ramp: readonly string[] = BRAND_RAMP): string {
+function rampAt(t: number, ramp: readonly string[] = BRAND_RAMP): string {
   const clamped = Math.min(1, Math.max(0, t))
   const span = ramp.length - 1
   const scaled = clamped * span
@@ -83,20 +83,6 @@ const ANSI_GLOBAL = /\[[0-9;]*m/g
 const ANSI_SPLIT = /(\[[0-9;]*m)/
 const ANSI_ONLY = /^\[[0-9;]*m$/
 
-/**
- * Paint `text` across the brand ramp, one escape per character.
- *
- * Falls back to a single flat brand colour without truecolor, and to the bare
- * string with colour off — a gradient is the most decorative thing this CLI
- * does, so it must also be the first thing to degrade quietly.
- */
-export function gradient(text: string, ramp: readonly string[] = BRAND_RAMP): string {
-  if (!pc.isColorSupported) return text
-  if (!supportsTrueColor()) return pc.magenta(text)
-  const chars = [...text]
-  const last = Math.max(1, chars.length - 1)
-  return chars.map((char, i) => (char === ' ' ? char : `${rampAt(i / last, ramp)}${char}`)).join('') + RESET
-}
 
 /**
  * Paint each line of a block so the gradient runs left-to-right across the