@raidiant/notifai 9.0.0 → 9.1.0

package/src/send-attempts.test.ts

@@ -0,0 +1,143 @@
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { NotificationDraftT } from '@raidiant/notifai-protocol'
+import type { MachineCredential } from './credentials.js'
+import {
+  SEND_ATTEMPT_TTL_MS,
+  beginSendAttempt,
+  semanticMediaIds,
+  sendDraftFingerprint,
+  settleSendAttempt,
+} from './send-attempts.js'
+
+const roots: string[] = []
+afterEach(() => {
+  while (roots.length > 0) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function fixture() {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-send-attempt-'))
+  roots.push(root)
+  const env = { XDG_STATE_HOME: path.join(root, 'state') }
+  const credential: MachineCredential = {
+    machineId: 'mac_attempt',
+    machineName: 'Attempt Machine',
+    baseUrl: 'https://app.notifai.test',
+    secret: 'private-machine-secret',
+  }
+  const draft = {
+    schema_version: 1,
+    kind: 'done',
+    project: 'private-project',
+    presentation: { title: 'Sensitive result', body: 'Private body text' },
+    targets: { mode: 'all' },
+  } as NotificationDraftT
+  return { root, env, credential, draft }
+}
+
+describe('opaque interrupted-send recovery', () => {
+  it('matches one exact semantic retry without storing notification content', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    const first = beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(first.ok).toBe(true)
+    if (!first.ok) return
+
+    const files = readdirSync(path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts'))
+    expect(files).toHaveLength(1)
+    const file = path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts', files[0]!)
+    const stored = readFileSync(file, 'utf8')
+    expect(stored).not.toContain('Sensitive result')
+    expect(stored).not.toContain('Private body text')
+    if (process.platform !== 'win32') expect(statSync(file).mode & 0o777).toBe(0o600)
+    if (process.platform !== 'win32') {
+      expect(statSync(path.dirname(file)).mode & 0o777).toBe(0o700)
+    }
+
+    const retry = beginSendAttempt({ env, credential, fingerprint, retry: true, now: 11 })
+    expect(retry).toMatchObject({
+      ok: true,
+      attemptId: first.attemptId,
+      idempotencyKey: first.idempotencyKey,
+      replay: true,
+    })
+    settleSendAttempt(env, first.attemptId)
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 12 })).toMatchObject({
+      ok: false,
+      code: 'retry_not_found',
+    })
+  })
+
+  it('does not follow a symlink presented as an attempt record', () => {
+    const { root, env, credential, draft } = fixture()
+    if (process.platform === 'win32') return
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    const first = beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(first.ok).toBe(true)
+    if (!first.ok) return
+    const directory = path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts')
+    const file = path.join(directory, `${first.attemptId}.json`)
+    const target = path.join(root, 'foreign.json')
+    writeFileSync(target, readFileSync(file, 'utf8'))
+    rmSync(file)
+    symlinkSync(target, file)
+
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 11 })).toMatchObject({
+      ok: false,
+      code: 'retry_not_found',
+    })
+    expect(readFileSync(target, 'utf8')).toContain(first.idempotencyKey)
+  })
+
+  it('refuses ambiguity instead of choosing between identical unresolved events', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 11 })
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 12 })).toMatchObject({
+      ok: false,
+      code: 'retry_ambiguous',
+    })
+  })
+
+  it('invalidates attempts after expiry or credential rotation', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(
+      beginSendAttempt({
+        env,
+        credential,
+        fingerprint,
+        retry: true,
+        now: 10 + SEND_ATTEMPT_TTL_MS + 1,
+      }),
+    ).toMatchObject({ ok: false, code: 'retry_not_found' })
+
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 20 })
+    const rotated = { ...credential, secret: 'rotated-secret' }
+    expect(
+      beginSendAttempt({
+        env,
+        credential: rotated,
+        fingerprint: sendDraftFingerprint(draft, rotated),
+        retry: true,
+        now: 21,
+      }),
+    ).toMatchObject({ ok: false, code: 'retry_not_found' })
+  })
+
+  it('fingerprints local media bytes without retaining paths or bytes', () => {
+    const { root } = fixture()
+    const file = path.join(root, 'private.png')
+    writeFileSync(file, 'first bytes')
+    const first = semanticMediaIds([file], root)
+    writeFileSync(file, 'different bytes')
+    const second = semanticMediaIds([file], root)
+    expect(first).not.toEqual(second)
+    expect(first[0]).not.toContain(file)
+    expect(first[0]).not.toContain('first bytes')
+  })
+})

