@raidiant/notifai 0.1.8 → 0.2.1

package/README.md

@@ -35,7 +35,7 @@ banner and is shown in the companion app for when you sit down.
 ## Asking you a question
 
 ```sh
-notifai ask "Deploy the migration to production?" --choice "Yes,No"
+notifai ask "Deploy the migration to production?" --choice Yes --choice No
 ```
 
 The agent registers the question, ends its turn, and your answer comes

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import { type ListRepliesResponse, type Platform, type ReplyView } from '@raidiant/notifai-protocol';
+import { type ListRepliesResponse, type Platform, type QuestionT, type ReplyView } from '@raidiant/notifai-protocol';
 import { type ApiClient, type ClientOptions } from './client.js';
 import type { CredentialStore } from './credentials.js';
 import { type Readiness } from './readiness.js';
@@ -112,16 +112,15 @@ interface ReplyWaitResult {
 /** Loop over server-capped long polls until a reply arrives or the caller's deadline passes. */
 export declare function waitForReply(client: ApiClient, requestId: string, options: ReplyWaitOptions): Promise<ReplyWaitResult>;
 /**
- * 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 declare function contradictingAnswer(replies: ReplyView[]): string | null;
 export declare function statusCommand(deps: CommandDeps, requestId: string, flags: {
@@ -155,16 +154,35 @@ export declare function hookRunCommand(deps: CommandDeps, event: string, readStd
  */
 export declare function describeHookFailure(err: 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;
 }
+/**
+ * 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 declare function buildQuestions(flags: AskFlags, question: string | undefined): {
+    ok: true;
+    questions: QuestionT[];
+    detail?: string;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * 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 declare function askCommand(deps: CommandDeps, question: string, flags: AskFlags): number;
+export declare function askCommand(deps: CommandDeps, question: string | undefined, flags: AskFlags): number;
 /** Retire a question so a late answer is rejected rather than silently lost. */
 export declare function closeCommand(deps: CommandDeps, requestId: string): Promise<number>;
 export interface HooksInstallFlags {
@@ -191,7 +209,7 @@ export declare function configSetCommand(deps: CommandDeps, key: string, rawValu
  * 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 declare const SKILLS_SOURCE = "Raidiant-io/notifai#v0.1.8";
+export declare const SKILLS_SOURCE = "Raidiant-io/notifai#v0.2.1";
 /** Derive a contract-valid project slug from a directory name. */
 export declare function projectSlugFrom(name: string): string;
 export interface InitFlags {

package/dist/commands.js

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSyn
 import os from 'node:os';
 import path from 'node:path';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
-import { CAPABILITIES_V1, REPLY_MAX_WINDOW_SECONDS, validateDraft, } from '@raidiant/notifai-protocol';
+import { CAPABILITIES_V1, QUESTION_TEXT_MAX_LENGTH, REPLY_MAX_QUESTIONS, REPLY_MAX_WINDOW_SECONDS, validateDraft, } from '@raidiant/notifai-protocol';
 import { sha256Hex } from '@raidiant/notifai-protocol/node';
 import { ApiCallError, NetworkError, createClient, } from './client.js';
 import { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS, NUMERIC_CONFIG_KEYS, configBounds, findProjectConfigPath, findProjectLocalConfigPath, globalConfigPath, loadConfig, sessionConfigPath, } from './config.js';
@@ -13,7 +13,7 @@ import { handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, p
 import { readIdleSeconds } from './idle.js';
 import { HARNESSES, applyPlan, blockingHookTimeoutSeconds, buildCursorHookConfig, buildHookConfig, codexLayerDir, codexProjectRoot, detectHarness, findInstallations, handlerEvent, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, } from './install-hooks.js';
 import { isOurOpencodePlugin, opencodePluginSource, } from './opencode-plugin.js';
-import { CHOICE_USAGE, ambiguousChoiceSplit, buildDraft, formatReceipt, parseChoices, receiptExitCode, } from './send.js';
+import { CHOICE_USAGE, buildDraft, formatReceipt, parseChoices, receiptExitCode, slugify, } from './send.js';
 export const EXIT = {
     ok: 0,
     failed: 1,
@@ -433,20 +433,25 @@ export async function repliesCommand(deps, requestedId, flags) {
         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 !== 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;
     }
@@ -455,27 +460,44 @@ export async function repliesCommand(deps, requestedId, flags) {
     if (!authed)
         return EXIT.auth;
     try {
-        const result = await waitForReply(authed.client, requestId, {
-            timeoutSeconds: waitSeconds,
-            afterSeq,
-            now: deps.now,
-            sleep: deps.sleep,
-        });
-        if (flags.json) {
-            deps.io.out(JSON.stringify({ ...result.response, degraded: result.degraded }, null, 2));
+        let anyReplies = false;
+        let anyDegraded = false;
+        let allTimedOut = true;
+        const jsonBodies = [];
+        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;
         }
-        else if (result.response.replies.length > 0) {
-            if (flags.pending === true)
-                deps.io.out(`pending request ${requestId}`);
-            printReplies(deps, result.response.replies);
+        if (flags.json) {
+            // 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);
@@ -550,29 +572,27 @@ function printReplies(deps, replies) {
         deps.io.err(contradiction);
 }
 /**
- * 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) {
-    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)
+    const key = (reply) => 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(disagreeing.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.`);
+    const names = [...new Set(corrected.map((reply) => reply.device_name))].join(', ');
+    return (`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.`);
 }
 function printNoReply(deps, requestId, expiresAt) {
     // A harness hook may have retired this question, in which case promising an
@@ -841,6 +861,88 @@ function rejectedPaths(details) {
         .filter((path) => path !== null && path !== '')
         .slice(0, 5);
 }
+/**
+ * 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, question) {
+    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;
+        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.questions)) {
+            return { ok: false, error: '--form needs a "questions" array (1-4 entries).' };
+        }
+        const form = parsed;
+        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 = [];
+        const usedIds = new Set();
+        for (const [index, entry] of form.questions.entries()) {
+            if (typeof entry !== 'object' || entry === null || typeof entry.text !== 'string') {
+                return { ok: false, error: `Question ${index + 1} needs a "text" string.` };
+            }
+            const spec = entry;
+            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, choiceLabels, multi, index, usedIds) {
+    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
@@ -895,37 +997,38 @@ export function askCommand(deps, question, flags) {
             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 {
         registerQuestion(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)());
     }
     catch (err) {
         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;
 }
 function activeHarnessSession(env) {
@@ -1381,7 +1484,7 @@ export async function configSetCommand(deps, key, rawValue, flags) {
  * 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() {
     const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE);
     return match === null ? null : { source: match[1], ref: match[2] };
@@ -2393,12 +2496,16 @@ function remedyLine(state) {
  * 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) {
     const installations = findInstallations(deps.cwd, deps.env);
@@ -2438,23 +2545,30 @@ function hookStates(deps) {
     }
     /** 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(/-$/, ''),
             title: check.name === 'hooks' || check.name.startsWith('hooks (active')
                 ? 'Question routing'
                 : check.name,
-            status: check.ok ? 'ready' : informational.has(check.name) ? 'optional-gap' : 'gap',
+            status: check.ok
+                ? 'ready'
+                : check.informational === true || informational.has(check.name)
+                    ? 'optional-gap'
+                    : 'gap',
             detail: check.detail,
             ...(check.ok
                 ? {}
                 : {
                     remedy: {
                         by: 'user-here',
-                        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',
+                        }),
                     },
                 }),
         })),
@@ -2492,21 +2606,52 @@ function hookChecks(deps) {
             detail: 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
+            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',
+                            },
+                        }),
+                });
+            }
         }
     }
     // A handler naming an event this build dropped exits 2 every time the harness
@@ -2574,9 +2719,20 @@ function hookChecks(deps) {
     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')) {
         checks.push({