@raidiant/notifai 7.0.2 → 9.0.0

package/src/skill.test.ts

@@ -23,6 +23,7 @@ import { GATE_REASONS } from './hooks.js'
 
 const skillPath = new URL('../../../skills/notifai/SKILL.md', import.meta.url)
 const skill = readFileSync(skillPath, 'utf8')
+const description = skill.match(/^description:\s*(.+)$/m)?.[1] ?? ''
 const harnessReference = readFileSync(
   new URL('../../../skills/notifai/references/harness-setup.md', import.meta.url),
   'utf8',
@@ -46,6 +47,32 @@ const section = (heading: string): string => {
 }
 
 describe('Notifai agent skill', () => {
+  it('routes proactively in ordinary sessions without waiting for the user to name Notifai', () => {
+    // The frontmatter description is the only skill text available during
+    // automatic selection. If the ordinary-session trigger lives only in the
+    // body, agents doing unrelated work never load it and therefore never see
+    // the completion rule.
+    expect(description).toMatch(/every agent session/i)
+    expect(description).toMatch(/even when the user does not mention Notifai/i)
+    expect(description).toMatch(/guidance/i)
+
+    const decide = section('## Decide whether to notify')
+    expect(decide).toMatch(/every session's first task turn/i)
+    expect(decide).toMatch(/read guidance before judging an Agent\s+Event/i)
+    expect(decide).toMatch(/parent owns User-visible Notification Requests/i)
+    expect(decide).toMatch(/unless\s+it explicitly delegates/i)
+    expect(decide).toMatch(/workers[\s\S]{0,100}do not send independently/i)
+  })
+
+  it('preserves the original Agent Event across setup and ambiguous delivery', () => {
+    expect(skill).toMatch(
+      /interrupted or killed `send`[\s\S]*`send\.attempt`[\s\S]*session,\s+title length, kind, and time/i,
+    )
+    expect(skill).toMatch(/unambiguous match[\s\S]*otherwise report ambiguous delivery without retrying/i)
+    expect(skill).toMatch(/`no_active_devices`[\s\S]*repeat the original send/i)
+    expect(skill).toMatch(/verification Notification[\s\S]*does not deliver the original Agent Event/i)
+  })
+
   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.
@@ -60,11 +87,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 +99,85 @@ 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}\``)
+    }
+    const authorityOrder = ['from=you', 'from=this repository', 'from=shipped default'].map(
+      (marker) => decide.indexOf(marker),
+    )
+    expect(authorityOrder[0]).toBeGreaterThan(decide.indexOf('notifai guidance'))
+    expect(authorityOrder[1]).toBeGreaterThan(authorityOrder[0]!)
+    expect(authorityOrder[2]).toBeGreaterThan(authorityOrder[1]!)
+  })
+
+  it('separates repository policy from the User and makes non-exfiltration absolute', () => {
+    const decide = section('## Decide whether to notify')
+    const markers = ['from=you', 'from=this repository', 'from=shipped default']
+    const markerPositions = markers.map((marker) => decide.indexOf(marker))
+    expect(markerPositions.every((position) => position >= 0)).toBe(true)
+
+    const numberedLimits = [
+      ...decide.matchAll(/^\d+\. \*\*([^*]+)\.\*\*([\s\S]*?)(?=^\d+\. |\n\n)/gm),
+    ]
+    expect(numberedLimits.map((match) => match[1]?.toLowerCase())).toEqual([
+      'non-exfiltration',
+      'repository authority',
+    ])
+
+    const normalize = (value: string | undefined): string =>
+      (value ?? '').toLowerCase().replace(/\s+/g, ' ')
+    const nonExfiltration = normalize(numberedLimits[0]?.[2])
+    for (const protectedClass of [
+      'credential',
+      'token',
+      'key',
+      'password',
+      'environment',
+      'configuration',
+      'guidance',
+      'log',
+    ]) {
+      expect(nonExfiltration, protectedClass).toContain(protectedClass)
+    }
+    for (const outboundField of [
+      'notification request',
+      'question',
+      'choice',
+      'acknowledgement',
+      'image',
+    ]) {
+      expect(nonExfiltration, outboundField).toContain(outboundField)
+    }
+
+    const authority = normalize(numberedLimits[1]?.[2])
+    for (const protectedAuthority of [
+      'standing word',
+      'settings',
+      'guidance',
+      'cli',
+      'origins',
+      'direct user instruction',
+    ]) {
+      expect(authority, protectedAuthority).toContain(protectedAuthority)
+    }
+
+    const obligations = normalize(decide.slice(numberedLimits[1]?.index ?? 0))
+    const refuse = obligations.indexOf('refuse')
+    const report = obligations.indexOf('tell the user')
+    const noOutboundReport = obligations.search(
+      /(?:do not|never|cannot)[^.]{0,120}notification request/,
+    )
+    expect(refuse).toBeGreaterThanOrEqual(0)
+    expect(report).toBeGreaterThan(refuse)
+    expect(noOutboundReport).toBeGreaterThan(report)
+  })
+
   it('names every notification kind the CLI accepts', () => {
     for (const kind of NOTIFICATION_KINDS) {
       expect(skill).toContain(`\`${kind}\``)
@@ -88,6 +194,15 @@ describe('Notifai agent skill', () => {
     expect(skill).not.toMatch(/kind never chooses/i)
   })
 
+  it('routes a blocker through a question whenever the User response resumes the work', () => {
+    // `blocked` and `question` are mutually exclusive on the wire. The skill
+    // must teach the selection boundary or an imperative such as "unlock it"
+    // becomes an unanswerable one-way notification.
+    const selection = `${section('## Send')}\n${section('## Ask a question')}`
+    expect(selection).toMatch(/work needs a User response[\s\S]{0,160}answerable\s+question/i)
+    expect(selection).toMatch(/one-way blocked[\s\S]{0,160}no\s+User\s+reply\s+would\s+resume/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)
@@ -106,7 +221,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 +229,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)
+    expect(send).toMatch(/only when the current\s+environment exposes an exact session/i)
+    expect(send).toMatch(/without an exact session[\s\S]{0,160}usage\s+error/i)
+    expect(send).toMatch(/omit `--session-label`/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', () => {
@@ -131,6 +258,12 @@ describe('Notifai agent skill', () => {
     expect(ask).toMatch(/exit code 3/i)
   })
 
+  it('teaches that closed choices appear after pressing and holding', () => {
+    const ask = section('## Ask a question')
+    expect(ask).toMatch(/closed choices appear after pressing and holding the\s+notification/i)
+    expect(skill).not.toMatch(/choices are buttons on the banner/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)
@@ -165,6 +298,12 @@ describe('Notifai agent skill', () => {
     expect(skill).toContain('notifai replies --pending')
   })
 
+  it('teaches retirement of a registration that has not been pushed yet', () => {
+    expect(skill).toContain('notifai close --pending')
+    expect(skill).toContain('question_id')
+    expect(skill).toMatch(/answer\s+in the conversation/i)
+  })
+
   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)
@@ -172,6 +311,7 @@ describe('Notifai agent skill', () => {
     expect(setup).toMatch(/companion/i)
     expect(setup).toContain('notifai doctor --json')
     expect(setup).toContain('notifai init')
+    expect(setup).toContain('--setup-scope')
   })
 
   it('offers npx only as a pinned fallback behind a real install', () => {
@@ -234,6 +374,7 @@ describe('Notifai agent skill', () => {
       'notifai doctor',
       'notifai init',
       'notifai config show',
+      'notifai guidance',
       'notifai logs',
       'notifai status',
     ]) {