package/src/send-attempts.ts

@@ -0,0 +1,188 @@
+import { createHash, createHmac, randomBytes } from 'node:crypto'
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+} from 'node:fs'
+import path from 'node:path'
+import type { NotificationDraftT } from '@raidiant/notifai-protocol'
+import { atomicWriteFileSync } from './atomic-file.js'
+import { stateDir } from './config.js'
+import type { MachineCredential } from './credentials.js'
+
+interface SendAttemptRecord {
+  version: 1
+  attempt_id: string
+  fingerprint: string
+  idempotency_key: string
+  credential_tag: string
+  machine_id: string
+  service: string
+  created_at: string
+  expires_at: string
+}
+
+export const SEND_ATTEMPT_TTL_MS = 24 * 60 * 60 * 1000
+
+/** Stable pre-upload media identities used only inside the keyed draft digest. */
+export function semanticMediaIds(images: readonly string[], cwd: string): string[] {
+  return images.map((image) => {
+    if (image.startsWith('med_')) return image
+    const digest = createHash('sha256')
+    if (/^https?:\/\//i.test(image)) digest.update(`url\0${image}`)
+    else digest.update('file\0').update(readFileSync(path.resolve(cwd, image)))
+    return `med_retry_${digest.digest('base64url')}`
+  })
+}
+
+function directory(env: NodeJS.ProcessEnv): string {
+  return path.join(stateDir(env), 'send-attempts')
+}
+
+function credentialTag(credential: MachineCredential): string {
+  return createHmac('sha256', credential.secret)
+    .update('notifai-send-attempt-credential-v1')
+    .digest('base64url')
+}
+
+/** A keyed digest proves equality without persisting notification content. */
+export function sendDraftFingerprint(
+  draft: NotificationDraftT,
+  credential: MachineCredential,
+): string {
+  return createHmac('sha256', credential.secret)
+    .update('notifai-send-draft-v1\0')
+    .update(JSON.stringify(draft))
+    .digest('base64url')
+}
+
+function parseRecord(file: string): SendAttemptRecord | null {
+  let descriptor: number | undefined
+  try {
+    const before = lstatSync(file)
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+    if (before.isSymbolicLink() || !before.isFile() || (uid !== undefined && before.uid !== uid)) {
+      return null
+    }
+    const flags = constants.O_RDONLY | (process.platform === 'win32' ? 0 : constants.O_NOFOLLOW)
+    descriptor = openSync(file, flags)
+    const opened = fstatSync(descriptor)
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) return null
+    const value = JSON.parse(readFileSync(descriptor, 'utf8')) as Partial<SendAttemptRecord>
+    return value.version === 1 &&
+      typeof value.attempt_id === 'string' &&
+      typeof value.fingerprint === 'string' &&
+      typeof value.idempotency_key === 'string' &&
+      typeof value.credential_tag === 'string' &&
+      typeof value.machine_id === 'string' &&
+      typeof value.service === 'string' &&
+      typeof value.created_at === 'string' &&
+      typeof value.expires_at === 'string'
+      ? value as SendAttemptRecord
+      : null
+  } catch {
+    return null
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor)
+  }
+}
+
+function liveRecords(
+  env: NodeJS.ProcessEnv,
+  credential: MachineCredential,
+  now: number,
+): SendAttemptRecord[] {
+  const dir = directory(env)
+  if (!existsSync(dir)) return []
+  const directoryStat = lstatSync(dir)
+  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+  if (
+    directoryStat.isSymbolicLink() ||
+    !directoryStat.isDirectory() ||
+    (uid !== undefined && directoryStat.uid !== uid)
+  ) return []
+  const tag = credentialTag(credential)
+  const records: SendAttemptRecord[] = []
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue
+    const file = path.join(dir, name)
+    const record = parseRecord(file)
+    const expired = record === null || Date.parse(record.expires_at) <= now
+    const rotated = record !== null && (
+      record.machine_id !== credential.machineId ||
+      record.service !== credential.baseUrl ||
+      record.credential_tag !== tag
+    )
+    if (expired || rotated) {
+      rmSync(file, { force: true })
+      continue
+    }
+    records.push(record)
+  }
+  return records
+}
+
+export type BeginAttempt =
+  | { ok: true; attemptId: string; idempotencyKey: string; replay: boolean }
+  | { ok: false; code: 'retry_not_found' | 'retry_ambiguous'; message: string }
+
+export function beginSendAttempt(options: {
+  env: NodeJS.ProcessEnv
+  credential: MachineCredential
+  fingerprint: string
+  retry: boolean
+  idempotencyKey?: string
+  now?: number
+}): BeginAttempt {
+  const now = options.now ?? Date.now()
+  const live = liveRecords(options.env, options.credential, now)
+  if (options.retry) {
+    const matches = live.filter((record) => record.fingerprint === options.fingerprint)
+    if (matches.length === 0) {
+      return {
+        ok: false,
+        code: 'retry_not_found',
+        message: 'No unresolved opaque attempt matches this exact send on the current Approved Machine.',
+      }
+    }
+    if (matches.length > 1) {
+      return {
+        ok: false,
+        code: 'retry_ambiguous',
+        message: 'More than one unresolved opaque attempt matches this exact send; refusing to guess or create another notification.',
+      }
+    }
+    const match = matches[0]!
+    return { ok: true, attemptId: match.attempt_id, idempotencyKey: match.idempotency_key, replay: true }
+  }
+
+  const attemptId = `sat_${randomBytes(12).toString('base64url')}`
+  const idempotencyKey = options.idempotencyKey ?? `cli-${randomBytes(12).toString('base64url')}`
+  const record: SendAttemptRecord = {
+    version: 1,
+    attempt_id: attemptId,
+    fingerprint: options.fingerprint,
+    idempotency_key: idempotencyKey,
+    credential_tag: credentialTag(options.credential),
+    machine_id: options.credential.machineId,
+    service: options.credential.baseUrl,
+    created_at: new Date(now).toISOString(),
+    expires_at: new Date(now + SEND_ATTEMPT_TTL_MS).toISOString(),
+  }
+  atomicWriteFileSync(
+    path.join(directory(options.env), `${attemptId}.json`),
+    `${JSON.stringify(record)}\n`,
+    { mode: 0o600, directoryMode: 0o700, requireCurrentUserOwner: true },
+  )
+  return { ok: true, attemptId, idempotencyKey, replay: false }
+}
+
+export function settleSendAttempt(env: NodeJS.ProcessEnv, attemptId: string): void {
+  rmSync(path.join(directory(env), `${attemptId}.json`), { force: true })
+}

