@raidiant/notifai 0.3.0 → 0.5.0

package/src/claude-wake.ts

@@ -0,0 +1,489 @@
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createConnection } from 'node:net'
+import type {
+  ContinuationEvent,
+  DeliveryOutcome,
+  EscalationDeliveryRoute,
+} from './hooks.js'
+
+/** Claude Code's currently observed inbox protocol. Unknown versions fail closed. */
+export const CLAUDE_PEER_PROTOCOL = 1
+
+/** The first Claude Code release that publishes a session inbox socket. */
+export const CLAUDE_MIN_INBOX_VERSION = '2.1.224'
+
+/** The inbox socket is a Unix domain socket; no Windows implementation exists. */
+const INBOX_PLATFORMS: ReadonlySet<string> = new Set(['darwin', 'linux'])
+
+/** macOS verifies own-child ancestry only while the posting process is alive. */
+export const CLAUDE_POST_SEND_LIVENESS_MS = 8_000
+
+export type ClaudeLiveStatus = 'idle' | 'busy'
+
+export interface ClaudeSessionDescriptor {
+  pid: number
+  sessionId: string
+  cwd: string
+  startedAt: number
+  procStart: string
+  version: string
+  peerProtocol: number
+  messagingSocketPath: string
+  status: string
+}
+
+export interface ClaudeAgentObservation {
+  pid: number
+  sessionId: string
+  startedAt: number
+  status: string
+}
+
+export interface ClaudeWakeAdapters {
+  listAgents(): Promise<unknown>
+  readDescriptor(pid: number): unknown
+  sendSocket(socketPath: string, line: string): Promise<void>
+  resume(sessionId: string, cwd: string, context: string): Promise<void>
+  sleep(milliseconds: number): Promise<void>
+}
+
+export type ClaudeWakeObservation =
+  | {
+      state: 'live-idle' | 'live-busy'
+      descriptor: ClaudeSessionDescriptor
+    }
+  | { state: 'stopped' }
+  | { state: 'unknown'; reason: string }
+
+const LIVE_STATUSES: ReadonlySet<string> = new Set(['idle', 'busy'])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function parseAgent(value: unknown): ClaudeAgentObservation | null {
+  if (!isRecord(value)) return null
+  if (
+    typeof value['pid'] !== 'number' ||
+    !Number.isInteger(value['pid']) ||
+    value['pid'] <= 0 ||
+    typeof value['sessionId'] !== 'string' ||
+    value['sessionId'] === '' ||
+    typeof value['startedAt'] !== 'number' ||
+    !Number.isFinite(value['startedAt']) ||
+    typeof value['status'] !== 'string'
+  ) {
+    return null
+  }
+  return {
+    pid: value['pid'],
+    sessionId: value['sessionId'],
+    startedAt: value['startedAt'],
+    status: value['status'],
+  }
+}
+
+function parseDescriptor(value: unknown): ClaudeSessionDescriptor | null {
+  if (!isRecord(value)) return null
+  if (
+    typeof value['pid'] !== 'number' ||
+    !Number.isInteger(value['pid']) ||
+    value['pid'] <= 0 ||
+    typeof value['sessionId'] !== 'string' ||
+    value['sessionId'] === '' ||
+    typeof value['cwd'] !== 'string' ||
+    value['cwd'] === '' ||
+    typeof value['startedAt'] !== 'number' ||
+    !Number.isFinite(value['startedAt']) ||
+    typeof value['procStart'] !== 'string' ||
+    value['procStart'] === '' ||
+    typeof value['version'] !== 'string' ||
+    value['version'] === '' ||
+    typeof value['peerProtocol'] !== 'number' ||
+    !Number.isInteger(value['peerProtocol']) ||
+    typeof value['messagingSocketPath'] !== 'string' ||
+    value['messagingSocketPath'] === '' ||
+    typeof value['status'] !== 'string'
+  ) {
+    return null
+  }
+  return {
+    pid: value['pid'],
+    sessionId: value['sessionId'],
+    cwd: value['cwd'],
+    startedAt: value['startedAt'],
+    procStart: value['procStart'],
+    version: value['version'],
+    peerProtocol: value['peerProtocol'],
+    messagingSocketPath: value['messagingSocketPath'],
+    status: value['status'],
+  }
+}
+
+/**
+ * Observe one exact Claude Code session without guessing.
+ *
+ * `claude agents --json` is the liveness oracle: Claude Code itself validates
+ * each registry row against both PID and process start time before returning it.
+ * The descriptor supplies the socket and peer protocol, but is never trusted as
+ * proof that a process still owns the session.
+ */
+export async function observeClaudeSession(
+  sessionId: string,
+  adapters: Pick<ClaudeWakeAdapters, 'listAgents' | 'readDescriptor'>,
+): Promise<ClaudeWakeObservation> {
+  let listed: unknown
+  try {
+    listed = await adapters.listAgents()
+  } catch (err) {
+    return {
+      state: 'unknown',
+      reason: `claude agents probe failed: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+  if (!Array.isArray(listed)) {
+    return { state: 'unknown', reason: 'claude agents returned an invalid document' }
+  }
+
+  const matchingRaw = listed.filter(
+    (value) => isRecord(value) && value['sessionId'] === sessionId,
+  )
+  if (matchingRaw.length === 0) return { state: 'stopped' }
+  if (matchingRaw.length !== 1) {
+    return { state: 'unknown', reason: 'claude agents returned duplicate session owners' }
+  }
+  const agent = parseAgent(matchingRaw[0])
+  if (agent === null) {
+    return { state: 'unknown', reason: 'claude agents returned an invalid matching row' }
+  }
+
+  let descriptorRaw: unknown
+  try {
+    descriptorRaw = adapters.readDescriptor(agent.pid)
+  } catch (err) {
+    return {
+      state: 'unknown',
+      reason: `Claude session descriptor could not be read: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+  const descriptor = parseDescriptor(descriptorRaw)
+  if (descriptor === null) {
+    return { state: 'unknown', reason: 'Claude session descriptor has an unknown shape' }
+  }
+  if (
+    descriptor.pid !== agent.pid ||
+    descriptor.sessionId !== agent.sessionId ||
+    descriptor.startedAt !== agent.startedAt
+  ) {
+    return { state: 'unknown', reason: 'Claude liveness probe and descriptor disagree' }
+  }
+  if (descriptor.peerProtocol !== CLAUDE_PEER_PROTOCOL) {
+    return {
+      state: 'unknown',
+      reason: `unsupported Claude peer protocol ${descriptor.peerProtocol}`,
+    }
+  }
+  if (!LIVE_STATUSES.has(agent.status)) {
+    return { state: 'unknown', reason: `Claude session status ${agent.status} is not wakeable` }
+  }
+  return {
+    state: agent.status === 'idle' ? 'live-idle' : 'live-busy',
+    descriptor,
+  }
+}
+
+export type ClaudeInboxReadiness =
+  | { state: 'ready'; socketPath: string; version: string }
+  | { state: 'unavailable'; reason: string }
+
+/** Ordered comparison of dotted release numbers, ignoring any suffix. */
+function versionAtLeast(version: string, minimum: string): boolean {
+  const parse = (value: string): number[] =>
+    value.split('.').map((part) => Number.parseInt(part, 10) || 0)
+  const left = parse(version)
+  const right = parse(minimum)
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const a = left[index] ?? 0
+    const b = right[index] ?? 0
+    if (a !== b) return a > b
+  }
+  return true
+}
+
+/**
+ * Whether an answer could reach this exact Claude session over its inbox
+ * socket, decided from evidence already on disk.
+ *
+ * Read-only by construction: it reads the session descriptor and asks whether
+ * the socket file exists, and never connects to it. A diagnostic that delivers
+ * a message is not a diagnostic.
+ *
+ * Every negative answer here is a degradation, not a failure — the accepted
+ * journal still replays the answer at the session's next turn. What it buys is
+ * that the reason is nameable in advance instead of being discovered as
+ * silence. The common one is `--bare`, which binds no socket at all (and runs
+ * no hooks either, so nothing would have registered a question in the first
+ * place).
+ */
+export function inspectClaudeInbox(options: {
+  pid: number
+  platform: NodeJS.Platform
+  readDescriptor: (pid: number) => unknown
+  socketExists: (socketPath: string) => boolean
+}): ClaudeInboxReadiness {
+  if (!INBOX_PLATFORMS.has(options.platform)) {
+    return {
+      state: 'unavailable',
+      reason: `Claude Code publishes no inbox socket on ${options.platform}; it exists on macOS and Linux only`,
+    }
+  }
+  let raw: unknown
+  try {
+    raw = options.readDescriptor(options.pid)
+  } catch (err) {
+    return {
+      state: 'unavailable',
+      reason: `no session descriptor for pid ${options.pid} (${err instanceof Error ? err.message : String(err)}); a session started with \`--bare\` binds no inbox socket`,
+    }
+  }
+  const descriptor = parseDescriptor(raw)
+  if (descriptor === null) {
+    return {
+      state: 'unavailable',
+      reason: `the session descriptor for pid ${options.pid} has an unknown shape`,
+    }
+  }
+  if (descriptor.peerProtocol !== CLAUDE_PEER_PROTOCOL) {
+    return {
+      state: 'unavailable',
+      reason: `this session speaks inbox protocol ${descriptor.peerProtocol}, and only ${CLAUDE_PEER_PROTOCOL} is known; refusing to guess at an undocumented wire format`,
+    }
+  }
+  if (!versionAtLeast(descriptor.version, CLAUDE_MIN_INBOX_VERSION)) {
+    return {
+      state: 'unavailable',
+      reason: `Claude Code ${descriptor.version} is older than ${CLAUDE_MIN_INBOX_VERSION}, which is where the inbox socket starts`,
+    }
+  }
+  if (!options.socketExists(descriptor.messagingSocketPath)) {
+    return {
+      state: 'unavailable',
+      reason: `the descriptor names ${descriptor.messagingSocketPath}, but no socket exists there`,
+    }
+  }
+  return {
+    state: 'ready',
+    socketPath: descriptor.messagingSocketPath,
+    version: descriptor.version,
+  }
+}
+
+function socketLine(context: string): string {
+  return `${JSON.stringify({
+    type: 'user',
+    message: { role: 'user', content: context },
+  })}\n`
+}
+
+/**
+ * Claude's own-child delivery route.
+ *
+ * A successful socket write proves delivery to Claude Code, not model
+ * consumption — and this route reports exactly that, no more. It reports
+ * `delivered` all the same, because the write is the strongest acknowledgement
+ * this route can ever obtain: the message it posts starts a brand-new turn
+ * rather than continuing this one, so no later hook will confirm anything about
+ * it. An answer delivered once and settled is strictly better than an answer
+ * redelivered on every turn-end for ever.
+ *
+ * Every path that hands nothing over reports `held`, so the accepted journal
+ * replays it. Unknown state deliberately returns without throwing, so the
+ * journal becomes `hold-for-next-turn` instead of failing the hook.
+ */
+export function claudeWakeRoute(options: {
+  sessionId: string
+  cwd: string
+  sourcePid: number
+  adapters?: ClaudeWakeAdapters
+}): EscalationDeliveryRoute {
+  const adapters = options.adapters ?? systemClaudeWakeAdapters()
+  let sourceDescriptor: ClaudeSessionDescriptor | null = null
+  try {
+    const parsed = parseDescriptor(adapters.readDescriptor(options.sourcePid))
+    if (
+      parsed !== null &&
+      parsed.sessionId === options.sessionId &&
+      parsed.pid === options.sourcePid
+    ) {
+      sourceDescriptor = parsed
+    }
+  } catch {
+    // Delivery fails closed below; route construction must never break the hook.
+  }
+  return {
+    kind: 'inbox-socket',
+    async deliver(event: ContinuationEvent): Promise<DeliveryOutcome> {
+      const observation = await observeClaudeSession(options.sessionId, adapters)
+      if (observation.state === 'unknown') {
+        return {
+          notes: [`holding the accepted answer for the next turn: ${observation.reason}`],
+          log: { route: 'hold-for-next-turn', stage: 'queued', reason: observation.reason },
+          acknowledgement: 'held',
+        }
+      }
+      if (sourceDescriptor === null) {
+        const reason = 'the Stop-hook process cannot prove exact Claude session ownership'
+        return {
+          notes: [`holding the accepted answer for the next turn: ${reason}`],
+          log: { route: 'hold-for-next-turn', stage: 'queued', reason },
+          acknowledgement: 'held',
+        }
+      }
+      if (observation.state === 'stopped') {
+        // Probe immediately before spawn. A prior descriptor or dead socket is
+        // never sufficient: resuming a live session creates a divergent ghost.
+        const confirmed = await observeClaudeSession(options.sessionId, adapters)
+        if (confirmed.state !== 'stopped') {
+          const reason =
+            confirmed.state === 'unknown'
+              ? confirmed.reason
+              : 'the Claude session became live before cold resume'
+          return {
+            notes: [`holding the accepted answer for the next turn: ${reason}`],
+            log: { route: 'hold-for-next-turn', stage: 'queued', reason },
+            acknowledgement: 'held',
+          }
+        }
+        await adapters.resume(options.sessionId, sourceDescriptor.cwd, event.context)
+        return {
+          notes: ['cold-resumed the stopped Claude session with its accepted answer'],
+          log: { route: 'cold-resume', stage: 'delivered' },
+          acknowledgement: 'delivered',
+        }
+      }
+
+      if (
+        observation.descriptor.pid !== options.sourcePid ||
+        sourceDescriptor.startedAt !== observation.descriptor.startedAt
+      ) {
+        const reason = 'the Stop-hook process is not the observed exact Claude session child'
+        return {
+          notes: [`holding the accepted answer for the next turn: ${reason}`],
+          log: { route: 'hold-for-next-turn', stage: 'queued', reason },
+          acknowledgement: 'held',
+        }
+      }
+      await adapters.sendSocket(
+        observation.descriptor.messagingSocketPath,
+        socketLine(event.context),
+      )
+      await adapters.sleep(CLAUDE_POST_SEND_LIVENESS_MS)
+      return {
+        notes: [
+          observation.state === 'live-idle'
+            ? 'posted the accepted answer to the live Claude session'
+            : 'queued the accepted answer for the busy Claude session',
+        ],
+        log: {
+          route: 'inbox-socket',
+          stage: 'delivered',
+          session_state: observation.state,
+        },
+        // The write completed: Claude Code holds the message. Nothing later
+        // reports on it, so this is where the journal settles.
+        acknowledgement: 'delivered',
+      }
+    },
+  }
+}
+
+function runClaude(args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('claude', args, {
+      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+      ...(options.env === undefined ? {} : { env: options.env }),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const stdout: Buffer[] = []
+    const stderr: Buffer[] = []
+    child.stdout?.on('data', (chunk: Buffer | string) => stdout.push(Buffer.from(chunk)))
+    child.stderr?.on('data', (chunk: Buffer | string) => stderr.push(Buffer.from(chunk)))
+    child.once('error', reject)
+    child.once('exit', (code, signal) => {
+      if (code === 0) {
+        resolve(Buffer.concat(stdout).toString())
+        return
+      }
+      reject(
+        new Error(
+          `claude ${args[0] ?? ''} exited ${code === null ? `on ${String(signal)}` : String(code)}: ${Buffer.concat(stderr).toString().trim()}`,
+        ),
+      )
+    })
+  })
+}
+
+function coldResumeEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const next = { ...env }
+  for (const key of Object.keys(next)) {
+    if (key === 'CLAUDECODE' || key === 'CLAUDE_PID' || key.startsWith('CLAUDE_CODE_')) {
+      delete next[key]
+    }
+  }
+  return next
+}
+
+export function systemClaudeWakeAdapters(
+  env: NodeJS.ProcessEnv = process.env,
+): ClaudeWakeAdapters {
+  return {
+    async listAgents() {
+      const output = await runClaude(['agents', '--json'], { env })
+      return JSON.parse(output) as unknown
+    },
+    readDescriptor(pid) {
+      const file = path.join(os.homedir(), '.claude', 'sessions', `${pid}.json`)
+      return JSON.parse(readFileSync(file, 'utf8')) as unknown
+    },
+    sendSocket(socketPath, line) {
+      return new Promise<void>((resolve, reject) => {
+        const socket = createConnection(socketPath)
+        let settled = false
+        const fail = (err: Error): void => {
+          if (settled) return
+          settled = true
+          socket.destroy()
+          reject(err)
+        }
+        socket.once('error', fail)
+        socket.once('connect', () => {
+          socket.end(line, () => {
+            if (settled) return
+            settled = true
+            resolve()
+          })
+        })
+      })
+    },
+    async resume(sessionId, cwd, context) {
+      if (!existsSync(cwd)) throw new Error(`Claude session cwd no longer exists: ${cwd}`)
+      await runClaude(
+        [
+          '-p',
+          '--resume',
+          sessionId,
+          '--output-format',
+          'json',
+          context,
+        ],
+        { cwd, env: coldResumeEnvironment(env) },
+      )
+    },
+    sleep(milliseconds) {
+      return new Promise((resolve) => setTimeout(resolve, milliseconds))
+    },
+  }
+}

