@raidiant/notifai 3.0.1 → 4.0.0

package/src/config-schema.ts

@@ -107,14 +107,14 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     choiceHints: {
       default: 'the standard notification tone',
       done: 'the completion chime',
-      attention: 'used for questions that want an answer',
+      attention: 'a distinct attention tone',
       alert: 'the most insistent tone',
       none: 'silent — arrives without a sound',
     },
-    summary: 'Override the sound every notification uses',
+    summary: 'Set the sound notifications from here use',
     detail:
-      'Normally the sound comes from what the notification is: progress updates are silent, completions get the done chime, questions get the attention tone. Setting this pins one sound for everything sent from here, overriding those profiles.\n\nA common use is `none`, to make a noisy project completely silent.',
-    unsetMeans: 'each notification uses the sound for its kind',
+      'Setting this pins one sound for every notification sent from here. Kind remains semantic status metadata and never changes native-banner attention.\n\nLeave this unset to omit the sound field and let the destination use its normal behavior. A common explicit preference is `none`, to make a noisy project completely silent.',
+    unsetMeans: 'not specified; the destination uses its normal behavior',
   },
   interruption_level: {
     label: 'Interruption level',
@@ -126,10 +126,10 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
       active: 'wakes the screen and plays the sound',
       time_sensitive: 'may break through Focus modes',
     },
-    summary: 'Override how insistently notifications arrive',
+    summary: 'Set how insistently notifications from here arrive',
     detail:
-      'How hard a notification tries to reach you, in the operating system\'s terms. Like the sound, this is normally decided by what the notification is; setting it pins one level for everything.\n\n`time_sensitive` can pierce a Focus mode, so it is worth reserving for the cases that genuinely earn it.',
-    unsetMeans: 'each notification uses the level for its kind',
+      'How hard a notification tries to reach you, in the operating system\'s terms. Setting this pins one level for everything sent from here; kind never changes it.\n\nLeave this unset to omit the field and let the destination use its normal behavior. `time_sensitive` can pierce a Focus mode, so reserve it for cases that genuinely earn it.',
+    unsetMeans: 'not specified; the destination uses its normal behavior',
   },
   devices: {
     label: 'Default devices',
@@ -178,8 +178,8 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     kind: 'string',
     summary: 'The name this project reports itself as',
     detail:
-      'Stamped on every notification sent from this directory, and how the companion apps group and filter what arrives. Normally set once in `.notifai/config.toml` and committed, so everyone working on the repository reports the same name.',
-    unsetMeans: 'notifications arrive without a project',
+      'Stamped on every notification sent from this directory, and how the companion apps group and filter what arrives. When unset, the CLI infers a stable identifier from Git (shared across linked worktrees) or the current directory. Set it in `.notifai/config.toml` only when that inferred name is not the identity you want.',
+    unsetMeans: 'inferred from Git or the current directory',
     example: 'my-app',
   },
   notify_criteria: {

package/src/config.test.ts

@@ -98,6 +98,25 @@ describe('harness config layers', () => {
     })
   })
 