package/src/session-activation.ts

@@ -1,29 +1,46 @@
 import type { HookHarness } from './hooks.js'
+import { Buffer } from 'node:buffer'
+import { GUIDANCE_CONTEXT_MAX_BYTES, boundedEffectiveGuidance } from './guidance-render.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.'
+const ROOT_OWNERSHIP =
+  'Notifai is active for this session. The effective, provenance-marked guidance below governs Notification Requests. ' +
+  'Missing CLI readiness is handled through `notifai init --json`. ' +
+  'The root agent owns User-visible Notification Requests unless it explicitly delegates that ownership; workers report Agent Events to the parent.'
+
+export const WORKER_ACTIVATION_CONTEXT =
+  'Notifai worker context: report Agent Events to the parent; do not send User-visible Notification Requests unless the parent explicitly delegated that ownership. If delegated, run `notifai guidance` before composing one.'
+
+export const MISSING_LIFECYCLE_GUIDANCE_CONTEXT =
+  'Notifai is active, but lifecycle guidance could not be loaded. Run `notifai guidance` once before deciding whether or how to send a Notification Request.'
+
+function rootActivationContext(cwd: string, env: NodeJS.ProcessEnv): string {
+  const guidance = boundedEffectiveGuidance({
+    cwd,
+    env,
+    maxBytes: GUIDANCE_CONTEXT_MAX_BYTES - Buffer.byteLength(`${ROOT_OWNERSHIP}\n\n`, 'utf8'),
+  })
+  return `${ROOT_OWNERSHIP}\n\n${guidance.ok ? guidance.content : guidance.fallback}`
+}
 
 /** One lifecycle meaning, encoded for each harness output contract. */
 export function sessionActivationOutput(
   harness: HookHarness | undefined,
   hookEventName: 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit',
+  cwd: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
 ): string | undefined {
+  const context = hookEventName === 'SubagentStart'
+    ? WORKER_ACTIVATION_CONTEXT
+    : rootActivationContext(cwd, env)
+  if (harness === 'opencode') return context
   if (harness === 'cursor') {
-    return JSON.stringify({ additional_context: SESSION_ACTIVATION_CONTEXT })
+    return JSON.stringify({ additional_context: context })
   }
   if (harness === 'claude-code' || harness === 'codex') {
     return JSON.stringify({
       hookSpecificOutput: {
         hookEventName,
-        additionalContext: SESSION_ACTIVATION_CONTEXT,
+        additionalContext: context,
       },
     })
   }
@@ -35,11 +52,11 @@ export function sessionActivationOutput(
  * 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 {
+export function cursorStopActivationOutput(
+  cwd: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
+): 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,',
-    ),
+    followup_message: rootActivationContext(cwd, env),
   })
 }

