@raidiant/notifai 5.0.0 → 6.0.0

package/src/commands-io.ts

@@ -0,0 +1,108 @@
+import { openUrl } from './platform.js'
+import type { CommandIo } from './commands-core.js'
+
+// ---------------------------------------------------------------------------
+// production IO
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether a human is driving this terminal.
+ *
+ * A TTY alone is NOT that evidence: agent harnesses frequently allocate a PTY
+ * for the commands they run, and a prompt shown to an agent does not fail — it
+ * hangs, because every prompt library waits on stdin rather than erroring. So
+ * this also honours `CI` and an explicit `NOTIFAI_NO_INPUT=1` escape hatch,
+ * and every interactive affordance stays strictly optional: anything `init`
+ * can ask, a flag can answer.
+ */
+function isHumanTerminal(env: NodeJS.ProcessEnv): boolean {
+  return (
+    process.stdin.isTTY === true &&
+    process.stdout.isTTY === true &&
+    (env['CI'] ?? '') === '' &&
+    (env['NOTIFAI_NO_INPUT'] ?? '') === ''
+  )
+}
+
+/**
+ * Lazy on purpose: the hook path runs in front of every prompt the user types,
+ * and must not pay for a prompt library it will never show.
+ */
+async function clack() {
+  return await import('@clack/prompts')
+}
+
+export function realIo(env: NodeJS.ProcessEnv = process.env): CommandIo {
+  const interactive = () => isHumanTerminal(env)
+  return {
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+    get interactive() {
+      return interactive()
+    },
+    confirm: async (question, fallback = false) => {
+      if (!interactive()) return fallback
+      const p = await clack()
+      const answer = await p.confirm({ message: question, initialValue: fallback })
+      // Ctrl-C mid-prompt arrives as a cancel symbol, not a SIGINT; treat it
+      // as the safe answer rather than letting a Symbol escape into logic.
+      return p.isCancel(answer) ? false : answer
+    },
+    select: async (message, options) => {
+      if (!interactive()) return null
+      const p = await clack()
+      const answer = await p.select({ message, options })
+      return p.isCancel(answer) ? null : (answer as string)
+    },
+    multiselect: async (message, options, initial) => {
+      if (!interactive()) return null
+      const p = await clack()
+      const answer = await p.multiselect({
+        message,
+        options,
+        required: true,
+        ...(initial !== undefined && initial.length > 0 ? { initialValues: initial } : {}),
+      })
+      return p.isCancel(answer) ? null : (answer as string[])
+    },
+    intro: async (title) => {
+      if (!interactive()) return
+      ;(await clack()).intro(title)
+    },
+    outro: async (message) => {
+      if (!interactive()) return
+      ;(await clack()).outro(message)
+    },
+    note: async (message, title) => {
+      if (!interactive()) return
+      ;(await clack()).note(message, title)
+    },
+    spinner: async (message) => {
+      if (!interactive()) return null
+      const progress = (await clack()).spinner()
+      progress.start(message)
+      return {
+        message: (next) => progress.message(next),
+        stop: (next) => progress.stop(next),
+        error: (next) => progress.error(next),
+      }
+    },
+    check: async (ok, message, tone) => {
+      if (!interactive()) return
+      const { log } = await clack()
+      switch (tone ?? (ok ? 'ok' : 'bad')) {
+        case 'ok':
+          return log.success(message)
+        case 'warn':
+          return log.warn(message)
+        case 'pending':
+          // Never checked. `log.info` reads as neutral, which is the honest
+          // rendering for a state no evidence was gathered about.
+          return log.info(message)
+        case 'bad':
+          return log.error(message)
+      }
+    },
+    openUrl,
+  }
+}

package/src/commands-logs.ts