+  it('uses NOTIFAI_SESSION_ID for the session layer and ignores the deleted env name', () => {
+    const { env, cwd } = setup({
+      sessionToml: 'ask_grace_seconds = 45\n',
+      sessionId: 'exact-session',
+    })
+    expect(
+      loadConfig({
+        cwd,
+        env: { ...env, NOTIFAI_SESSION_ID: 'exact-session' },
+      }).ask_grace_seconds.value,
+    ).toBe(45)
+    expect(
+      loadConfig({
+        cwd,
+        env: { ...env, NOTIFAI_SESSION: 'exact-session' },
+      }).ask_grace_seconds.value,
+    ).toBe(0)
+  })
+
   it('keeps hostile or colliding session ids inside their own file', () => {
     const { env, cwd } = setup({
       sessionToml: 'ask_grace_seconds = 99\n',
@@ -172,28 +191,23 @@ describe('draft building', () => {
       presentation: { title: 'T', body: 'B' },
       targets: { mode: 'all' },
       delivery: { ttl_seconds: 86400, collapse_key: null },
-      platform: {
-        ios: { sound: null, interruption_level: 'passive' },
-        macos: { sound: null, interruption_level: 'passive' },
-      },
     })
   })
 
   it.each([
-    { flags: {}, sound: null, level: 'passive' },
-    { flags: { kind: 'done' }, sound: 'done', level: 'passive' },
-    { flags: { reply: true }, sound: 'attention', level: 'active' },
-  ])('derives the $sound / $level kind profile from $flags', ({ flags, sound, level }) => {
+    {},
+    { kind: 'done' },
+    { kind: 'failed' },
+    { kind: 'blocked' },
+    { reply: true },
+  ])('never derives sound or interruption level from kind: %j', (flags) => {
     const config = loadConfig({ cwd: base.cwd, env: base.env })
     const build = buildDraft(config, { title: 'T', body: 'B', ...flags })
     if (!build.ok) throw new Error(build.error)
-    expect(build.draft.platform).toEqual({
-      ios: { sound, interruption_level: level },
-      macos: { sound, interruption_level: level },
-    })
+    expect(build.draft.platform).toBeUndefined()
   })
 
-  it('orders explicit flags over user config over the kind profile', () => {
+  it('orders explicit flags over saved user config', () => {
     const { env, cwd } = setup({
       projectToml: 'sound = "alert"\ninterruption_level = "active"\n',
     })
@@ -227,15 +241,129 @@ describe('draft building', () => {
     expect(build.draft.reply?.expires_in_seconds).toBe(3_600)
   })
 
-  it('stamps the project from flag or project config', () => {
+  it('orders explicit and configured Project identity over inference', () => {
     const { env, cwd } = setup({ projectToml: 'project = "my-app"\n' })
     const config = loadConfig({ cwd, env })
-    const fromConfig = buildDraft(config, { title: 'T', body: 'B' })
+    const fromConfig = buildDraft(
+      config,
+      { title: 'T', body: 'B' },
+      { inferredProject: 'inferred-app' },
+    )
     if (!fromConfig.ok) throw new Error(fromConfig.error)
     expect(fromConfig.draft.project).toBe('my-app')
-    const fromFlag = buildDraft(config, { title: 'T', body: 'B', project: 'other-app' })
+    const fromFlag = buildDraft(
+      config,
+      { title: 'T', body: 'B', project: 'other-app' },
+      { inferredProject: 'inferred-app' },
+    )
     if (!fromFlag.ok) throw new Error(fromFlag.error)
     expect(fromFlag.draft.project).toBe('other-app')
+
+    const inferredCase = setup({})
+    const unset = loadConfig({ cwd: inferredCase.cwd, env: inferredCase.env })
+    const inferred = buildDraft(
+      unset,
+      { title: 'T', body: 'B' },
+      { inferredProject: 'inferred-app' },
+    )
+    if (!inferred.ok) throw new Error(inferred.error)
+    expect(inferred.draft.project).toBe('inferred-app')
+  })
+
+  it('carries Source Context without copying authoring overrides into legacy fields', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(
+      config,
+      { title: 'T', body: 'B', sessionId: 'opaque', sessionLabel: 'Visible' },
+      {
+        source: {
+          session_id: 'opaque',
+          session_label: 'Visible',
+          harness: 'codex',
+          branch: 'main',
+          worktree: 'topic',
+        },
+      },
+    )
+    if (!build.ok) throw new Error(build.error)
+    expect(build.draft.source).toEqual({
+      session_id: 'opaque',
+      session_label: 'Visible',
+      harness: 'codex',
+      branch: 'main',
+      worktree: 'topic',
+    })
+    expect(build.draft).not.toHaveProperty('session')
+  })
+
+  it('rewrites positional media references and preserves canonical ids', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(config, {
+      title: 'Visual result',
+      body: '![first](media:1) then ![second](media:2) and ![existing](media:med_keep)',
+      image: ['med_first', 'med_second', 'med_attached'],
+      imageAlt: ['First image', 'Second image'],
+    })
+    if (!build.ok) throw new Error(build.error)
+    expect(build.draft.presentation.body).toBe(
+      '![first](media:med_first) then ![second](media:med_second) and ![existing](media:med_keep)',
+    )
+    expect(build.draft.presentation.body).not.toMatch(/media:[1-8](?!\d)/)
+    expect(build.draft.presentation.media).toEqual([
+      { media_id: 'med_first', alt: 'First image' },
+      { media_id: 'med_second', alt: 'Second image' },
+      { media_id: 'med_attached' },
+    ])
+  })
+
+  it('preserves sparse alt text in an internal ordered media manifest', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(config, {
+      title: 'Visual result',
+      body: '![second](media:2)',
+      media: [
+        { media_id: 'med_first' },
+        { media_id: 'med_second', alt: 'Second image' },
+      ],
+    })
+    if (!build.ok) throw new Error(build.error)
+    expect(build.draft.presentation.body).toBe('![second](media:med_second)')
+    expect(build.draft.presentation.media).toEqual([
+      { media_id: 'med_first' },
+      { media_id: 'med_second', alt: 'Second image' },
+    ])
+  })
+
+  it('names an out-of-range positional media reference', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(config, {
+      title: 'Visual result',
+      body: '![missing](media:3)',
+      image: ['med_first', 'med_second'],
+    })
+    expect(build).toEqual({
+      ok: false,
+      error: 'Body reference "media:3" has no matching --image occurrence.',
+    })
+  })
+
+  it('validates media cardinality and alt pairing', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    expect(
+      buildDraft(config, {
+        title: 'T',
+        body: 'B',
+        image: Array.from({ length: 9 }, (_, index) => `med_${index}`),
+      }),
+    ).toMatchObject({ ok: false, error: expect.stringContaining('at most 8') })
+    expect(
+      buildDraft(config, {
+        title: 'T',
+        body: 'B',
+        image: ['med_one'],
+        imageAlt: ['one', 'two'],
+      }),
+    ).toMatchObject({ ok: false, error: expect.stringContaining('2 --image-alt') })
   })
 
   it('carries --kind and rejects one outside the vocabulary', () => {

package/src/config.ts

@@ -380,7 +380,7 @@ export function loadConfig(options: {
   const projectRaw = projectPath ? readTomlFile(projectPath) : {}
   const projectLocalPath = findProjectLocalConfigPath(cwd, env)
   const projectLocalRaw = projectLocalPath ? readTomlFile(projectLocalPath) : {}
-  const sessionId = options.sessionId ?? env['NOTIFAI_SESSION']
+  const sessionId = options.sessionId ?? env['NOTIFAI_SESSION_ID']
   const sessionPath = sessionId ? sessionConfigPath(sessionId, env) : null
   const sessionRaw = sessionPath && existsSync(sessionPath) ? readTomlFile(sessionPath) : {}
 

package/src/hooks.test.ts

@@ -14,11 +14,12 @@ import {
 import os from 'node:os'
 import path from 'node:path'
 import { PassThrough } from 'node:stream'
-import type {
-  ListRepliesResponse,
-  ReplyView,
-  SubmissionReceipt,
-  SubmitNotificationRequestT,
+import {
+  sessionLabelFromId,
+  type ListRepliesResponse,
+  type ReplyView,
+  type SubmissionReceipt,
+  type SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
 import { describe, expect, it, vi } from 'vitest'
 import { ApiCallError, type ApiClient } from './client.js'
@@ -54,11 +55,46 @@ import {
   readMatchingProjectSessionPointer,
   readProjectSession,
   readSessionState,
-  registerQuestion,
+  registerQuestion as persistQuestion,
   writeProjectSession,
-  writeSessionState,
+  writeSessionState as persistSessionState,
+  type PendingQuestion,
+  type SessionState,
 } from './hooks.js'
 
+/** New-format test fixtures always carry the canonical body explicitly. */
+function registerQuestion(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  question: PendingQuestion,
+  now?: number,
+): void {
+  persistQuestion(
+    sessionId,
+    env,
+    { ...question, body: question.body ?? question.question },
+    now,
+  )
+}
+
+function writeSessionState(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  state: SessionState,
+): void {
+  persistSessionState(sessionId, env, {
+    ...state,
+    ...(state.pending === undefined
+      ? {}
+      : {
+          pending: state.pending.map((entry) => ({
+            ...entry,
+            body: entry.body ?? entry.question,
+          })),
+        }),
+  })
+}
+
 class CapturedIo implements CommandIo {
   outLines: string[] = []
   errLines: string[] = []
@@ -432,16 +468,38 @@ describe('pushing a registered question', () => {
       device_ids: ['dev_iphone', 'dev_mac'],
     })
     expect(h.recorder.submitted[0]?.draft.presentation).toMatchObject({
-      title: 'Question',
+      title: 'Ship it?',
       body: 'Ship it?',
     })
-    expect(h.recorder.submitted[0]?.draft.platform).toEqual({
-      ios: { sound: 'attention', interruption_level: 'active' },
-      macos: { sound: 'attention', interruption_level: 'active' },
-    })
+    expect(h.recorder.submitted[0]?.draft.platform).toBeUndefined()
+  })
+
+  it('keeps sparse alt text paired with its original media item', async () => {
+    const h = harness([reply({ text: 'Yes' })])
+    writeSessionState('media-order', h.env, { last_prompt_at: AWAY })
+    registerQuestion(
+      'media-order',
+      h.env,
+      {
+        question: 'Which image should ship?',
+        body: 'Compare ![the second image](media:med_second).',
+        media: [
+          { media_id: 'med_first' },
+          { media_id: 'med_second', alt: 'Second image' },
+        ],
+      },
+      NOW,
+    )
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'media-order' }))
+
+    expect(h.recorder.submitted[0]?.draft.presentation.media).toEqual([
+      { media_id: 'med_first' },
+      { media_id: 'med_second', alt: 'Second image' },
+    ])
   })
 
-  it('names the resolved project in the pushed question title', async () => {
+  it('keeps Project identity out of the substantive question title', async () => {
     const h = harness([reply({ text: 'Yes' })])
     const projectDir = path.join(h.deps.cwd, '.notifai')
     mkdirSync(projectDir, { recursive: true })
@@ -450,11 +508,17 @@ describe('pushing a registered question', () => {
       'project = "notifai-cli"\nask_grace_seconds = 0\n',
     )
     writeSessionState('project-title', h.env, { last_prompt_at: AWAY })
-    registerQuestion('project-title', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion(
+      'project-title',
+      h.env,
+      { question: 'Ship it?', project: 'notifai-cli' },
+      NOW,
+    )
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'project-title', cwd: h.deps.cwd }))
 
-    expect(h.recorder.submitted[0]?.draft.presentation.title).toBe('Question · notifai-cli')
+    expect(h.recorder.submitted[0]?.draft.presentation.title).toBe('Ship it?')
+    expect(h.recorder.submitted[0]?.draft.project).toBe('notifai-cli')
   })
 })
 
@@ -1900,7 +1964,6 @@ describe('a question that outlives its session', () => {
         question: 'Old?',
         state: 'expired',
       }],
-      undefined,
       NOW - 25 * 3600 * 1000,
     )
     const drained = await drainOrphanRetirements(
@@ -1962,7 +2025,7 @@ describe('ask registration', () => {
     const h = harness()
     // Inside a hook, a rejection is only a stderr note the agent never reads —
     // so it would look registered and then silently never ask.
-    expect(askCommand(h.deps, 'Ship it?', { choice: ['Only one'], session: 'a1' })).toBe(EXIT.usage)
+    expect(askCommand(h.deps, 'Ship it?', { choice: ['Only one'], sessionId: 'a1' })).toBe(EXIT.usage)
     expect(readSessionState('a1', h.env).pending).toBeUndefined()
   })
 
@@ -1993,7 +2056,7 @@ describe('ask registration', () => {
             { text: 'Deploy where?', choices: ['Staging', 'Production'], multi: true },
             { text: 'Anything to watch?' },
           ],
-          detail: '## Context\nThe long story.',
+          body: '## Context\nThe long story.',
         }) },
       undefined,
     )
@@ -2002,18 +2065,18 @@ describe('ask registration', () => {
     registerQuestion('form1', h.env, {
       question: built.questions[0]!.text,
       questions: built.questions,
-      ...(built.detail === undefined ? {} : { detail: built.detail }),
+      body: built.body,
     })
     const pending = readSessionState('form1', h.env).pending?.[0]
     expect(pending?.questions).toHaveLength(2)
-    expect(pending?.detail).toContain('long story')
+    expect(pending?.body).toContain('long story')
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'form1' }))
     const draft = h.recorder.submitted[0]?.draft
-    // The banner leads with the first question and admits the rest exists;
-    // the full set rides the payload for the answering card.
-    expect(draft?.presentation.body).toBe('Deploy where? (+1 more)')
-    expect(draft?.presentation.detail).toContain('long story')
+    expect(draft?.presentation.title).toBe('Deploy where?')
+    expect(draft?.presentation.body).toBe(
+      '1. Deploy where?\n2. Anything to watch?\n\n## Context\nThe long story.',
+    )
     expect(draft?.reply?.questions).toEqual([
       {
         id: 'deploy-where',
@@ -2108,7 +2171,7 @@ describe('ask registration', () => {
 
   it('does not let an explicit session bypass exact active-harness proof', () => {
     const h = harness()
-    expect(askCommand(h.deps, 'Ship it?', { session: 'guessed' })).toBe(EXIT.usage)
+    expect(askCommand(h.deps, 'Ship it?', { sessionId: 'guessed' })).toBe(EXIT.usage)
     expect(readSessionState('guessed', h.env).pending).toBeUndefined()
   })
 
@@ -2529,21 +2592,46 @@ describe('malformed input', () => {
 })
 
 describe('telling concurrent agents apart', () => {
-  it('stamps the harness session on the question it pushes', async () => {
-    // The hook has always known session_id and never passed it on, so two
-    // agents in separate worktrees produced identical notifications and the
-    // user could answer the wrong one's question.
+  it('stamps structured Source Context on the question it pushes', async () => {
     const h = harness([])
-    registerQuestion('sess-abc', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion(
+      'sess-abc',
+      h.env,
+      {
+        question: 'Ship it?',
+        source: {
+          session_id: 'sess-abc',
+          session_label: sessionLabelFromId('sess-abc'),
+          harness: 'claude-code',
+        },
+      },
+      NOW,
+    )
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sess-abc' }))
 
-    expect(h.recorder.submitted[0]?.draft.session).toBe('sess-abc')
+    expect(h.recorder.submitted[0]?.draft.source).toEqual({
+      session_id: 'sess-abc',
+      session_label: sessionLabelFromId('sess-abc'),
+      harness: 'claude-code',
+    })
   })
 
   it('stamps the retirement too, so it lands on the right agent’s notification', async () => {
     const h = harness([reply({ text: 'Yes' })])
-    registerQuestion('sess-abc', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion(
+      'sess-abc',
+      h.env,
+      {
+        question: 'Ship it?',
+        source: {
+          session_id: 'sess-abc',
+          session_label: sessionLabelFromId('sess-abc'),
+          harness: 'claude-code',
+        },
+      },
+      NOW,
+    )
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sess-abc' }))
     h.recorder.acknowledged ??= new Set()
@@ -2555,17 +2643,35 @@ describe('telling concurrent agents apart', () => {
     )
 
     const retirement = h.recorder.submitted.find((s) => s.draft.event === 'question_retired')
-    expect(retirement?.draft.session).toBe('sess-abc')
+    expect(retirement?.draft.source).toEqual({
+      session_id: 'sess-abc',
+      session_label: sessionLabelFromId('sess-abc'),
+      harness: 'claude-code',
+    })
   })
 
-  it('prefers a name the user chose over the harness UUID', async () => {
+  it('preserves a human session label without displaying the opaque id', async () => {
     const h = harness([])
-    h.env['NOTIFAI_SESSION'] = 'migration-worktree'
-    registerQuestion('sess-abc', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion(
+      'sess-abc',
+      h.env,
+      {
+        question: 'Ship it?',
+        source: {
+          session_id: 'sess-abc',
+          session_label: 'Migration Worktree',
+          harness: 'claude-code',
+        },
+      },
+      NOW,
+    )
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sess-abc' }))
 
-    expect(h.recorder.submitted[0]?.draft.session).toBe('migration-worktree')
+    const draft = h.recorder.submitted[0]?.draft
+    expect(draft?.source?.session_label).toBe('Migration Worktree')
+    expect(draft?.presentation.title).not.toContain('sess-abc')
+    expect(draft?.presentation.body).not.toContain('sess-abc')
   })
 })
 
@@ -2713,7 +2819,6 @@ describe('durable state writes', () => {
             state: 'expired',
           },
         ],
-        'linked-pointer',
         NOW,
       ),
     ).toThrow(/symlink/)