package/src/client.test.ts

@@ -51,6 +51,18 @@ describe('a server that never answers', () => {
     await expect(client.listDevices()).rejects.toThrow(/did not respond within/)
   })
 
+  it('clamps a late request to the caller whole-operation deadline', async () => {
+    const baseUrl = await serving(() => {})
+    const started = Date.now()
+    const client = createClient(baseUrl, null, {
+      timeoutMs: 5_000,
+      deadlineAt: started + 200,
+    })
+
+    await expect(client.listDevices()).rejects.toBeInstanceOf(NetworkError)
+    expect(Date.now() - started).toBeLessThan(2_000)
+  })
+
   it('allows for the long poll it asked the server to hold', async () => {
     // The deadline is per request, so a 25s long poll must not be cut off by
     // the ordinary budget — otherwise waiting for a reply could never work.

package/src/client.ts

@@ -13,6 +13,7 @@ import type {
   SubmissionReceipt,
   SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
+import type { Logger } from './logging.js'
 
 export class ApiCallError extends Error {
   constructor(
@@ -28,6 +29,18 @@ export class ApiCallError extends Error {
 
 export class NetworkError extends Error {}
 
+/**
+ * Whether a replies-poll failure is temporary while the durable request stays
+ * live. Transport faults, throttling, request timeouts, and server failures
+ * can recover on a later poll; client errors cannot be repaired by retrying
+ * the same authenticated request.
+ */
+export function isRetryableReplyPollError(err: unknown): boolean {
+  if (err instanceof NetworkError) return true
+  if (!(err instanceof ApiCallError)) return false
+  return err.status >= 500 || err.status === 429 || err.status === 408
+}
+
 /**
  * A deadline that fired reads as an abort, which says nothing useful on its
  * own. Naming the timeout is what lets someone tell a hung server apart from a
@@ -57,8 +70,8 @@ export interface ApiClient {
     requestId: string,
     options: { waitSeconds: number; afterSeq: number },
   ): Promise<ListRepliesResponse>
-  /** Retire a question so a late device answer is rejected rather than lost. */
-  closeReplies(requestId: string): Promise<void>
+  /** Retire a question and return the replies committed before the close fence. */
+  closeReplies(requestId: string): Promise<ListRepliesResponse>
   createMediaUpload(body: CreateMediaUploadRequestT): Promise<CreateMediaUploadResponse>
   uploadMedia(grant: CreateMediaUploadResponse, bytes: Uint8Array): Promise<void>
   health(): Promise<boolean>
@@ -71,6 +84,21 @@ export interface ClientOptions {
    * whole network path stays inside the budget the harness allows them.
    */
   timeoutMs?: number
+  /**
+   * Absolute wall-clock ceiling for the caller's whole operation. This is
+   * intentionally separate from `timeoutMs`: a late long poll must not get a
+   * fresh per-request allowance after its owning harness hook is nearly done.
+   */
+  deadlineAt?: number
+  /** Test seam for `deadlineAt`; production uses the wall clock. */
+  now?: () => number
+  /**
+   * Records each call locally. Worth having because the two failures that cost
+   * the most time — a server older than this CLI, and a network path that only
+   * fails inside a hook — both look identical from outside and are told apart
+   * instantly by a status code and a duration.
+   */
+  logger?: Pick<Logger, 'debug' | 'error'>
 }
 
 /** Generous enough for a slow link, short enough that nothing hangs for ever. */
@@ -83,6 +111,8 @@ export function createClient(
 ): ApiClient {
   const root = baseUrl.replace(/\/$/, '')
   const budgetMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const now = options.now ?? Date.now
+  const logger = options.logger
 
   async function call<T>(
     method: string,
@@ -90,12 +120,47 @@ export function createClient(
     body?: unknown,
     /** Seconds the server was asked to hold the connection open. */
     serverWaitSeconds = 0,
+  ): Promise<T> {
+    const startedAt = Date.now()
+    try {
+      const result = await callOnce<T>(method, apiPath, body, serverWaitSeconds)
+      logger?.debug('http.call', {
+        method,
+        path: apiPath,
+        ok: true,
+        duration_ms: Date.now() - startedAt,
+      })
+      return result
+    } catch (err) {
+      logger?.error('http.call', {
+        method,
+        path: apiPath,
+        ok: false,
+        duration_ms: Date.now() - startedAt,
+        ...(err instanceof ApiCallError
+          ? { status: err.status, code: err.code, message: err.message, details: err.details }
+          : { message: String(err) }),
+      })
+      throw err
+    }
+  }
+
+  async function callOnce<T>(
+    method: string,
+    apiPath: string,
+    body?: unknown,
+    serverWaitSeconds = 0,
   ): Promise<T> {
     // Without this, a server that accepts the connection and then never answers
     // hangs until the harness kills the whole hook — and the reply-poll deadline
     // cannot interrupt an individual fetch. The signal covers the
     // body read too, not just the response headers.
-    const limitMs = budgetMs + serverWaitSeconds * 1000
+    const requestBudgetMs = budgetMs + serverWaitSeconds * 1000
+    const remainingMs =
+      options.deadlineAt === undefined
+        ? requestBudgetMs
+        : Math.max(1, options.deadlineAt - now())
+    const limitMs = Math.max(1, Math.min(requestBudgetMs, remainingMs))
     const signal = AbortSignal.timeout(limitMs)
     let response: Response
     try {
@@ -154,7 +219,10 @@ export function createClient(
         waitSeconds,
       ),
     closeReplies: (requestId) =>
-      call('POST', `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`),
+      call<ListRepliesResponse>(
+        'POST',
+        `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`,
+      ),
     createMediaUpload: (body) => call('POST', '/api/v1/media', body),
     uploadMedia: async (grant, bytes) => {
       let response: Response