@raidiant/notifai 9.2.2 → 10.0.0

package/src/harnesses.test.ts

@@ -1,5 +1,26 @@
+import { readFileSync } from 'node:fs'
 import { describe, expect, it } from 'vitest'
-import { HARNESS_CAPABILITIES, HARNESS_LABELS, HARNESSES } from './harnesses.js'
+import {
+  HARNESS_CAPABILITIES,
+  HARNESS_LABELS,
+  HERMES_CLASSIC_CLI_LOCAL_CAPABILITY,
+  HERMES_QUESTION_ROUTING_UNAVAILABLE,
+  HOOK_INSTALLABLE_HARNESSES,
+  SOURCE_CONTEXT_HARNESSES,
+  hermesClassicCliLocalInstance,
+  isHookInstallableHarness,
+  questionRoutingCapability,
+} from './harnesses.js'
+
+const PINNED_HERMES_TRACE = JSON.parse(
+  readFileSync(new URL('./fixtures/hermes-0.20.6-classic-cli-local.json', import.meta.url), 'utf8'),
+) as {
+  instance: { harness: 'hermes'; surface: 'classic-cli'; terminalBackend: 'local' }
+  observedToolSubprocessEnv: { HERMES_SESSION_ID: string }
+  supported: string[]
+  unsupported: string[]
+  deferred: string[]
+}
 
 /**
  * This file used to hold a verbatim copy of the table below it, which meant
@@ -8,23 +29,36 @@ import { HARNESS_CAPABILITIES, HARNESS_LABELS, HARNESSES } from './harnesses.js'
  * edit. What is worth asserting is the shape the rest of the CLI assumes.
  */
 describe('harness contract', () => {
-  it('describes every shipped harness, and only those', () => {
-    expect(Object.keys(HARNESS_CAPABILITIES).sort()).toEqual([...HARNESSES].sort())
-    expect(Object.keys(HARNESS_LABELS).sort()).toEqual([...HARNESSES].sort())
+  it('describes every shipped Source Context harness, and only those', () => {
+    expect(Object.keys(HARNESS_LABELS).sort()).toEqual([...SOURCE_CONTEXT_HARNESSES].sort())
+  })
+
+  it('keeps managed hook installation a strict subset of Source Context', () => {
+    expect(HOOK_INSTALLABLE_HARNESSES).toEqual(['claude-code', 'codex', 'cursor', 'opencode'])
+    expect(SOURCE_CONTEXT_HARNESSES).toContain('hermes')
+    expect(HOOK_INSTALLABLE_HARNESSES).not.toContain('hermes')
+    expect(Object.keys(HARNESS_CAPABILITIES).sort()).toEqual([...HOOK_INSTALLABLE_HARNESSES].sort())
+    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
+      expect(isHookInstallableHarness(harness)).toBe(true)
+    }
+    expect(isHookInstallableHarness('hermes')).toBe(false)
   })
 
   it('gives a harness that cannot continue a turn no route to pretend with', () => {
     // `ask` fails closed on these, and the reason it can is that the two facts
     // agree. A harness claiming a delivery route while declaring it cannot
     // continue would accept an answer into a void.
-    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
+      const capability = questionRoutingCapability(harness)
       if (capability.stopContinuation !== 'unsupported') continue
       expect(capability.deliveryRoutes, harness).toEqual(['unsupported'])
     }
+    expect(HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryRoutes).toEqual(['unsupported'])
   })
 
   it('gives a harness that can continue a turn at least one real route', () => {
-    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
+      const capability = HARNESS_CAPABILITIES[harness]
       if (capability.stopContinuation === 'unsupported') continue
       expect(capability.deliveryRoutes.length, harness).toBeGreaterThan(0)
       expect(capability.deliveryRoutes, harness).not.toContain('unsupported')
@@ -35,8 +69,73 @@ describe('harness contract', () => {
   })
 
   it('explains each harness in prose an operator can act on', () => {
-    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
-      expect(capability.deliveryContract.length, harness).toBeGreaterThan(40)
+    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
+      expect(questionRoutingCapability(harness).deliveryContract.length, harness).toBeGreaterThan(40)
+    }
+    expect(HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryContract.length).toBeGreaterThan(40)
+  })
+
+  it('keeps Claude Code, Codex, Cursor, and OpenCode continuation contracts unchanged', () => {
+    expect(HARNESS_CAPABILITIES['claude-code'].stopContinuation).toBe('decision-block')
+    expect(HARNESS_CAPABILITIES['claude-code'].deliveryRoutes).toEqual([
+      'hook-continuation',
+      'inbox-socket',
+      'cold-resume',
+      'hold-for-next-turn',
+    ])
+    expect(HARNESS_CAPABILITIES.codex.stopContinuation).toBe('decision-block')
+    expect(HARNESS_CAPABILITIES.codex.deliveryRoutes).toEqual([
+      'hook-continuation',
+      'cold-resume',
+      'hold-for-next-turn',
+    ])
+    expect(HARNESS_CAPABILITIES.cursor).toEqual({
+      stopContinuation: 'unsupported',
+      deliveryRoutes: ['unsupported'],
+      deliveryContract: HARNESS_CAPABILITIES.cursor.deliveryContract,
+    })
+    expect(HARNESS_CAPABILITIES.opencode.stopContinuation).toBe('unsupported')
+    expect(HARNESS_CAPABILITIES.opencode.deliveryRoutes).toEqual(['unsupported'])
+  })
+
+  it('treats the pinned Hermes classic CLI/local trace as send-only', () => {
+    expect(HERMES_CLASSIC_CLI_LOCAL_CAPABILITY.instance).toEqual(PINNED_HERMES_TRACE.instance)
+    expect(PINNED_HERMES_TRACE.supported).toContain('deliberate-send')
+    expect(PINNED_HERMES_TRACE.unsupported).toContain('question-routing')
+    expect(PINNED_HERMES_TRACE.deferred).toContain('gateway')
+    expect(HERMES_CLASSIC_CLI_LOCAL_CAPABILITY.sourceContext).toBe(
+      'hermes-session-id-and-invocation-cwd',
+    )
+    expect(HERMES_QUESTION_ROUTING_UNAVAILABLE.stopContinuation).toBe('unsupported')
+    expect(HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryRoutes).toEqual(['unsupported'])
+  })
+
+  it('resolves only the pinned classic CLI/local marker envelope', () => {
+    expect(
+      hermesClassicCliLocalInstance({
+        HERMES_SESSION_ID: PINNED_HERMES_TRACE.observedToolSubprocessEnv.HERMES_SESSION_ID,
+      }),
+    ).toEqual(PINNED_HERMES_TRACE.instance)
+    expect(
+      hermesClassicCliLocalInstance({
+        HERMES_SESSION_ID: PINNED_HERMES_TRACE.observedToolSubprocessEnv.HERMES_SESSION_ID,
+        HERMES_SESSION_SOURCE: 'cli',
+        TERMINAL_ENV: 'local',
+      }),
+    ).toEqual(PINNED_HERMES_TRACE.instance)
+    for (const env of [
+      { HERMES_SESSION_KEY: 'gateway-key' },
+      { HERMES_SESSION_PLATFORM: 'api_server' },
+      { HERMES_SESSION_SOURCE: 'tui' },
+      { TERMINAL_ENV: 'docker' },
+      { TERMINAL_ENV: 'ssh' },
+    ]) {
+      expect(
+        hermesClassicCliLocalInstance({
+          HERMES_SESSION_ID: PINNED_HERMES_TRACE.observedToolSubprocessEnv.HERMES_SESSION_ID,
+          ...env,
+        }),
+      ).toBeNull()
     }
   })
 })

package/src/harnesses.ts

@@ -1,13 +1,29 @@
-/** Every harness Notifai ships. This is the sole source of the harness union. */
-export const HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'] as const
+/** Every harness Notifai can name in Source Context when authoritatively known. */
+export const SOURCE_CONTEXT_HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode', 'hermes'] as const
 
-export type Harness = (typeof HARNESSES)[number]
+export type SourceContextHarness = (typeof SOURCE_CONTEXT_HARNESSES)[number]
 
-export const HARNESS_LABELS: Record<Harness, string> = {
+/**
+ * Harnesses whose lifecycle Notifai can install and manage.
+ *
+ * Source Context is the broader vocabulary. Managed hook installation is a
+ * narrower, independently proven cell: Hermes can appear in Source Context
+ * without being hook-installable.
+ */
+export const HOOK_INSTALLABLE_HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'] as const
+
+export type HookInstallableHarness = (typeof HOOK_INSTALLABLE_HARNESSES)[number]
+
+export function isHookInstallableHarness(value: string): value is HookInstallableHarness {
+  return (HOOK_INSTALLABLE_HARNESSES as readonly string[]).includes(value)
+}
+
+export const HARNESS_LABELS: Record<SourceContextHarness, string> = {
   'claude-code': 'Claude Code',
   codex: 'Codex',
   cursor: 'Cursor',
   opencode: 'OpenCode',
+  hermes: 'Hermes',
 }
 
 export type DeliveryRoute =
@@ -29,33 +45,98 @@ export interface HarnessCapability {
   deliveryContract: string
 }
 
+const CLAUDE_CODE_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'decision-block',
+  deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
+  deliveryContract:
+    'the Stop hook returns at once and waits out of band through the complete answer window, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
+}
+
+const CODEX_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'decision-block',
+  deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
+  deliveryContract:
+    'live Stop continuation while the turn is held through the complete answer window; crash recovery may resume only a stopped thread behind its writer lock',
+}
+
+const CURSOR_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'unsupported',
+  deliveryRoutes: ['unsupported'],
+  deliveryContract:
+    'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
+}
+
+const OPENCODE_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'unsupported',
+  deliveryRoutes: ['unsupported'],
+  deliveryContract:
+    'no proven answer continuation after session.idle; use a blocking reply command',
+}
+
+export const HERMES_QUESTION_ROUTING_UNAVAILABLE: HarnessCapability = {
+  stopContinuation: 'unsupported',
+  deliveryRoutes: ['unsupported'],
+  deliveryContract:
+    'Hermes asynchronous ask has no proven continuation owner on this integration surface. Use a blocking `notifai send --reply` question',
+}
+
 /**
- * Exhaustive runtime contract. Adding a harness without deciding every
- * continuation joint is a type error, not a silently degraded notification.
+ * The one Hermes integration instance proven by the pinned vertical probe.
+ *
+ * This is evidence-bearing capability data, not an adapter. Unsupported and
+ * deferred surfaces intentionally have no empty implementation object here.
  */
