@raidiant/notifai 0.1.8 → 0.2.1

package/src/commands.ts

@@ -6,12 +6,15 @@ import path from 'node:path'
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
 import {
   CAPABILITIES_V1,
+  QUESTION_TEXT_MAX_LENGTH,
+  REPLY_MAX_QUESTIONS,
   REPLY_MAX_WINDOW_SECONDS,
   validateDraft,
   type EvidenceSnapshot,
   type AccountAccessResponse,
   type ListRepliesResponse,
   type Platform,
+  type QuestionT,
   type ReplyView,
   type RoutableDevice,
   type SubmissionReceipt,
@@ -82,11 +85,11 @@ import {
 } from './opencode-plugin.js'
 import {
   CHOICE_USAGE,
-  ambiguousChoiceSplit,
   buildDraft,
   formatReceipt,
   parseChoices,
   receiptExitCode,
+  slugify,
   type SendFlags,
 } from './send.js'
 import type { NativeSkill, NativeSkills, SkillScope } from './native-skills.js'
@@ -634,20 +637,25 @@ export async function repliesCommand(
     deps.io.err('Pass a request id or --pending, not both.')
     return EXIT.usage
   }
-  let requestId = requestedId
+  let requestIds = requestedId === undefined ? [] : [requestedId]
   if (flags.pending === true) {
     const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)())
     if (sessionId === null) {
       deps.io.err('No active session pointer is available in this directory.')
       return EXIT.noReply
     }
-    requestId = readSessionState(sessionId, deps.env).pending?.request_id
-    if (requestId === undefined) {
+    // Every delivered question in the session's queue, in registration order —
+    // an agent may have several outstanding at once.
+    const state = readSessionState(sessionId, deps.env)
+    requestIds = (Array.isArray(state.pending) ? state.pending : [])
+      .map((entry) => entry.request_id)
+      .filter((id): id is string => id !== undefined)
+    if (requestIds.length === 0) {
       deps.io.err(`Session ${sessionId} has no pushed question pending.`)
       return EXIT.noReply
     }
   }
