@raidiant/notifai 0.1.8 → 0.2.0

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.0";
 /** 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,
@@ -550,29 +550,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 +839,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 +975,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 +1462,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.0';
 function skillSourceParts() {
     const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE);
     return match === null ? null : { source: match[1], ref: match[2] };