@@ -0,0 +1,243 @@
+import { unlinkSync } from 'node:fs'
+import { type LogLevel } from './config.js'
+import {
+  LOG_EVENTS,
+  RECORD_LEVELS,
+  activeLogPath,
+  archiveLogPaths,
+  logsDiskUsage,
+  readLogRecords,
+  renderRecord,
+  type LogQuery,
+} from './logging.js'
+import { EXIT, loadLoggedConfig, type CommandDeps } from './commands-core.js'
+
+// ---------------------------------------------------------------------------
+// logs
+// ---------------------------------------------------------------------------
+
+export interface LogsFlags {
+  json?: boolean
+  limit?: number
+  all?: boolean
+  since?: string
+  level?: string
+  event?: string[]
+  run?: string
+  request?: string
+  session?: string
+  project?: string
+  allProjects?: boolean
+  grep?: string
+  path?: boolean
+  clear?: boolean
+}
+
+const LOG_RECORD_OPTIONS: readonly (readonly [keyof LogsFlags, string])[] = [
+  ['limit', '--limit'],
+  ['all', '--all'],
+  ['since', '--since'],
+  ['level', '--level'],
+  ['event', '--event'],
+  ['run', '--run'],
+  ['request', '--request'],
+  ['session', '--session'],
+  ['project', '--project'],
+  ['allProjects', '--all-projects'],
+  ['grep', '--grep'],
+]
+
+/**
+ * Deliberately small. The reader is usually a model with a finite context, and
+ * a log command whose default answer is ten thousand lines gets used once.
+ * Everything beyond this is reachable by asking for it.
+ */
+const DEFAULT_LOG_LIMIT = 30
+/** Even `--all` stops somewhere; an unbounded dump is never the useful answer. */
+const MAX_LOG_LIMIT = 2_000
+
+/** `10m`, `2h`, `1d`, or an ISO 8601 instant. */
+export function parseSince(raw: string, now: number): number | null {
+  const relative = /^(\d+)([smhd])$/.exec(raw.trim())
+  if (relative !== null) {
+    const amount = Number(relative[1])
+    const unit = relative[2] as 's' | 'm' | 'h' | 'd'
+    const seconds = { s: 1, m: 60, h: 3600, d: 86400 }[unit]
+    return now - amount * seconds * 1000
+  }
+  const absolute = Date.parse(raw)
+  return Number.isNaN(absolute) ? null : absolute
+}
+
+/**
+ * What this machine recorded about itself.
+ *
+ * The retrieval half of the local log, and the half that decides whether the
+ * log is worth having. Three things make it usable by an agent rather than
+ * merely available to one: the default is bounded and scoped to this project,
+ * the filters match the questions actually asked ("that run", "that
+ * notification", "just the failures"), and `--json` gives the machine the
+ * records untouched on stdout while every word of explanation goes to stderr.
+ */
+export function logsCommand(deps: CommandDeps, flags: LogsFlags): number {
+  const selectedRetrievalOptions = LOG_RECORD_OPTIONS
+    .filter(([key]) => {
+      const value = flags[key]
+      return Array.isArray(value) ? value.length > 0 : value !== undefined && value !== false
+    })
+    .map(([, name]) => name)
+
+  if (flags.path === true && flags.clear === true) {
+    deps.io.err('Pass --path or --clear, not both.')
+    return EXIT.usage
+  }
+  if (flags.path === true && selectedRetrievalOptions.length > 0) {
+    deps.io.err(`--path cannot be combined with record options: ${selectedRetrievalOptions.join(', ')}.`)
+    return EXIT.usage
+  }
+  if (flags.clear === true && selectedRetrievalOptions.length > 0) {
+    deps.io.err(`--clear cannot be combined with record options: ${selectedRetrievalOptions.join(', ')}.`)
+    return EXIT.usage
+  }
+  if (flags.project !== undefined && flags.allProjects === true) {
+    deps.io.err('Pass --project or --all-projects, not both.')
+    return EXIT.usage
+  }
+  if (flags.limit !== undefined && flags.all === true) {
+    deps.io.err('Pass --limit or --all, not both.')
+    return EXIT.usage
+  }
+  if (flags.limit !== undefined && (!Number.isInteger(flags.limit) || flags.limit <= 0)) {
+    deps.io.err('--limit must be a positive integer.')
+    return EXIT.usage
+  }
+  if (flags.limit !== undefined && flags.limit > MAX_LOG_LIMIT) {
+    deps.io.err(`--limit cannot exceed ${MAX_LOG_LIMIT}; narrow the result with --since or filters.`)
+    return EXIT.usage
+  }
+
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const now = (deps.now ?? Date.now)()
+
+  if (flags.path === true) {
+    const usage = logsDiskUsage(deps.env)
+    const archives = archiveLogPaths(deps.env)
+    if (flags.json === true) {
+      deps.io.out(
+        JSON.stringify(
+          {
+            active: activeLogPath(deps.env),
+            archives,
+            files: usage.files,
+            bytes: usage.bytes,
+            level: config.log_level.value,
+            max_bytes: config.log_max_bytes.value,
+            max_files: config.log_max_files.value,
+            local_only: true,
+          },
+          null,
+          2,
+        ),
+      )
+      return EXIT.ok
+    }
+    deps.io.out(activeLogPath(deps.env))
+    for (const archive of archives) deps.io.out(archive)
+    deps.io.err(
+      `${usage.files} file(s), ${Math.round(usage.bytes / 1024)} KB, level ${config.log_level.value}. These stay on this machine.`,
+    )
+    return EXIT.ok
+  }
+
+  if (flags.clear === true) {
+    let removed = 0
+    for (const file of [activeLogPath(deps.env), ...archiveLogPaths(deps.env)]) {
+      try {
+        unlinkSync(file)
+        removed += 1
+      } catch {
+        // Absent, or not ours to remove; either way there is nothing to report.
+      }
+    }
+    deps.io.out(
+      flags.json === true
+        ? JSON.stringify({ cleared_files: removed })
+        : `Cleared ${removed} log file${removed === 1 ? '' : 's'}.`,
+    )
+    return EXIT.ok
+  }
+
+  const query: LogQuery = {
+    limit: flags.limit ?? (flags.all === true ? MAX_LOG_LIMIT : DEFAULT_LOG_LIMIT),
+  }
+
+  if (flags.since !== undefined) {
+    const since = parseSince(flags.since, now)
+    if (since === null) {
+      deps.io.err(`Could not read "${flags.since}" as a time. Use 10m, 2h, 1d, or an ISO 8601 instant.`)
+      return EXIT.usage
+    }
+    query.since = since
+  }
+  if (flags.level !== undefined) {
+    if (!(RECORD_LEVELS as readonly string[]).includes(flags.level)) {
+      deps.io.err(`--level takes one of: ${RECORD_LEVELS.join(', ')} — not "${flags.level}".`)
+      return EXIT.usage
+    }
+    query.level = flags.level as LogLevel
+  }
+  if (flags.event !== undefined && flags.event.length > 0) {
+    const unknown = flags.event.filter((name) => !(LOG_EVENTS as readonly string[]).includes(name))
+    if (unknown.length > 0) {
+      deps.io.err(`Unknown event ${unknown.join(', ')}. Valid: ${LOG_EVENTS.join(', ')}`)
+      return EXIT.usage
+    }
+    query.event = flags.event
+  }
+  if (flags.run !== undefined) query.run = flags.run
+  if (flags.session !== undefined) query.session = flags.session
+  if (flags.request !== undefined) query.request = flags.request
+  if (flags.grep !== undefined) query.contains = flags.grep
+
+  // Scoped to this project by default. A machine commonly runs several agents
+  // in several worktrees at once, and the answer to "what just happened" is
+  // useless if three other projects are interleaved through it.
+  const scope =
+    flags.project ?? (flags.allProjects === true ? undefined : (config.project.value ?? undefined))
+  if (scope !== undefined) query.project = scope
+
+  const result = readLogRecords(deps.env, query)
+
+  if (flags.json === true) {
+    for (const record of result.records) deps.io.out(JSON.stringify(record))
+  } else {
+    for (const record of result.records) deps.io.out(renderRecord(record))
+  }
+
+  if (result.records.length === 0) {
+    if (config.log_level.value === 'off') {
+      deps.io.err('Nothing is being recorded: log_level is off.')
+      deps.io.err('Turn it on with `notifai config set log_level info --yes`.')
+    } else if (logsDiskUsage(deps.env).files === 0) {
+      deps.io.err('No log yet. It is written the next time a notifai command or harness hook runs.')
+    } else {
+      deps.io.err('No records matched. Widen it with --all-projects, --since 1d, or --all.')
+    }
+    return EXIT.ok
+  }
+
+  // Everything explanatory goes to stderr so `--json` leaves stdout as clean
+  // JSONL for whatever is parsing it.
+  const notes: string[] = []
+  if (scope !== undefined) notes.push(`project ${scope} (--all-projects for every project)`)
+  if (result.more) {
+    notes.push(
+      query.limit! < MAX_LOG_LIMIT
+        ? `more history behind this (-n ${Math.min(query.limit! * 4, MAX_LOG_LIMIT)} or --all)`
+        : `more history exists beyond the ${MAX_LOG_LIMIT}-record safety cap; narrow with --since or filters`,
+    )
+  }
+  if (config.log_level.value !== 'debug') notes.push('`log_level = debug` records request detail')
+  if (notes.length > 0) deps.io.err(`— ${result.records.length} records; ${notes.join('; ')}`)
+  return EXIT.ok
+}