-export const HARNESS_CAPABILITIES: Record<Harness, HarnessCapability> = {
-  'claude-code': {
-    stopContinuation: 'decision-block',
-    deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
-    deliveryContract:
-      'the Stop hook returns at once and waits out of band, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
-  },
-  codex: {
-    stopContinuation: 'decision-block',
-    deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
-    deliveryContract:
-      'live Stop continuation while the turn is held; once it returns, a stopped thread is resumed behind its writer lock and anything else waits for the next turn',
-  },
-  cursor: {
-    stopContinuation: 'unsupported',
-    deliveryRoutes: ['unsupported'],
-    deliveryContract:
-      'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
-  },
-  opencode: {
-    stopContinuation: 'unsupported',
-    deliveryRoutes: ['unsupported'],
-    deliveryContract:
-      'no proven answer continuation after session.idle; use a blocking reply command',
+export const HERMES_CLASSIC_CLI_LOCAL_CAPABILITY = {
+  instance: {
+    harness: 'hermes',
+    surface: 'classic-cli',
+    terminalBackend: 'local',
   },
+  setup: 'unsupported',
+  activation: 'unsupported',
+  sourceContext: 'hermes-session-id-and-invocation-cwd',
+  continuation: 'unsupported',
+} as const
+
+export type HermesClassicCliLocalInstance =
+  (typeof HERMES_CLASSIC_CLI_LOCAL_CAPABILITY)['instance']
+
+/**
+ * Resolve only the Hermes instance whose complete marker envelope was proven.
+ *
+ * `HERMES_SESSION_ID` is also bridged by deferred gateway, TUI, API, ACP, and
+ * remote-backend paths. Their first-party routing/source/backend markers keep
+ * those cells distinct. Missing source/backend values are the pinned classic
+ * CLI defaults; a gateway key is never part of that instance.
+ */
+export function hermesClassicCliLocalInstance(
+  env: NodeJS.ProcessEnv,
+): HermesClassicCliLocalInstance | null {
+  const sessionId = (env['HERMES_SESSION_ID'] ?? '').trim()
+  const sessionKey = (env['HERMES_SESSION_KEY'] ?? '').trim()
+  const platform = (env['HERMES_SESSION_PLATFORM'] ?? '').trim().toLowerCase()
+  const source = (env['HERMES_SESSION_SOURCE'] ?? '').trim().toLowerCase()
+  const terminalBackend = (env['TERMINAL_ENV'] ?? '').trim().toLowerCase()
+  if (sessionId === '' || sessionKey !== '' || platform !== '') return null
+  if (source !== '' && source !== 'cli') return null
+  if (terminalBackend !== '' && terminalBackend !== 'local') return null
+  return HERMES_CLASSIC_CLI_LOCAL_CAPABILITY.instance
+}
+
+/**
+ * Question-routing contract for hook-installable harnesses.
+ *
+ * Hermes is deliberately absent: a send-only surface must not occupy this
+ * table with a fake managed-hook continuation route.
+ */
+export const HARNESS_CAPABILITIES: Record<HookInstallableHarness, HarnessCapability> = {
+  'claude-code': CLAUDE_CODE_CAPABILITY,
+  codex: CODEX_CAPABILITY,
+  cursor: CURSOR_CAPABILITY,
+  opencode: OPENCODE_CAPABILITY,
+}
+
+/** Question-routing capability for the active harness integration. */
+export function questionRoutingCapability(harness: HookInstallableHarness): HarnessCapability {
+  return HARNESS_CAPABILITIES[harness]
 }

package/src/hook-adapter.test.ts

@@ -21,6 +21,7 @@ import {
   isNpxAdapterTarget,
 } from './hook-adapter.js'
 import { buildHookConfig, codexHookIdentityHash, type InstalledHandler } from './install-hooks.js'
+import { enableProject, projectBinding } from './project-enablement.js'
 
 function isolated(): { root: string; homeDir: string } {
   const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-hook-adapter-'))
@@ -28,22 +29,40 @@ function isolated(): { root: string; homeDir: string } {
 }
 
 describe('stable hook adapter', () => {
-  it('delivers session activation through the installed adapter before setup exists', () => {
+  it('keeps the installed adapter silent until the Project is enabled', () => {
     const { root, homeDir } = isolated()
+    const env = {
+      ...process.env,
+      HOME: homeDir,
+      XDG_CONFIG_HOME: path.join(root, 'config'),
+      XDG_STATE_HOME: path.join(root, 'state'),
+    }
     const scriptPath = fileURLToPath(new URL('../dist/main.js', import.meta.url))
     const installed = installHookAdapter({ execPath: process.execPath, scriptPath }, homeDir)
+    const disabled = spawnSync(
+      installed.path,
+      ['hook', 'session-start', '--owner', 'notifai', '--harness', 'codex'],
+      {
+        encoding: 'utf8',
+        input: JSON.stringify({ session_id: 'adapter-session', cwd: root, source: 'startup' }),
+        env,
+      },
+    )
+
+    expect(disabled.status).toBe(0)
+    expect(disabled.stderr).toBe('')
+    expect(disabled.stdout).toBe('')
+
+    const binding = projectBinding(root, env)
+    if (binding === null) throw new Error('test Project binding unavailable')
+    enableProject(binding)
     const run = spawnSync(
       installed.path,
       ['hook', 'session-start', '--owner', 'notifai', '--harness', 'codex'],
       {
         encoding: 'utf8',
         input: JSON.stringify({ session_id: 'adapter-session', cwd: root, source: 'startup' }),
-        env: {
-          ...process.env,
-          HOME: homeDir,
-          XDG_CONFIG_HOME: path.join(root, 'config'),
-          XDG_STATE_HOME: path.join(root, 'state'),
-        },
+        env,
       },
     )
 
@@ -52,7 +71,7 @@ describe('stable hook adapter', () => {
     expect(JSON.parse(run.stdout)).toMatchObject({
       hookSpecificOutput: {
         hookEventName: 'SessionStart',
-        additionalContext: expect.stringMatching(/Notifai.*session/i),
+        additionalContext: expect.stringMatching(/Notifai.*enabled.*Project/i),
       },
     })
   })