@raidiant/notifai 1.0.1 → 2.0.0

package/src/commands.ts

@@ -1,10 +1,10 @@
 import { createHash, randomBytes } from 'node:crypto'
-import { spawn } from 'node:child_process'
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
 import {
+  AGENT_ACKNOWLEDGEMENT_MAX_LENGTH,
   CAPABILITIES_V1,
   QUESTION_TEXT_MAX_LENGTH,
   REPLY_MAX_QUESTIONS,
@@ -40,6 +40,7 @@ import {
   globalConfigPath,
   loadConfig,
   sessionConfigPath,
+  stateDir,
   type CliConfig,
   type ConfigKey,
   type FlagOverrides,
@@ -65,6 +66,7 @@ import {
 import type { Tone } from './ui/theme.js'
 import {
   WAITER_CEILING_SECONDS,
+  clearAcknowledgementObligation,
   handleSessionEnd,
   handleStop,
   handleUserPromptSubmit,
@@ -154,6 +156,7 @@ import {
   type SendFlags,
 } from './send.js'
 import type { NativeSkill, NativeSkills, SkillScope } from './native-skills.js'
+import { openUrl } from './platform.js'
 
 export interface CommandIo {
   out(line: string): void
@@ -204,6 +207,8 @@ export interface CommandDeps {
   hookAdapterHome?: string
   /** Test seam; production uses this process's Node and CLI paths. */
   hookInstallTarget?: HookAdapterTarget
+  /** Test seam; production uses process.platform for adapter format and quoting. */
+  hookPlatform?: NodeJS.Platform
   /** Test seam; production uses fetch against base_url. */
   clientFactory?: (baseUrl: string, bearer: string | null, options?: ClientOptions) => ApiClient
   /** Test seam for bounded polling without wall-clock sleeps. */
@@ -682,6 +687,7 @@ export async function sendCommand(
     title: flags.title,
     overall: receipt.overall,
     replayed: receipt.replayed,
+    agent_acknowledgement_required: receipt.agent_acknowledgement_required,
     deliveries: receipt.deliveries.length,
     wait_seconds: waitSeconds,
     exit: receiptExit,
@@ -712,6 +718,9 @@ export async function sendCommand(
               type: 'reply_result',
               request_id: receipt.request_id,
               replies: [],
+              agent_acknowledgement_required: receipt.agent_acknowledgement_required,
+              agent_acknowledgement: null,
+              acknowledgement_command: null,
               degraded: false,
             })
           : JSON.stringify(receipt, null, 2),
@@ -730,15 +739,15 @@ export async function sendCommand(
     recordReplies(deps, receipt.request_id, result.response.replies)
     if (flags.json) {
       deps.io.out(
-        JSON.stringify({
-          type: 'reply_result',
-          request_id: receipt.request_id,
-          replies: result.response.replies,
-          degraded: result.degraded,
-        }),
+        JSON.stringify(replyResultJson(result.response, result.degraded)),
       )
-    } else if (result.response.replies.length > 0) printReplies(deps, result.response.replies)
-    else printNoReply(deps, receipt.request_id, result.response.reply_expires_at)
+    } else if (result.response.replies.length > 0) {
+      printReplies(deps, result.response.replies)
+      printAcknowledgementStatus(deps, result.response)
+    } else {
+      printNoReply(deps, receipt.request_id, result.response.reply_expires_at)
+      printAcknowledgementStatus(deps, result.response)
+    }
     if (result.degraded) {
       log(deps).error('cli.error', {
         kind: 'network',
@@ -890,12 +899,14 @@ export async function repliesCommand(
         })
         recordReplies(deps, requestId, result.response.replies)
         if (flags.json) {
-          jsonBodies.push({ ...result.response, degraded: result.degraded })
+          jsonBodies.push(replyResultJson(result.response, result.degraded))
         } else if (result.response.replies.length > 0) {
           if (flags.pending === true) deps.io.out(`pending request ${requestId}`)
           printReplies(deps, result.response.replies)
+          printAcknowledgementStatus(deps, result.response)
         } else {
           printNoReply(deps, requestId, result.response.reply_expires_at)
+          printAcknowledgementStatus(deps, result.response)
         }
         anyReplies ||= result.response.replies.length > 0
         if (result.degraded) degradedRequestIds.push(requestId)
@@ -993,7 +1004,13 @@ export async function waitForReply(
   return {
     response:
       lastResponse ??
-      ({ request_id: requestId, reply_expires_at: null, replies: [] } satisfies ListRepliesResponse),
+      ({
+        request_id: requestId,
+        reply_expires_at: null,
+        agent_acknowledgement_required: false,
+        agent_acknowledgement: null,
+        replies: [],
+      } satisfies ListRepliesResponse),
     timedOut: true,
     // A poll succeeded at some point, so we do not throw — but the last thing
     // we know is that we could not reach the server. Reporting that as a plain
@@ -1033,6 +1050,56 @@ function isNonNegativeInteger(value: number): boolean {
   return Number.isInteger(value) && value >= 0
 }
 
+function acknowledgementCommand(
+  requestId: string,
+  required: boolean,
+  acknowledgement: ListRepliesResponse['agent_acknowledgement'],
+  hasReply = true,
+): string | null {
+  return required && acknowledgement === null && hasReply
+    ? `notifai acknowledge ${requestId} --text <text>`
+    : null
+}
+
+function replyResultJson(response: ListRepliesResponse, degraded: boolean): object {
+  return {
+    type: 'reply_result',
+    request_id: response.request_id,
+    reply_expires_at: response.reply_expires_at,
+    replies: response.replies,
+    agent_acknowledgement_required: response.agent_acknowledgement_required,
+    agent_acknowledgement: response.agent_acknowledgement,
+    acknowledgement_command: acknowledgementCommand(
+      response.request_id,
+      response.agent_acknowledgement_required,
+      response.agent_acknowledgement,
+      response.replies.length > 0,
+    ),
+    degraded,
+  }
+}
+
+function printAcknowledgementStatus(deps: CommandDeps, response: ListRepliesResponse): void {
+  if (!response.agent_acknowledgement_required) {
+    deps.io.out('Agent Acknowledgement: not required for this request.')
+    return
+  }
+  if (response.agent_acknowledgement !== null) {
+    deps.io.out(
+      `Agent Acknowledgement: recorded at ${response.agent_acknowledgement.created_at}: ${response.agent_acknowledgement.text}`,
+    )
+    return
+  }
+  if (response.replies.length > 0) {
+    deps.io.out('Agent Acknowledgement required.')
+    deps.io.out(
+      `next: Run \`${acknowledgementCommand(response.request_id, true, null)}\` with concrete text saying what you will do because of the reply.`,
+    )
+    return
+  }
+  deps.io.out('Agent Acknowledgement: required after a user reply; no reply is recorded yet.')
+}
+
 function recordReplies(deps: CommandDeps, requestId: string, replies: readonly ReplyView[]): void {
   const logger = log(deps)
   for (const reply of replies) {
@@ -1486,6 +1553,7 @@ function stopWakeRoute(
 ): EscalationDeliveryRoute | undefined {
   if (sessionId === undefined) return undefined
   if (harness === 'claude-code') {
+    if ((deps.hookPlatform ?? process.platform) === 'win32') return undefined
     return claudeWakeRoute({
       sessionId,
       cwd,
@@ -1709,7 +1777,7 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
   const { active, contested } = resolveActiveHarness(deps.env, deps.cwd, now)
   let sessionId: string | undefined
   if (active !== null) {
-    const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome)
+    const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform)
     const activeInstalled = installations.some(
       (installation) => installation.harness === active.harness,
     )
@@ -1991,10 +2059,10 @@ function activeQuestionRouteProblems(
       }
     }
   }
-  for (const problem of inspectHookAdapter(deps.hookAdapterHome).problems) {
+  for (const problem of inspectHookAdapter(deps.hookAdapterHome, deps.hookPlatform).problems) {
     problems.push(problem)
   }
-  for (const installation of matching) problems.push(...stopShapeProblems(installation))
+  for (const installation of matching) problems.push(...stopShapeProblems(installation, deps.hookPlatform))
   problems.push(...codexTrustProblems(matching, deps.env))
   return [...new Set(problems)]
 }
@@ -2056,7 +2124,7 @@ function diagnoseActiveHarnessSession(
  * checked after a prompt before assuming that a new session is required.
  */
 function diagnoseMissingSession(deps: CommandDeps): string[] {
-  const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome)
+  const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform)
   if (installations.length === 0) {
     return [
       'Could not tell which harness session this is: no Notifai hooks are installed for this project.',
@@ -2119,14 +2187,95 @@ function hookActivationAdvice(installations: Installation[]): string {
   return `${advice.join('. ')}.`
 }
 
+/** Record the one Agent Acknowledgement associated with a replied-to request. */
+export async function acknowledgeCommand(
+  deps: CommandDeps,
+  requestId: string,
+  flags: { text?: string; json?: boolean },
+): Promise<number> {
+  const text = flags.text?.trim() ?? ''
+  if (text.length === 0) {
+    deps.io.err('--text is required and must contain non-whitespace text.')
+    return EXIT.usage
+  }
+  if (text.length > AGENT_ACKNOWLEDGEMENT_MAX_LENGTH) {
+    deps.io.err(
+      `--text must be at most ${AGENT_ACKNOWLEDGEMENT_MAX_LENGTH} characters after trimming.`,
+    )
+    return EXIT.usage
+  }
+
+  const logger = log(deps)
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  logger.info('acknowledgement.attempted', {
+    request_id: requestId,
+    text,
+    characters: text.length,
+  })
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  try {
+    const result = await authed.client.putAgentAcknowledgement(requestId, { text })
+    const output = {
+      request_id: requestId,
+      outcome: result.status,
+      acknowledgement: result.agent_acknowledgement,
+      agent_acknowledgement_required: true,
+    }
+    logger.info('acknowledgement.outcome', {
+      request_id: requestId,
+      outcome: result.status,
+      text: result.agent_acknowledgement.text,
+      created_at: result.agent_acknowledgement.created_at,
+      agent_acknowledgement_required: true,
+    })
+    const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)())
+    if (sessionId !== null) {
+      clearAcknowledgementObligation(sessionId, deps.env, requestId)
+    }
+    if (flags.json) deps.io.out(JSON.stringify(output, null, 2))
+    else {
+      deps.io.out(
+        `Agent Acknowledgement ${result.status} for ${requestId} at ${result.agent_acknowledgement.created_at}.`,
+      )
+    }
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err, { operation: 'agent_acknowledgement', request_id: requestId })
+  }
+}
+
 /** Retire a question so a late answer is rejected rather than silently lost. */
-export async function closeCommand(deps: CommandDeps, requestId: string): Promise<number> {
+export async function closeCommand(
+  deps: CommandDeps,
+  requestId: string,
+  flags: { json?: boolean } = {},
+): Promise<number> {
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const authed = authedClient(deps, config)
   if (!authed) return EXIT.auth
   try {
-    await authed.client.closeReplies(requestId)
-    deps.io.out(`Closed the reply window for ${requestId}.`)
+    const response = await authed.client.closeReplies(requestId)
+    if (flags.json) {
+      deps.io.out(
+        JSON.stringify(
+          {
+            ...response,
+            acknowledgement_command: acknowledgementCommand(
+              response.request_id,
+              response.agent_acknowledgement_required,
+              response.agent_acknowledgement,
+              response.replies.length > 0,
+            ),
+          },
+          null,
+          2,
+        ),
+      )
+    } else {
+      deps.io.out(`Closed the reply window for ${requestId}.`)
+      if (response.replies.length > 0) printAcknowledgementStatus(deps, response)
+    }
     return EXIT.ok
   } catch (err) {
     return reportError(deps, err)
@@ -2207,15 +2356,17 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   const adapterTarget = resolveHookAdapterTarget(deps, flags)
   const scriptPath =
     flags.scriptPath ?? fileHookInstallTarget(adapterTarget)?.scriptPath ?? process.argv[1] ?? 'notifai'
+  const hookPlatform = deps.hookPlatform ?? process.platform
+  const nodePath = adapterTarget.execPath
   let adapterPath: string
   try {
-    adapterPath = installHookAdapter(adapterTarget, deps.hookAdapterHome).path
+    adapterPath = installHookAdapter(adapterTarget, deps.hookAdapterHome, hookPlatform).path
   } catch (err) {
     deps.io.err(`Could not prepare the stable hook adapter: ${String(err)}`)
     return EXIT.failed
   }
   const wantGlobal = flags.global === true
-  const existing = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome).filter(
+  const existing = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform).filter(
     (installation) => installation.harness === harness,
   )
   const otherScope = existing.filter((installation) => installation.global !== wantGlobal)
@@ -2231,7 +2382,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       return EXIT.failed
     }
   }
-  const file = settingsFile(harness, wantGlobal, deps.cwd, deps.env)
+  const file = settingsFile(harness, wantGlobal, deps.cwd, deps.env, hookPlatform)
 
   // OpenCode's adapter is a generated plugin module rather than a handler
   // merged into a settings document, so it owns the whole file.
@@ -2239,6 +2390,8 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
     return installOpencodePlugin(deps, file, {
       adapterPath,
       timeoutSeconds: BLOCKING_STOP_TIMEOUT_SECONDS,
+      platform: hookPlatform,
+      nodePath,
     })
   }
 
@@ -2251,6 +2404,8 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
           buildCursorHookConfig({
             adapterPath,
             harness: 'cursor',
+            platform: hookPlatform,
+            nodePath,
           }),
           scriptPath,
         )
@@ -2276,6 +2431,8 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
         buildHookConfig({
           adapterPath,
           harness,
+          platform: hookPlatform,
+          nodePath,
         }),
         scriptPath,
       )
@@ -2331,7 +2488,12 @@ function foreignStopHandlers(document: { hooks?: Record<string, { hooks?: { comm
 function installOpencodePlugin(
   deps: CommandDeps,
   file: string,
-  options: { adapterPath: string; timeoutSeconds: number },
+  options: {
+    adapterPath: string
+    timeoutSeconds: number
+    platform?: NodeJS.Platform
+    nodePath?: string
+  },
 ): number {
   try {
     withTargetFileLock(file, () => {
@@ -2360,7 +2522,13 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
   const harness = resolveHarness(deps, flags.harness)
   if (!harness) return EXIT.usage
   const scriptPath = flags.scriptPath ?? process.argv[1] ?? 'notifai'
-  const file = settingsFile(harness, flags.global ?? false, deps.cwd, deps.env)
+  const file = settingsFile(
+    harness,
+    flags.global ?? false,
+    deps.cwd,
+    deps.env,
+    deps.hookPlatform,
+  )
   if (harness === 'opencode') {
     try {
       return withTargetFileLock(file, () => {
@@ -3193,9 +3361,7 @@ function setupProofPath(deps: CommandDeps): string {
     // the resolved absolute path is still a stable local identity for it.
   }
   const digest = createHash('sha256').update(projectDir).digest('hex').slice(0, 32)
-  const xdg = deps.env['XDG_STATE_HOME']
-  const base = xdg && xdg !== '' ? xdg : path.join(os.homedir(), '.local', 'state')
-  return path.join(base, 'notifai', 'setup-proofs', `${digest}.json`)
+  return path.join(stateDir(deps.env), 'setup-proofs', `${digest}.json`)
 }
 
 function readSetupProof(deps: CommandDeps): SetupProofRecord | null {
@@ -3579,6 +3745,9 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
       const observed = observedCompanionReceipt(snapshot, proof.device_id)
       if (observed) {
         spinner?.stop(`Receipt observed from ${observed.delivery.device_name}`)
+        deps.io.out(
+          `Companion Receipt (the app's delivery confirmation) observed from ${observed.delivery.device_name}.`,
+        )
         return 'closed'
       }
       lastError = null
@@ -4399,7 +4568,7 @@ function remedyLine(state: ReadinessState): string {
  * is, is each check's own call (`HookCheck`).
  */
 function hookStates(deps: CommandDeps): ReadinessState[] {
-  const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome)
+  const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform)
   const active = activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)())
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const settings: ReadinessState = {
@@ -4492,13 +4661,16 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
  *     hashes into `trusted_hash`, and an untrusted handler is simply not run.
  *   - Everything else blocks its turn and needs a ceiling above the wait.
  */
-function stopShapeProblems(installation: Installation): string[] {
+function stopShapeProblems(
+  installation: Installation,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
   if (installation.harness === 'codex') return []
   const problems: string[] = []
   for (const handler of installation.handlers.filter(
     (entry) => handlerEvent(entry.command) === 'stop',
   )) {
-    if (installation.harness === 'claude-code') {
+    if (installation.harness === 'claude-code' && platform !== 'win32') {
       if (handler.async !== true) {
         problems.push(
           `${installation.file} declares a blocking Stop handler; the Claude Code wake route needs \`async: true\` so the turn ends while the waiter runs`,
@@ -4532,7 +4704,7 @@ interface HookCheck {
 
 function hookChecks(deps: CommandDeps): HookCheck[] {
   const checks: HookCheck[] = []
-  const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome)
+  const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform)
 
   // Not having hooks is a setup someone chose, not a fault: `send` works
   // without them. A setup that cannot work is what deserves to go red.
@@ -4651,7 +4823,7 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
   const adapterProblems = installations.flatMap((installation) =>
     (installation.problems ?? []).map((problem) => `${installation.file}: ${problem}`),
   )
-  const sharedAdapter = inspectHookAdapter(deps.hookAdapterHome)
+  const sharedAdapter = inspectHookAdapter(deps.hookAdapterHome, deps.hookPlatform)
   adapterProblems.push(...sharedAdapter.problems)
   if (adapterProblems.length > 0) {
     checks.push({
@@ -4683,7 +4855,7 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
   })
 
   const shapeProblems = installations.flatMap((installation) =>
-    stopShapeProblems(installation).map(
+    stopShapeProblems(installation, deps.hookPlatform).map(
       (problem) =>
         `${problem} — run \`notifai hooks install --harness ${installation.harness}${installation.global ? ' --global' : ''}\``,
     ),
@@ -4896,7 +5068,7 @@ function wakeRouteCheck(
   if (active.harness === 'claude-code') {
     const readiness = inspectClaudeInbox({
       pid: deps.claudeSourcePid ?? claudeSessionPid(deps.env),
-      platform: process.platform,
+      platform: deps.hookPlatform ?? process.platform,
       readDescriptor:
         deps.claudeWake?.readDescriptor ?? systemClaudeWakeAdapters(deps.env).readDescriptor,
       socketExists: (socketPath) => existsSync(socketPath),
@@ -4913,7 +5085,7 @@ function wakeRouteCheck(
   }
   if (active.harness === 'codex') {
     const readiness = inspectCodexResume(deps.env, {
-      platform: process.platform,
+      platform: deps.hookPlatform ?? process.platform,
       directoryExists: (directory) => existsSync(directory),
     })
     return {
@@ -5069,20 +5241,6 @@ export function realIo(env: NodeJS.ProcessEnv = process.env): CommandIo {
           return log.error(message)
       }
     },
-    openUrl: (url) => {
-      try {
-        if (process.platform === 'darwin') {
-          spawn('open', [url], { stdio: 'ignore', detached: true }).unref()
-        } else if (process.platform === 'win32') {
-          // `start` is a cmd builtin; spawn('start', …) cannot work on Windows.
-          // Empty title argument keeps URLs with special characters intact.
-          spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref()
-        } else {
-          spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref()
-        }
-      } catch {
-        // Browser opening is best-effort; the URL is printed anyway.
-      }
-    },
+    openUrl,
   }
 }

package/src/config.ts

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readFileSync, realpathSync } from 'node:fs'
-import os from 'node:os'
 import path from 'node:path'
 import { parse as parseToml } from 'smol-toml'
 import type { CLI_SOUNDS, INTERRUPTION_LEVELS } from '@raidiant/notifai-protocol'
+import { configHome, stateHome } from './platform.js'
 
 /**
  * Layered configuration with provenance. Most specific wins:
@@ -163,10 +163,11 @@ export function configDefaultValue(key: ConfigKey): unknown {
   return DEFAULTS[key]
 }
 
-export function globalConfigDir(env: NodeJS.ProcessEnv = process.env): string {
-  const xdg = env['XDG_CONFIG_HOME']
-  const base = xdg && xdg !== '' ? xdg : path.join(os.homedir(), '.config')
-  return path.join(base, 'notifai')
+export function globalConfigDir(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  return path.join(configHome(env, platform), 'notifai')
 }
 
 export function globalConfigPath(env: NodeJS.ProcessEnv = process.env): string {
@@ -178,10 +179,11 @@ export function globalConfigPath(env: NodeJS.ProcessEnv = process.env): string {
  * session config overrides. Separate from the config dir because none of it is
  * user-authored and none of it should ever be synced or committed.
  */
-export function stateDir(env: NodeJS.ProcessEnv = process.env): string {
-  const xdg = env['XDG_STATE_HOME']
-  const base = xdg && xdg !== '' ? xdg : path.join(os.homedir(), '.local', 'state')
-  return path.join(base, 'notifai')
+export function stateDir(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  return path.join(stateHome(env, platform), 'notifai')
 }
 
 /** Per-harness-session override file; see the ConfigSource doc comment. */