-  if (requestId === undefined) {
+  if (requestIds.length === 0) {
     deps.io.err('Pass a request id or --pending.')
     return EXIT.usage
   }
@@ -656,24 +664,40 @@ export async function repliesCommand(
   const authed = authedClient(deps, config)
   if (!authed) return EXIT.auth
   try {
-    const result = await waitForReply(authed.client, requestId, {
-      timeoutSeconds: waitSeconds,
-      afterSeq,
-      now: deps.now,
-      sleep: deps.sleep,
-    })
+    let anyReplies = false
+    let anyDegraded = false
+    let allTimedOut = true
+    const jsonBodies: object[] = []
+    for (const requestId of requestIds) {
+      const result = await waitForReply(authed.client, requestId, {
+        timeoutSeconds: waitSeconds,
+        afterSeq,
+        now: deps.now,
+        sleep: deps.sleep,
+      })
+      if (flags.json) {
+        jsonBodies.push({ ...result.response, degraded: result.degraded })
+      } else if (result.response.replies.length > 0) {
+        if (flags.pending === true) deps.io.out(`pending request ${requestId}`)
+        printReplies(deps, result.response.replies)
+      } else {
+        printNoReply(deps, requestId, result.response.reply_expires_at)
+      }
+      anyReplies ||= result.response.replies.length > 0
+      anyDegraded ||= result.degraded
+      allTimedOut &&= result.timedOut
+    }
     if (flags.json) {
-      deps.io.out(JSON.stringify({ ...result.response, degraded: result.degraded }, null, 2))
-    } else if (result.response.replies.length > 0) {
-      if (flags.pending === true) deps.io.out(`pending request ${requestId}`)
-      printReplies(deps, result.response.replies)
+      // One request keeps the response shape agents already parse; several
+      // (only possible via --pending) arrive as an array in queue order.
+      deps.io.out(JSON.stringify(jsonBodies.length === 1 ? jsonBodies[0] : jsonBodies, null, 2))
     }
-    else printNoReply(deps, requestId, result.response.reply_expires_at)
-    if (result.degraded) {
+    if (anyDegraded) {
       deps.io.err(DEGRADED_WAIT_WARNING)
       return EXIT.network
     }
-    return result.timedOut ? EXIT.noReply : EXIT.ok
+    if (anyReplies) return EXIT.ok
+    return allTimedOut ? EXIT.noReply : EXIT.ok
   } catch (err) {
     return reportError(deps, err)
   }
@@ -770,28 +794,27 @@ function printReplies(deps: CommandDeps, replies: ReplyView[]): void {
 }
 
 /**
- * The other half of first-reply-wins.
+ * The correction note for a wait that saw more than one answer.
  *
- * A blocking send returns the first non-empty batch and acts on it, so a later
- * answer that disagrees is silently ignored. That is the right default — an
- * agent wants one answer, not a quorum — but silently is the wrong way to do
- * it. The server now retires the question on the other devices the moment one
- * answers, which makes this rare; it is still reachable, because a device can
- * answer between the first reply landing and its retirement arriving.
+ * A later reply that conflicts with an earlier one is a correction, so the
+ * latest answer is the one that counts. The server retires the question on
+ * the other devices the moment one answers, which makes this rare; it is
+ * still reachable, because a device can answer between the first reply
+ * landing and its retirement arriving.
  *
- * Ordered by seq, so `replies[0]` is the one that won.
+ * Ordered by seq, so `replies.at(-1)` is the answer to act on.
  */
 export function contradictingAnswer(replies: ReplyView[]): string | null {
-  const winner = replies[0]
+  const winner = replies.at(-1)
   if (winner === undefined || replies.length < 2) return null
-  const disagreeing = replies
-    .slice(1)
-    .filter((reply) => (reply.choice_id ?? reply.text) !== (winner.choice_id ?? winner.text))
-  if (disagreeing.length === 0) return null
-  const names = [...new Set(disagreeing.map((reply) => reply.device_name))].join(', ')
+  const key = (reply: ReplyView) =>
+    reply.answers.length > 0 ? JSON.stringify(reply.answers) : reply.text
+  const corrected = replies.slice(0, -1).filter((reply) => key(reply) !== key(winner))
+  if (corrected.length === 0) return null
+  const names = [...new Set(corrected.map((reply) => reply.device_name))].join(', ')
   return (
-    `note: "${winner.text}" from ${winner.device_name} is the answer that counts — it arrived first. ` +
-    `${names} answered differently afterwards and that answer was not used.`
+    `note: "${winner.text}" from ${winner.device_name} is the answer that counts — a later ` +
+    `answer corrects an earlier one. Earlier differing answers from ${names} were superseded.`
   )
 }
 
@@ -1096,17 +1119,119 @@ function rejectedPaths(details: unknown): string[] {
 }
 
 export interface AskFlags {
-  choice?: string | string[]
+  choice?: string[]
+  /** The single question is multi-select: several answers may be chosen. */
+  multi?: boolean
+  /** Long-form markdown context; shown in the app, never on the banner. */
+  detail?: string
+  /** Raw JSON for a multi-question form; replaces the positional question. */
+  form?: string
   session?: string
 }
 
+/** The `--form` document: what an agent writes to ask several things at once. */
+interface AskFormQuestion {
+  text: string
+  choices?: string[]
+  multi?: boolean
+}
+
+/**
+ * Turn ask input into the question set that will ride the push. Everything is
+ * validated here, at registration, because the push happens inside a hook
+ * where a rejection becomes a stderr note the agent never reads.
+ */
+export function buildQuestions(
+  flags: AskFlags,
+  question: string | undefined,
+): { ok: true; questions: QuestionT[]; detail?: string } | { ok: false; error: string } {
+  if (flags.form !== undefined) {
+    if (question !== undefined || flags.choice?.length || flags.multi) {
+      return { ok: false, error: '--form replaces the positional question, --choice, and --multi.' }
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(flags.form)
+    } catch {
+      return { ok: false, error: '--form must be JSON: {"questions": [{"text", "choices"?, "multi"?}], "detail"?}.' }
+    }
+    if (typeof parsed !== 'object' || parsed === null || !Array.isArray((parsed as { questions?: unknown }).questions)) {
+      return { ok: false, error: '--form needs a "questions" array (1-4 entries).' }
+    }
+    const form = parsed as { questions: unknown[]; detail?: unknown }
+    if (form.questions.length < 1 || form.questions.length > REPLY_MAX_QUESTIONS) {
+      return { ok: false, error: `A form asks 1-${REPLY_MAX_QUESTIONS} questions; this one has ${form.questions.length}.` }
+    }
+    if (form.detail !== undefined && typeof form.detail !== 'string') {
+      return { ok: false, error: '"detail" must be a markdown string.' }
+    }
+    const questions: QuestionT[] = []
+    const usedIds = new Set<string>()
+    for (const [index, entry] of form.questions.entries()) {
+      if (typeof entry !== 'object' || entry === null || typeof (entry as AskFormQuestion).text !== 'string') {
+        return { ok: false, error: `Question ${index + 1} needs a "text" string.` }
+      }
+      const spec = entry as AskFormQuestion
+      const built = buildOneQuestion(spec.text, spec.choices, spec.multi === true, index, usedIds)
+      if ('error' in built) return { ok: false, error: `Question ${index + 1}: ${built.error}` }
+      questions.push(built.question)
+    }
+    return { ok: true, questions, ...(form.detail !== undefined ? { detail: form.detail } : {}) }
+  }
+
+  if (question === undefined || question.trim() === '') {
+    return { ok: false, error: 'The question cannot be empty.' }
+  }
+  const built = buildOneQuestion(question, flags.choice, flags.multi === true, 0, new Set())
+  if ('error' in built) return { ok: false, error: built.error }
+  return {
+    ok: true,
+    questions: [built.question],
+    ...(flags.detail !== undefined && flags.detail.trim() !== '' ? { detail: flags.detail } : {}),
+  }
+}
+
+function buildOneQuestion(
+  text: string,
+  choiceLabels: string[] | undefined,
+  multi: boolean,
+  index: number,
+  usedIds: Set<string>,
+): { question: QuestionT } | { error: string } {
+  const trimmed = text.trim()
+  if (trimmed === '') return { error: 'the question text cannot be empty.' }
+  if (trimmed.length > QUESTION_TEXT_MAX_LENGTH) {
+    return {
+      error:
+        `a question must be readable where it is answered: keep it within ` +
+        `${QUESTION_TEXT_MAX_LENGTH} characters and put the longer context in detail.`,
+    }
+  }
+  const choices = parseChoices(choiceLabels)
+  if (choices === 'invalid') return { error: CHOICE_USAGE }
+  if (multi && choices === null) {
+    return { error: '--multi needs answers to select between; add --choice.' }
+  }
+  let id = slugify(trimmed)
+  if (id === '' || usedIds.has(id)) id = `q${index + 1}`
+  usedIds.add(id)
+  return {
+    question: {
+      id,
+      text: trimmed,
+      ...(choices !== null ? { choices } : {}),
+      ...(multi ? { multi: true } : {}),
+    },
+  }
+}
+
 /**
  * Registers a question for turn-end routing under the user's presence config.
  * Returns immediately so the agent can ask in prose and end its turn. With the
  * default presence gate, recent keyboard or mouse activity keeps it local;
  * `require_idle = false` intentionally permits a push while the user is active.
  */
-export function askCommand(deps: CommandDeps, question: string, flags: AskFlags): number {
+export function askCommand(deps: CommandDeps, question: string | undefined, flags: AskFlags): number {
   // An agent calling this gets no hook payload. Harness-native environment
   // markers identify the active owner, while the UserPromptSubmit hook leaves
   // a pointer keyed on the project directory with the hook's canonical id.
@@ -1155,16 +1280,12 @@ export function askCommand(deps: CommandDeps, question: string, flags: AskFlags)
     for (const line of diagnoseMissingSession(deps)) deps.io.err(line)
     return EXIT.usage
   }
-  if (question.trim() === '') {
-    deps.io.err('The question cannot be empty.')
-    return EXIT.usage
-  }
   // Validate here, not at push time. The push happens inside a hook, where a
   // rejection becomes a stderr note the agent never reads — so a malformed
-  // choice set would look like it registered fine and then silently never ask.
-  const choices = parseChoices(flags.choice)
-  if (choices === 'invalid') {
-    deps.io.err(CHOICE_USAGE)
+  // question set would look like it registered fine and then silently never ask.
+  const built = buildQuestions(flags, question)
+  if (!built.ok) {
+    deps.io.err(built.error)
     return EXIT.usage
   }
   try {
@@ -1172,8 +1293,9 @@ export function askCommand(deps: CommandDeps, question: string, flags: AskFlags)
       sessionId,
       deps.env,
       {
-        question: question.trim(),
-        ...(choices !== null ? { choices: choices.map((choice) => choice.label) } : {}),
+        question: built.questions[0]!.text,
+        questions: built.questions,
+        ...(built.detail !== undefined ? { detail: built.detail } : {}),
       },
       (deps.now ?? Date.now)(),
     )
@@ -1181,14 +1303,20 @@ export function askCommand(deps: CommandDeps, question: string, flags: AskFlags)
     deps.io.err(`Could not register the question: ${err instanceof Error ? err.message : String(err)}`)
     return EXIT.failed
   }
-  if (choices !== null) {
-    deps.io.out(`Answers offered: ${choices.map((choice) => choice.label).join(' / ')}`)
+  for (const [index, entry] of built.questions.entries()) {
+    const prefix = built.questions.length > 1 ? `${index + 1}. ` : ''
+    if (entry.choices !== undefined) {
+      const kind = entry.multi === true ? 'answers offered (several may be chosen)' : 'answers offered'
+      deps.io.out(`${prefix}${entry.text} — ${kind}: ${entry.choices.map((choice) => choice.label).join(' / ')}`)
+    } else if (built.questions.length > 1) {
+      deps.io.out(`${prefix}${entry.text} — free text`)
+    }
   }
-  // On stdout, not stderr: the agent reads the former and this is only useful
-  // if it is read while there is still time to fix the question.
-  const ambiguous = ambiguousChoiceSplit(flags.choice)
-  if (ambiguous !== null) deps.io.out(ambiguous)
-  deps.io.out('Question registered. Ask it in the conversation as usual and end your turn.')
+  deps.io.out(
+    built.questions.length > 1
+      ? `${built.questions.length} questions registered as one form. Ask them in the conversation as usual and end your turn.`
+      : 'Question registered. Ask it in the conversation as usual and end your turn.',
+  )
   return EXIT.ok
 }
 
@@ -1729,7 +1857,7 @@ export async function configSetCommand(
  * 1.5.x, `owner/repo@name` selects a skill; a Git ref belongs after `#`.
  * Keep this immutable and public because the command is printed to users.
  */
-export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.1.8'
+export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.2.1'
 
 function skillSourceParts(): { source: string; ref: string } | null {
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
@@ -2929,12 +3057,16 @@ function remedyLine(state: ReadinessState): string {
  * way and is not worth re-deriving. The judgment added here is which failures
  * actually stand in the way.
  *
- * Two do not. A hook that has never fired is the normal condition of an
- * install thirty seconds old, and OpenCode's inability to resume an idle turn
- * is a property of that harness rather than a fault in this setup. Treating
- * either as blocking would mean `init` could never finish for an OpenCode
- * user, or could only finish after a session had already run — so both report
- * as things worth knowing rather than things to fix.
+ * Not everything failed is in the way. A pointer that has never been
+ * published is the normal condition of an install thirty seconds old — the
+ * next prompt fixes it and no command can — and OpenCode's inability to
+ * resume an idle turn is a property of that harness rather than a fault in
+ * this setup. Treating those as blocking would mean `init` could never
+ * finish for an OpenCode user, or could only finish after a session had
+ * already run — so they report as things worth knowing rather than things to
+ * fix, and `init` walks on to the states it can actually close, delivery
+ * proof included. Which failures are informational, and what the true remedy
+ * is, is each check's own call (`HookCheck`).
  */
 function hookStates(deps: CommandDeps): ReadinessState[] {
   const installations = findInstallations(deps.cwd, deps.env)
@@ -2977,7 +3109,6 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
 
   /** Real but not in the way; see the note above. */
   const informational = new Set(['hooks (opencode continuation)'])
-  if (active === null) informational.add('hooks (fired)')
   return [
     ...hookChecks(deps).map((check) => ({
       id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
@@ -2985,15 +3116,24 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
         check.name === 'hooks' || check.name.startsWith('hooks (active')
           ? 'Question routing'
           : check.name,
-      status: check.ok ? 'ready' as const : informational.has(check.name) ? 'optional-gap' as const : 'gap' as const,
+      status: check.ok
+        ? 'ready' as const
+        : check.informational === true || informational.has(check.name)
+          ? 'optional-gap' as const
+          : 'gap' as const,
       detail: check.detail,
       ...(check.ok
         ? {}
         : {
             remedy: {
               by: 'user-here' as const,
-              summary: 'the detail above names what to change',
-              command: 'notifai hooks install',
+              // The check's own remedy when it has one; the generic reinstall
+              // line was wrong exactly where it mattered (an unfired pointer
+              // needs a prompt, not `hooks install`).
+              ...(check.remedy ?? {
+                summary: 'the detail above names what to change',
+                command: 'notifai hooks install',
+              }),
             },
           }),
     })),
@@ -3001,8 +3141,18 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
   ]
 }
 
-function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: string }[] {
-  const checks: { name: string; ok: boolean; detail: string }[] = []
+interface HookCheck {
+  name: string
+  ok: boolean
+  detail: string
+  /** Real but not in the way: worth a line, never a blocker. */
+  informational?: boolean
+  /** A remedy truer than the generic `notifai hooks install`. */
+  remedy?: { summary: string; command: string }
+}
+
+function hookChecks(deps: CommandDeps): HookCheck[] {
+  const checks: HookCheck[] = []
   const installations = findInstallations(deps.cwd, deps.env)
 
   // Not having hooks is a setup someone chose, not a fault: `send` works
@@ -3036,23 +3186,52 @@ function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: str
         activeInstallations.length > 0
           ? `active ${active.label} session has a matching hook installation`
           : `active ${active.label} session has no matching hook installation — run \`notifai hooks install --harness ${active.harness}\``,
+      ...(activeInstallations.length > 0
+        ? {}
+        : {
+            remedy: {
+              summary: `install hooks for the active ${active.label} session`,
+              command: `notifai hooks install --harness ${active.harness}`,
+            },
+          }),
     })
     if (activeInstallations.length > 0) {
       const pointer = readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)())
-      const matches =
-        pointer !== null &&
-        pointer.harness === active.harness &&
-        (active.sessionId === undefined || pointer.sessionId === active.sessionId)
-      checks.push({
-        name: 'hooks (active session)',
-        ok: matches,
-        detail:
-          pointer === null
-            ? `active ${active.label} session has not published a live pointer — send one ${active.label} prompt, then check again`
-            : matches
-              ? `the project pointer belongs to the active ${active.label} session`
-              : `the project pointer belongs to another ${active.label} session or harness; refusing cross-session routing`,
-      })
+      if (pointer === null) {
+        // The normal condition of hooks installed moments ago: the pointer
+        // appears when the harness next fires a hook, and no command can
+        // force that. Informational, so `init` walks on to the states it can
+        // actually prove instead of exiting over evidence only time produces.
+        checks.push({
+          name: 'hooks (active session)',
+          ok: false,
+          informational: true,
+          detail: `active ${active.label} session has not published a live pointer — send one ${active.label} prompt, then check again`,
+          remedy: {
+            summary: `send one ${active.label} prompt — its hook publishes the routing pointer`,
+            command: 'notifai doctor',
+          },
+        })
+      } else {
+        const matches =
+          pointer.harness === active.harness &&
+          (active.sessionId === undefined || pointer.sessionId === active.sessionId)
+        checks.push({
+          name: 'hooks (active session)',
+          ok: matches,
+          detail: matches
+            ? `the project pointer belongs to the active ${active.label} session`
+            : `the project pointer belongs to another ${active.label} session or harness; refusing cross-session routing`,
+          ...(matches
+            ? {}
+            : {
+                remedy: {
+                  summary: `send one ${active.label} prompt in this session so the pointer belongs to it`,
+                  command: 'notifai doctor',
+                },
+              }),
+        })
+      }
     }
   }
 
@@ -3145,9 +3324,20 @@ function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: str
   checks.push({
     name: 'hooks (fired)',
     ok: fired,
+    // Never-fired is evidence about the past, not a fault in the setup, and
+    // the cure is a prompt no command can send.
+    informational: true,
     detail: fired
       ? 'a session in this directory has run them'
       : `no session pointer from the last 24 hours — ${hookActivationAdvice(activationInstallations)}`,
+    ...(fired
+      ? {}
+      : {
+          remedy: {
+            summary: 'send one prompt in a session here, then re-check',
+            command: 'notifai doctor',
+          },
+        }),
   })
 
   if (installations.some((installation) => installation.harness === 'opencode')) {