@raidiant/notifai 10.1.0 → 10.1.2

package/src/client.ts

@@ -1,345 +0,0 @@
-import type {
-  ApiErrorBody,
-  AccountAccessResponse,
-  BeginPairingResponse,
-  CapabilityDocument,
-  CreateMediaUploadRequestT,
-  CreateMediaUploadResponse,
-  FinalizeMediaUploadResponse,
-  EvidenceSnapshot,
-  GetAgentAcknowledgementResponse,
-  ListDevicesResponse,
-  ListSoundsResponse,
-  ClientCapability,
-  CompatibilityResponse,
-  RecoveryAction,
-  ListRepliesResponse,
-  Platform,
-  PollPairingResponse,
-  PutAgentAcknowledgementRequestT,
-  PutAgentAcknowledgementResponse,
-  PutAgentSessionLabelRequestT,
-  AgentSessionView,
-  SubmissionReceipt,
-  SubmitNotificationRequestT,
-} from '@raidiant/notifai-protocol'
-import {
-  CAPABILITIES_HEADER,
-  CLI_VERSION_HEADER,
-} from '@raidiant/notifai-protocol'
-import type { Logger } from './logging.js'
-
-export class ApiCallError extends Error {
-  constructor(
-    public status: number,
-    public code: string,
-    message: string,
-    public nextAction: string | null = null,
-    public details: unknown = null,
-    public recoveryAction: RecoveryAction | null = null,
-  ) {
-    super(message)
-  }
-}
-
-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
- * refused connection.
- */
-function networkFailure(err: unknown, root: string, limitMs: number): NetworkError {
-  const name = err instanceof Error ? err.name : ''
-  if (name === 'TimeoutError' || name === 'AbortError') {
-    return new NetworkError(`${root} did not respond within ${Math.round(limitMs / 1000)}s`)
-  }
-  return new NetworkError(`Could not reach ${root}: ${String(err)}`)
-}
-
-export interface ApiClient {
-  beginPairing(body: {
-    machine_name: string
-    credential_hash: string
-    poll_verifier_hash: string
-    confirmation_hash: string
-  }): Promise<BeginPairingResponse>
-  pollPairing(pairingId: string, pollVerifier: string): Promise<PollPairingResponse>
-  accessStatus(): Promise<AccountAccessResponse>
-  listDevices(): Promise<ListDevicesResponse>
-  listSounds(): Promise<ListSoundsResponse>
-  capabilities(
-    platform?: Platform,
-    appVersion?: string,
-    appBuild?: string,
-  ): Promise<CapabilityDocument>
-  compatibility(): Promise<CompatibilityResponse>
-  submit(body: SubmitNotificationRequestT, waitSeconds: number): Promise<SubmissionReceipt>
-  evidence(requestId: string): Promise<EvidenceSnapshot>
-  replies(
-    requestId: string,
-    options: { waitSeconds: number; afterSeq: number },
-  ): Promise<ListRepliesResponse>
-  /** Retire a question and return the replies committed before the close fence. */
-  closeReplies(requestId: string): Promise<ListRepliesResponse>
-  putAgentAcknowledgement(
-    requestId: string,
-    body: PutAgentAcknowledgementRequestT,
-  ): Promise<PutAgentAcknowledgementResponse>
-  putAgentSessionLabel(body: PutAgentSessionLabelRequestT): Promise<AgentSessionView>
-  agentAcknowledgement(
-    requestId: string,
-    options: { waitSeconds: number },
-  ): Promise<GetAgentAcknowledgementResponse>
-  createMediaUpload(body: CreateMediaUploadRequestT): Promise<CreateMediaUploadResponse>
-  finalizeMediaUpload(mediaId: string): Promise<FinalizeMediaUploadResponse>
-  uploadMedia(grant: CreateMediaUploadResponse, bytes: Uint8Array): Promise<void>
-  health(): Promise<boolean>
-}
-
-export interface ClientOptions {
-  /**
-   * Ceiling for a single request, on top of any long poll the server has been
-   * asked to hold. Callers running inside a harness hook shrink this so their
-   * 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'>
-  /** Artifact identity and named jobs advertised only on authenticated traffic. */
-  cliVersion?: string | null
-  capabilities?: readonly ClientCapability[]
-}
-
-/** Generous enough for a slow link, short enough that nothing hangs for ever. */
-const DEFAULT_TIMEOUT_MS = 20_000
-
-export function createClient(
-  baseUrl: string,
-  bearer: string | null,
-  options: ClientOptions = {},
-): ApiClient {
-  const root = baseUrl.replace(/\/$/, '')
-  const budgetMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
-  const now = options.now ?? Date.now
-  const logger = options.logger
-  const clientHeaders: Record<string, string> = bearer
-    ? {
-        ...(options.cliVersion ? { [CLI_VERSION_HEADER]: options.cliVersion } : {}),
-        ...(options.capabilities
-          ? { [CAPABILITIES_HEADER]: options.capabilities.join(',') }
-          : {}),
-      }
-    : {}
-
-  async function call<T>(
-    method: string,
-    apiPath: string,
-    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 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 {
-      response = await fetch(`${root}${apiPath}`, {
-        method,
-        headers: {
-          ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
-          ...(bearer ? { authorization: bearer } : {}),
-          ...clientHeaders,
-        },
-        signal,
-        ...(bearer ? { redirect: 'error' as const } : {}),
-        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-      })
-    } catch (err) {
-      throw networkFailure(err, root, limitMs)
-    }
-    if (!response.ok) {
-      let parsed: ApiErrorBody | null = null
-      try {
-        parsed = (await response.json()) as ApiErrorBody
-      } catch {
-        // non-JSON body
-      }
-      throw new ApiCallError(
-        response.status,
-        parsed?.error.code ?? 'internal_error',
-        parsed?.error.message ?? `Request failed with status ${response.status}`,
-        parsed?.error.next_action ?? null,
-        parsed?.error.details ?? null,
-        parsed?.error.recovery_action ?? null,
-      )
-    }
-    if (response.status === 204) return undefined as T
-    try {
-      return (await response.json()) as T
-    } catch (err) {
-      // A truncated or abandoned body is a transport failure, not a protocol
-      // one: it must be retryable like any other, not surface as a raw abort.
-      throw networkFailure(err, root, limitMs)
-    }
-  }
-
-  return {
-    beginPairing: (body) => call('POST', '/api/v1/pairings', body),
-    pollPairing: (pairingId, pollVerifier) =>
-      call('POST', `/api/v1/pairings/${encodeURIComponent(pairingId)}/poll`, {
-        poll_verifier: pollVerifier,
-      }),
-    accessStatus: () => call('GET', '/api/v1/account/access'),
-    listDevices: () => call('GET', '/api/v1/devices'),
-    listSounds: () => call('GET', '/api/v1/sounds'),
-    capabilities: (platform = 'ios', appVersion, appBuild) => {
-      const query = new URLSearchParams()
-      if (appVersion !== undefined) query.set('app_version', appVersion)
-      if (appBuild !== undefined) query.set('app_build', appBuild)
-      const suffix = query.size > 0 ? `?${query.toString()}` : ''
-      return call('GET', `/api/v1/capabilities/${encodeURIComponent(platform)}${suffix}`)
-    },
-    compatibility: () => call('GET', '/api/v1/compatibility'),
-    submit: (body, waitSeconds) =>
-      call('POST', `/api/v1/notifications?wait_seconds=${waitSeconds}`, body, waitSeconds),
-    evidence: (requestId) => call('GET', `/api/v1/notifications/${encodeURIComponent(requestId)}`),
-    replies: (requestId, { waitSeconds, afterSeq }) =>
-      call(
-        'GET',
-        `/api/v1/notifications/${encodeURIComponent(requestId)}/replies?wait_seconds=${waitSeconds}&after_seq=${afterSeq}`,
-        undefined,
-        waitSeconds,
-      ),
-    closeReplies: (requestId) =>
-      call<ListRepliesResponse>(
-        'POST',
-        `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`,
-      ),
-    putAgentAcknowledgement: (requestId, body) =>
-      call<PutAgentAcknowledgementResponse>(
-        'PUT',
-        `/api/v1/notifications/${encodeURIComponent(requestId)}/agent-acknowledgement`,
-        body,
-      ),
-    putAgentSessionLabel: (body) =>
-      call<AgentSessionView>('PUT', '/api/v1/agent-sessions/label', body),
-    agentAcknowledgement: (requestId, { waitSeconds }) =>
-      call<GetAgentAcknowledgementResponse>(
-        'GET',
-        `/api/v1/notifications/${encodeURIComponent(requestId)}/agent-acknowledgement?wait_seconds=${waitSeconds}`,
-        undefined,
-        waitSeconds,
-      ),
-    createMediaUpload: (body) => call('POST', '/api/v1/media', body),
-    // Storage-observed bytes become authoritative before a send can reference
-    // the upload; the caller's declared size is only a request.
-    finalizeMediaUpload: (mediaId) =>
-      call('POST', `/api/v1/media/${encodeURIComponent(mediaId)}/finalize`),
-    uploadMedia: async (grant, bytes) => {
-      let response: Response
-      try {
-        response = await fetch(grant.upload_url, {
-          method: 'PUT',
-          headers: grant.upload_headers,
-          body: bytes,
-          // Media can be large, so this gets its own allowance rather than the
-          // per-request budget — but still a finite one.
-          signal: AbortSignal.timeout(Math.max(budgetMs, 60_000)),
-          // The grant names one exact destination and carries signed headers.
-          // A redirect would replay both against an origin the server never
-          // granted, so it is refused rather than followed.
-          redirect: 'manual',
-        })
-      } catch (err) {
-        throw new NetworkError(`Upload failed: ${String(err)}`)
-      }
-      if (response.status >= 300 && response.status < 400) {
-        throw new NetworkError(
-          `Upload redirect is refused, not followed: the grant's headers are signed for one exact destination`,
-        )
-      }
-      if (!response.ok) {
-        throw new NetworkError(`Upload rejected with status ${response.status}`)
-      }
-      // A successful storage PUT is not authorization to reference the media.
-      // The idempotent finalize call makes the server inspect provider metadata
-      // and commit authoritative quota before the command can use media_id.
-      await call<FinalizeMediaUploadResponse>(
-        'POST',
-        `/api/v1/media/${encodeURIComponent(grant.media_id)}/finalize`,
-      )
-    },
-    health: async () => {
-      try {
-        await call('GET', '/healthz')
-        return true
-      } catch {
-        return false
-      }
-    },
-  }
-}