package/src/commands-send-support.ts

@@ -0,0 +1,224 @@
+import { type ListRepliesResponse } from '@raidiant/notifai-protocol'
+import { sha256Hex } from '@raidiant/notifai-protocol/node'
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { isRetryableReplyPollError, type ApiClient } from './client.js'
+import { buildSourceContext, inferInvocationContext } from './invocation-context.js'
+import { type DraftInvocation, type SendFlags } from './send.js'
+import { EXIT, reportError, type CommandDeps } from './commands-core.js'
+import type { ActiveHarnessSession } from './commands-harness-context.js'
+
+export function resolveDraftInvocation(
+  deps: CommandDeps,
+  flags: Pick<SendFlags, 'sessionId' | 'sessionLabel'>,
+  active: ActiveHarnessSession | null,
+): { ok: true; invocation: DraftInvocation } | { ok: false; error: string } {
+  const inferred = inferInvocationContext(deps.cwd)
+  const source = buildSourceContext({
+    env: deps.env,
+    invocation: inferred,
+    ...(flags.sessionId !== undefined ? { sessionId: flags.sessionId } : {}),
+    ...(flags.sessionLabel !== undefined ? { sessionLabel: flags.sessionLabel } : {}),
+    ...(active === null
+      ? {}
+      : {
+          activeHarness: {
+            harness: active.harness,
+            ...(active.sessionId === undefined ? {} : { sessionId: active.sessionId }),
+          },
+        }),
+  })
+  if (!source.ok) return source
+  return {
+    ok: true,
+    invocation: {
+      inferredProject: inferred.project,
+      ...(source.source === undefined ? {} : { source: source.source }),
+    },
+  }
+}
+
+interface ReplyWaitOptions {
+  timeoutSeconds: number
+  afterSeq: number
+  now?: (() => number) | undefined
+  sleep?: ((milliseconds: number) => Promise<void>) | undefined
+}
+
+interface ReplyWaitResult {
+  response: ListRepliesResponse
+  timedOut: boolean
+  /**
+   * The wait ended while polls were failing, so silence is unproven: the user
+   * may well have answered and we could not see it.
+   */
+  degraded: boolean
+}
+
+/** Loop over server-capped long polls until a reply arrives or the caller's deadline passes. */
+export async function waitForReply(
+  client: ApiClient,
+  requestId: string,
+  options: ReplyWaitOptions,
+): Promise<ReplyWaitResult> {
+  const now = options.now ?? Date.now
+  const sleep = options.sleep ?? ((milliseconds: number) => new Promise((resolve) => setTimeout(resolve, milliseconds)))
+  const deadline = now() + options.timeoutSeconds * 1000
+  let lastResponse: ListRepliesResponse | null = null
+  let lastTransientError: Error | null = null
+  let consecutiveTransientErrors = 0
+  let firstPoll = true
+
+  while (firstPoll || now() < deadline) {
+    firstPoll = false
+    const remainingMs = Math.max(0, deadline - now())
+    const waitSeconds = Math.min(25, Math.floor(remainingMs / 1000))
+    try {
+      const response = await client.replies(requestId, {
+        waitSeconds,
+        afterSeq: options.afterSeq,
+      })
+      lastResponse = response
+      lastTransientError = null
+      consecutiveTransientErrors = 0
+      if (response.replies.length > 0) return { response, timedOut: false, degraded: false }
+
+      const pauseMs = Math.min(250, Math.max(0, deadline - now()))
+      if (pauseMs > 0) await sleep(pauseMs)
+    } catch (err) {
+      if (!isRetryableReplyPollError(err)) throw err
+      lastTransientError = err instanceof Error ? err : new Error(String(err))
+      consecutiveTransientErrors += 1
+      const remainingAfterError = Math.max(0, deadline - now())
+      if (remainingAfterError === 0) break
+      const backoffMs = Math.min(
+        250 * 2 ** (consecutiveTransientErrors - 1),
+        2_000,
+        remainingAfterError,
+      )
+      await sleep(backoffMs)
+    }
+  }
+
+  // Never saw a successful poll: surface the fault so callers get EXIT.network
+  // rather than a fake empty silence. The durable request is still on the
+  // server; the typed recovery is `notifai replies <id>`.
+  if (!lastResponse && lastTransientError) throw lastTransientError
+  return {
+    response:
+      lastResponse ??
+      ({
+        request_id: requestId,
+        reply_expires_at: null,
+        agent_acknowledgement_required: false,
+        agent_acknowledgement_text_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
+    // "no reply" would let an agent treat an unseen refusal as consent.
+    degraded: lastTransientError !== null,
+  }
+}
+
+function acknowledgeInvocation(requestId: string, textRequired: boolean): string {
+  return textRequired
+    ? `notifai acknowledge ${requestId} --text <text>`
+    : `notifai acknowledge ${requestId}`
+}
+
+export function acknowledgementCommand(
+  requestId: string,
+  required: boolean,
+  textRequired: boolean,
+  acknowledgement: ListRepliesResponse['agent_acknowledgement'],
+  hasReply = true,
+): string | null {
+  return required && acknowledgement === null && hasReply
+    ? acknowledgeInvocation(requestId, textRequired)
+    : null
+}
+
+export function printAcknowledgementStatus(deps: CommandDeps, response: ListRepliesResponse): void {
+  if (!response.agent_acknowledgement_required) {
+    deps.io.out('Agent Acknowledgement: not required for this request.')
+    return
+  }
+  const textRequired = response.agent_acknowledgement_text_required
+  if (response.agent_acknowledgement !== null) {
+    const recorded = `Agent Acknowledgement: recorded at ${response.agent_acknowledgement.created_at}`
+    deps.io.out(
+      response.agent_acknowledgement.text.length > 0
+        ? `${recorded}: ${response.agent_acknowledgement.text}`
+        : `${recorded}.`,
+    )
+    return
+  }
+  if (response.replies.length > 0) {
+    deps.io.out('Agent Acknowledgement required.')
+    deps.io.out(
+      textRequired
+        ? `next: Run \`${acknowledgeInvocation(response.request_id, true)}\` with concrete text saying what you will do because of the reply.`
+        : `next: Run \`${acknowledgeInvocation(response.request_id, false)}\` so the user sees you read the reply; this account turned acknowledgement text off.`,
+    )
+    return
+  }
+  deps.io.out('Agent Acknowledgement: required after a user reply; no reply is recorded yet.')
+}
+
+const MEDIA_TYPES: Record<string, 'image/jpeg' | 'image/png' | 'image/gif'> = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+}
+
+type UploadResult =
+  | { ok: true; mediaId: string }
+  /** `error: null` means `reportError` already said it; do not print it twice. */
+  | { ok: false; error: string | null; exit: number }
+
+/** `--image` accepts a media id, a local file path, or an http(s) URL. */
+export async function uploadImage(deps: CommandDeps, client: ApiClient, source: string): Promise<UploadResult> {
+  let bytes: Uint8Array
+  let mediaType: 'image/jpeg' | 'image/png' | 'image/gif' | undefined
+  if (/^https?:\/\//.test(source)) {
+    try {
+      const response = await fetch(source)
+      if (!response.ok) return { ok: false, error: `Could not fetch ${source} (${response.status}).`, exit: EXIT.usage }
+      const contentType = response.headers.get('content-type')?.split(';')[0]?.trim() ?? ''
+      mediaType = (['image/jpeg', 'image/png', 'image/gif'] as const).find((t) => t === contentType)
+      bytes = new Uint8Array(await response.arrayBuffer())
+    } catch (err) {
+      return { ok: false, error: `Could not fetch ${source}: ${String(err)}`, exit: EXIT.network }
+    }
+  } else {
+    if (!existsSync(source)) {
+      return { ok: false, error: `--image: "${source}" is not a media id, file, or URL.`, exit: EXIT.usage }
+    }
+    bytes = new Uint8Array(readFileSync(source))
+    mediaType = MEDIA_TYPES[path.extname(source).toLowerCase()]
+  }
+  if (!mediaType) {
+    return { ok: false, error: 'Images must be JPEG, PNG, or GIF.', exit: EXIT.usage }
+  }
+  try {
+    const grant = await client.createMediaUpload({
+      media_type: mediaType,
+      size_bytes: bytes.byteLength,
+      sha256: sha256Hex(bytes),
+    })
+    await client.uploadMedia(grant, bytes)
+    return { ok: true, mediaId: grant.media_id }
+  } catch (err) {
+    // Every other API failure in this file goes through `reportError`, which
+    // maps a revoked credential to the auth code, a server fault to the network
+    // one and everything else to plain failure, and records it in the local
+    // log with whatever next step the server named. This used to answer
+    // `network` to all of them, so an image too large for the account exited
+    // the same way an unreachable server did, and nothing about it was logged.
+    return { ok: false, error: null, exit: reportError(deps, err) }
+  }
+}