package/src/skill.test.ts

@@ -57,8 +57,8 @@ describe('Notifai agent skill', () => {
     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(/lifecycle context normally includes.*effective guidance/is)
+    expect(decide).toMatch(/context is absent.*read it once before judging an Agent\s+Event/is)
     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)
@@ -66,11 +66,11 @@ describe('Notifai agent skill', () => {
 
   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,
+      /interrupted or killed `send`[\s\S]*do not correlate redacted logs by title[\s\S]*re-run the exact semantic send with\s+`--retry`/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)
+    expect(skill).toMatch(/opaque matching attempt[\s\S]*refuse ambiguity/i)
+    expect(skill).toMatch(/`no_active_devices`[\s\S]*repeat the\s+(?:exact\s+)?original send/i)
+    expect(skill).toMatch(/verification Notification[\s\S]*does not deliver\s+the original Agent Event/i)
   })
 
   it('fits inside the budget a skill is actually read within', () => {
@@ -224,17 +224,16 @@ describe('Notifai agent skill', () => {
     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', () => {
+  it('lets callers repeat one immutable semantic session name without supplying its id', () => {
     const send = section('## Send')
     expect(send).toContain('--session-label')
-    expect(send).toMatch(/first Notification\s+Request/i)
     expect(send).toMatch(/2-6 words/i)
-    expect(send).toMatch(/only when the current\s+environment exposes an exact session/i)
+    expect(send).toMatch(/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)
+    expect(send).toMatch(/safe to repeat the same `--session-label` on every send and ask/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)
@@ -309,8 +308,8 @@ describe('Notifai agent skill', () => {
     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')
+    expect(setup).toContain('notifai init --json')
+    expect(setup).toMatch(/do not follow a successful structured init\s+with doctor/i)
     expect(setup).toContain('--setup-scope')
   })
 
@@ -371,7 +370,6 @@ describe('Notifai agent skill', () => {
       'notifai replies',
       'notifai acknowledge',
       'notifai close',
-      'notifai doctor',
       'notifai init',
       'notifai config show',
       'notifai guidance',
@@ -389,7 +387,7 @@ describe('Notifai agent skill', () => {
       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(/let init install and assess\s+the hooks/i)
     expect(harnessReference).toMatch(/run `notifai login` yourself/i)
     expect(harnessReference).toMatch(/only the user can approve/i)
   })