package/src/codex-wake.test.ts

@@ -1,254 +0,0 @@
-import { closeSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { afterAll, describe, expect, it, vi } from 'vitest'
-import {
-  CODEX_THREAD_LOCK_DIR,
-  codexThreadLockPath,
-  codexWakeRoute,
-  observeCodexThread,
-  systemCodexWakeAdapters,
-  type CodexWakeAdapters,
-  type CodexWakeObservation,
-} from './codex-wake.js'
-
-const THREAD_ID = '019ff69d-a07f-7161-ab6e-bd06b3b93c8e'
-
-const event = {
-  context:
-    'Notifai — question_id rollout-option, question "Which rollout option?"; the user answered "BETA".',
-  answers: 1,
-  remaining: 0,
-  request_ids: ['req_test'],
-  journal_recorded_at: 1_800_000_000_000,
-  commitDelivery: () => true,
-}
-
-const temporaries: string[] = []
-
-function codexHome(): string {
-  const home = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-wake-'))
-  temporaries.push(home)
-  mkdirSync(path.join(home, CODEX_THREAD_LOCK_DIR), { recursive: true })
-  return home
-}
-
-afterAll(() => {
-  for (const directory of temporaries) rmSync(directory, { recursive: true, force: true })
-})
-
-function adapters(
-  options: {
-    sourceAlive?: boolean
-    probes?: CodexWakeObservation[]
-    probe?: CodexWakeObservation
-  } = {},
-): CodexWakeAdapters & { resumed: Array<{ threadId: string; cwd: string; context: string }>; probed: string[] } {
-  const resumed: Array<{ threadId: string; cwd: string; context: string }> = []
-  const probed: string[] = []
-  const sequence = [...(options.probes ?? [])]
-  return {
-    resumed,
-    probed,
-    probeThreadWriter(lockPath) {
-      probed.push(lockPath)
-      return sequence.shift() ?? options.probe ?? { state: 'stopped' }
-    },
-    sourceAlive() {
-      return options.sourceAlive ?? false
-    },
-    async resume(threadId, cwd, context) {
-      resumed.push({ threadId, cwd, context })
-    },
-  }
-}
-
-function route(
-  wake: CodexWakeAdapters,
-  overrides: { threadId?: string; env?: NodeJS.ProcessEnv } = {},
-): ReturnType<typeof codexWakeRoute> {
-  return codexWakeRoute({
-    threadId: overrides.threadId ?? THREAD_ID,
-    cwd: '/tmp/notifai-codex-wake',
-    sourcePid: 4242,
-    env: overrides.env ?? { CODEX_HOME: '/tmp/notifai-codex-home' },
-    adapters: wake,
-  })
-}
-
-describe('Codex thread ownership', () => {
-  it('names the lock file Codex itself keys by thread id', () => {
-    expect(codexThreadLockPath(THREAD_ID, { CODEX_HOME: '/tmp/cx' })).toBe(
-      `/tmp/cx/${CODEX_THREAD_LOCK_DIR}/${THREAD_ID}.lock`,
-    )
-  })
-
-  it('refuses to derive a lock path from a session id that is not a thread id', () => {
-    const wake = adapters()
-
-    expect(observeCodexThread('../../etc/passwd', {}, wake)).toEqual({
-      state: 'unknown',
-      reason: 'the Codex session id is not a thread id',
-    })
-    expect(wake.probed).toEqual([])
-  })
-
-  it('reports a probe that throws as unknown rather than as an unowned thread', () => {
-    const observation = observeCodexThread(THREAD_ID, { CODEX_HOME: '/tmp/cx' }, {
-      probeThreadWriter() {
-        throw new Error('permission denied')
-      },
-    })
-
-    expect(observation).toEqual({
-      state: 'unknown',
-      reason: 'Codex thread-writer lock probe failed: permission denied',
-    })
-  })
-})
-
-describe('Codex writer-lock probe', () => {
-  const platform = process.platform
-  const supported = platform === 'darwin' || platform === 'freebsd' || platform === 'openbsd'
-
-  it.runIf(supported)('reads a kernel-held lock as a live writer and its release as stopped', () => {
-    const home = codexHome()
-    const lock = codexThreadLockPath(THREAD_ID, { CODEX_HOME: home })
-    writeFileSync(lock, '')
-    const probe = systemCodexWakeAdapters({ CODEX_HOME: home }).probeThreadWriter
-
-    // flock is held per open file description, so this process contends with
-    // itself exactly as a separate Codex process would.
-    const held = openSync(lock, 0x20 | 0x4)
-    try {
-      expect(probe(lock)).toEqual({ state: 'live' })
-    } finally {
-      closeSync(held)
-    }
-
-    expect(probe(lock)).toEqual({ state: 'stopped' })
-  })
-
-  it.runIf(supported)('treats a swept lock file inside a real lock directory as stopped', () => {
-    const home = codexHome()
-    const probe = systemCodexWakeAdapters({ CODEX_HOME: home }).probeThreadWriter
-
-    expect(probe(codexThreadLockPath(THREAD_ID, { CODEX_HOME: home }))).toEqual({
-      state: 'stopped',
-    })
-  })
-
-  it.runIf(supported)('never claims a thread is unowned when there is no lock directory', () => {
-    const home = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-nohome-'))
-    temporaries.push(home)
-    const probe = systemCodexWakeAdapters({ CODEX_HOME: home }).probeThreadWriter
-    const lock = codexThreadLockPath(THREAD_ID, { CODEX_HOME: home })
-
-    expect(probe(lock)).toMatchObject({ state: 'unknown' })
-  })
-
-  it.runIf(!supported)('fails closed where no non-blocking lock probe exists', () => {
-    const probe = systemCodexWakeAdapters({ CODEX_HOME: '/tmp/cx' }).probeThreadWriter
-
-    expect(probe(`/tmp/cx/${CODEX_THREAD_LOCK_DIR}/${THREAD_ID}.lock`)).toMatchObject({
-      state: 'unknown',
-    })
-  })
-})
-
-describe('Codex wake delivery', () => {
-  it('continues the live session through its own Stop hook without probing anything', async () => {
-    const wake = adapters({ sourceAlive: true })
-
-    const outcome = await route(wake).deliver(event)
-
-    expect(JSON.parse(outcome.stdout!)).toEqual({ decision: 'block', reason: event.context })
-    expect(wake.probed).toEqual([])
-    expect(wake.resumed).toEqual([])
-  })
-
-  it('cold-resumes a stopped thread only after two probes both find no writer', async () => {
-    const wake = adapters({ probes: [{ state: 'stopped' }, { state: 'stopped' }] })
-
-    const outcome = await route(wake).deliver(event)
-
-    expect(wake.probed).toEqual([
-      `/tmp/notifai-codex-home/${CODEX_THREAD_LOCK_DIR}/${THREAD_ID}.lock`,
-      `/tmp/notifai-codex-home/${CODEX_THREAD_LOCK_DIR}/${THREAD_ID}.lock`,
-    ])
-    expect(wake.resumed).toEqual([
-      { threadId: THREAD_ID, cwd: '/tmp/notifai-codex-wake', context: event.context },
-    ])
-    expect(outcome.stdout).toBeUndefined()
-    expect(outcome.log).toEqual({ route: 'cold-resume', stage: 'delivered' })
-  })
-
-  it('never resumes a thread a live writer owns', async () => {
-    const wake = adapters({ probe: { state: 'live' } })
-
-    const outcome = await route(wake).deliver(event)
-
-    expect(wake.resumed).toEqual([])
-    expect(outcome.stdout).toBeUndefined()
-    expect(outcome.log).toEqual({
-      route: 'hold-for-next-turn',
-      stage: 'queued',
-      reason: 'a live writer owns the Codex thread and this hook can no longer continue it',
-    })
-    expect(outcome.notes.join('\n')).toContain('holding the accepted answer for the next turn')
-  })
-
-  it('never resumes a thread whose writer took the lock between the two probes', async () => {
-    const wake = adapters({ probes: [{ state: 'stopped' }, { state: 'live' }] })
-
-    const outcome = await route(wake).deliver(event)
-
-    expect(wake.probed).toHaveLength(2)
-    expect(wake.resumed).toEqual([])
-    expect(outcome.log).toMatchObject({ route: 'hold-for-next-turn', stage: 'queued' })
-  })
-
-  it('journals the answer when ownership cannot be probed at all', async () => {
-    const wake = adapters({ probe: { state: 'unknown', reason: 'no lock directory' } })
-
-    const outcome = await route(wake).deliver(event)
-
-    expect(wake.resumed).toEqual([])
-    expect(outcome.log).toEqual({
-      route: 'hold-for-next-turn',
-      stage: 'queued',
-      reason: 'no lock directory',
-    })
-  })
-
-  it('journals the answer when the session id cannot name a thread lock', async () => {
-    const wake = adapters()
-
-    const outcome = await route(wake, { threadId: 'codex-session-7' }).deliver(event)
-
-    expect(wake.probed).toEqual([])
-    expect(wake.resumed).toEqual([])
-    expect(outcome.log).toMatchObject({
-      route: 'hold-for-next-turn',
-      reason: 'the Codex session id is not a thread id',
-    })
-  })
-
-  it('does not report delivery when the cold resume fails', async () => {
-    const wake = adapters()
-    wake.resume = vi.fn(async () => {
-      throw new Error('codex exec exited 1')
-    })
-
-    await expect(route(wake).deliver(event)).rejects.toThrow('codex exec exited 1')
-  })
-})
-
-describe('Codex system adapters', () => {
-  it('reads this process as a live source and PID 0 as no source at all', () => {
-    const wake = systemCodexWakeAdapters({})
-
-    expect(wake.sourceAlive(process.pid)).toBe(true)
-    expect(wake.sourceAlive(0)).toBe(false)
-  })
-})