@rmrdeveloper/sideroom-pi 8.1.0 → 8.2.0

package/README.md

@@ -4,6 +4,15 @@
 [![npm monthly downloads](https://img.shields.io/npm/dm/@rmrdeveloper/sideroom-pi?label=downloads&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 
+**Asks before it guesses. Shows the plan. Enforces the style. Refuses to
+call it done in red.**
+
+```bash
+pi install npm:@rmrdeveloper/sideroom-pi
+```
+
+![Sideroom asking a multi-question batch and keeping the live board below it](https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/preview.png)
+
 > Coding agents fail in predictable ways: they guess instead of asking, they
 > bury progress in chat scroll, they litter your repo with `TODO.md` files,
 > every session writes code in a slightly different style, and they declare
@@ -54,9 +63,10 @@ wall of tool calls, it:
 
 - **Asks like a senior would.** A clean TUI questionnaire appears — tabs for
   several questions, a simple list for one. Every question carries a
-  recommendation, you can always answer *Out of scope* or write your own,
-  and everything is written in your language. Escape cancels the whole
-  batch. No guessing, no twenty follow-up clarifications in chat.
+  recommendation, and a plural one lets you tick several answers at once. You
+  can always answer *Out of scope* or write your own, and everything is written
+  in your language. Escape cancels the whole batch. No guessing, no twenty
+  follow-up clarifications in chat.
 - **Works in the open.** A compact board sits above the editor:
   `pending → in_progress → completed`. Exactly one step is active at a
   time; the agent completes the current step and starts the next one in the
@@ -86,9 +96,11 @@ wall of tool calls, it:
 ### `sideroom_ask` — decisions, not interrogations
 
 One call is one 1–N question batch. Each question needs an `id`, a `prompt`,
-at least two `{ value, label }` options, and a `recommendationIndex` pointing
-at the recommended option. The UI adds the rest: the recommended mark, the
-always-on *Out of scope* row, and a custom answer.
+at least two `{ value, label }` options, and a recommendation:
+`recommendationIndex` for the default single answer, or
+`selectionMode: "multiple"` with `recommendedIndices` when the question accepts
+several. The UI adds the rest: the recommended mark, the always-on *Out of
+scope* row, and a custom answer.
 
 TUI-only by design. In print, JSON, or RPC modes it fails fast with
 `UI not available` instead of hanging.
@@ -185,9 +197,10 @@ pi update --extension npm:@rmrdeveloper/sideroom-pi
 ### Questionnaire contract
 
 Each batch accepts one to four questions, with two to four caller-provided
-options per question. Tab labels accept at most 16 characters and option
-labels at most 60. Inputs that exceed a limit are rejected rather than
-truncated.
+options per question. A question takes one answer unless it declares
+`selectionMode: "multiple"`, which requires `recommendedIndices` and at least
+one selection. Tab labels accept at most 16 characters and option labels at
+most 60. Inputs that exceed a limit are rejected rather than truncated.
 
 Write prompts, tab labels, and option copy in the language the user is
 speaking; keep ids, option values, and TUI chrome in English. Do not send
@@ -250,6 +263,23 @@ Single-session scope only. Files are created lazily: nothing exists until
 the first term or decision crystallises. A session with a sharper glossary
 and zero ADRs is working as designed.
 
+### Coexisting with other grilling skills
+
+Pi routes skills by description, not by name, so several grilling skills can
+be installed at once. `sideroom-grill` claims non-trivial plans before
+implementation and states precedence over other grilling, interview, and spec
+skills. If a third-party skill still wins, remove it from routing by adding
+`disable-model-invocation: true` to its frontmatter, or exclude its path with
+`-path` in `settings.skills`. A literal name collision keeps the first skill
+found: project `.pi/skills`, then project `.agents/skills`, then
+`~/.pi/agent/skills`, then `~/.agents/skills`, then packages.
+
+## Documentation
+
+Maintainer reference lives in [`docs/`](docs/README.md): the
+[architecture](docs/architecture.md) and one page per
+[extension](docs/extensions/ask.md).
+
 ## License
 
 MIT.

package/extensions/ask/index.ts

@@ -9,16 +9,18 @@ import {
 } from './model.ts';
 
 export const ASK_DESCRIPTION =
-  'Ask the user one or more questions in the language they are speaking. Use for clarifying requirements, getting preferences, or confirming decisions. Each question must include a recommended option. For a single question, shows a simple option list. For multiple questions, shows a tab-based interface.';
+  'Ask the user one or more questions in the language they are speaking. Use for clarifying requirements, getting preferences, or confirming decisions. Each question must include a recommended option, or several recommended options when it accepts multiple selections. For a single question, shows a simple option list. For multiple questions, shows a tab-based interface.';
 
 export const ASK_PROMPT_SNIPPET =
   'Ask the user one or more questions with a recommended option, in their language.';
 
 export const ASK_PROMPT_GUIDELINES = [
   'Use sideroom_ask to clarify requirements, preferences, or decisions with the user.',
+  'When a non-trivial request is not yet a settled spec, follow the sideroom-grill skill before implementing; it owns the interview and drives sideroom_ask rounds.',
   'Each sideroom_ask question needs an id, a prompt, at least two options, and a recommendationIndex pointing at the recommended option.',
   'Write every sideroom_ask prompt, tab label, and option label or description in the language the user is speaking. Keep ids, option values, and tool code in English.',
-  'sideroom_ask always adds Out of scope and a custom answer; do not include those options yourself.',
+  'sideroom_ask always adds Out of scope and a custom answer; do not include those options yourself, and in a multiple-selection question they replace the selections.',
+  'For a genuinely plural sideroom_ask question, set selectionMode "multiple" with recommendedIndices (at least one) instead of recommendationIndex; never send both fields, and keep the single default otherwise.',
   'One sideroom_ask call is one batch; call it again if another round of questions is needed.',
   'sideroom_ask only works in the interactive TUI; it returns an error in print, JSON, or RPC modes.',
 ];
@@ -73,6 +75,14 @@ export default function registerAsk(pi: ExtensionAPI): void {
         if (answer.wasCustom) {
           return `${mark}${id}: ${theme.fg('muted', '(wrote) ')}${answer.label}`;
         }
+        if (answer.selections !== undefined && answer.selections.length > 0) {
+          const picked = answer.selections
+            .map(
+              (selection) => `${String(selection.index)}. ${selection.label}`,
+            )
+            .join(', ');
+          return `${mark}${id}: ${picked}`;
+        }
         if (answer.index !== undefined) {
           return `${mark}${id}: ${String(answer.index)}. ${answer.label}`;
         }

package/extensions/ask/model.ts

@@ -9,6 +9,13 @@ export const CUSTOM_LABEL = 'Write a custom answer';
 export const UI_UNAVAILABLE =
   'Error: UI not available (running in non-interactive mode)';
 
+export const SINGLE_SELECTION_MODE = 'single';
+export const MULTIPLE_SELECTION_MODE = 'multiple';
+
+export type SelectionMode =
+  | typeof SINGLE_SELECTION_MODE
+  | typeof MULTIPLE_SELECTION_MODE;
+
 const MAX_QUESTIONS = 4;
 const MAX_OPTIONS = 4;
 const MAX_TAB_LABEL_LENGTH = 16;
@@ -39,10 +46,32 @@ const QuestionSchema = Type.Object({
     maxItems: MAX_OPTIONS,
     description: `Two to ${String(MAX_OPTIONS)} mutually exclusive options`,
   }),
-  recommendationIndex: Type.Integer({
-    minimum: 0,
-    description: 'Index into options pointing at the recommended option',
-  }),
+  selectionMode: Type.Optional(
+    Type.Union(
+      [
+        Type.Literal(SINGLE_SELECTION_MODE),
+        Type.Literal(MULTIPLE_SELECTION_MODE),
+      ],
+      {
+        description:
+          "'single' (default) answers with one option; 'multiple' answers with one or more",
+      },
+    ),
+  ),
+  recommendationIndex: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      description:
+        "Required for a 'single' question: index into options pointing at the recommended option",
+    }),
+  ),
+  recommendedIndices: Type.Optional(
+    Type.Array(Type.Integer({ minimum: 0 }), {
+      minItems: 1,
+      description:
+        "Required for a 'multiple' question: indexes of every recommended option, at least one",
+    }),
+  ),
 });
 
 export const AskParamsSchema = Type.Object({
@@ -61,7 +90,14 @@ export interface AskQuestion {
   readonly label: string;
   readonly prompt: string;
   readonly options: readonly QuestionOption[];
-  readonly recommendationIndex: number;
+  readonly selectionMode: SelectionMode;
+  readonly recommendedIndices: readonly number[];
+}
+
+export interface AskSelection {
+  readonly value: string;
+  readonly label: string;
+  readonly index: number;
 }
 
 export interface AskAnswer {
@@ -71,6 +107,7 @@ export interface AskAnswer {
   readonly wasCustom: boolean;
   readonly outOfScope: boolean;
   readonly index?: number;
+  readonly selections?: readonly AskSelection[];
 }
 
 export interface AskResult {
@@ -208,11 +245,9 @@ export function parseAskParams(value: unknown): ParseAskResult {
       };
     }
     seen.add(question.id);
-    if (question.recommendationIndex >= question.options.length) {
-      return {
-        ok: false,
-        message: `Error: recommendationIndex ${String(question.recommendationIndex)} is out of range for question '${question.id}'`,
-      };
+    const failure = recommendationError(question);
+    if (failure !== undefined) {
+      return { ok: false, message: failure };
     }
   }
 
@@ -224,6 +259,7 @@ export function normalizeQuestions(
 ): AskQuestion[] {
   return questions.map((question, index) => {
     const label = question.label;
+    const selectionMode = selectionModeOf(question);
     return {
       id: question.id,
       label:
@@ -232,15 +268,67 @@ export function normalizeQuestions(
           : `Q${String(index + 1)}`,
       prompt: question.prompt,
       options: question.options,
-      recommendationIndex: question.recommendationIndex,
+      selectionMode,
+      recommendedIndices: recommendedIndicesFor(question, selectionMode),
     };
   });
 }
 
+function selectionModeOf(
+  question: AskParams['questions'][number],
+): SelectionMode {
+  return question.selectionMode === MULTIPLE_SELECTION_MODE
+    ? MULTIPLE_SELECTION_MODE
+    : SINGLE_SELECTION_MODE;
+}
+
+function recommendedIndicesFor(
+  question: AskParams['questions'][number],
+  selectionMode: SelectionMode,
+): readonly number[] {
+  if (selectionMode === MULTIPLE_SELECTION_MODE) {
+    return question.recommendedIndices ?? [];
+  }
+  if (question.recommendationIndex === undefined) {
+    return [];
+  }
+  return [question.recommendationIndex];
+}
+
+function recommendationError(
+  question: AskParams['questions'][number],
+): string | undefined {
+  if (selectionModeOf(question) === SINGLE_SELECTION_MODE) {
+    if (question.recommendationIndex === undefined) {
+      return `Error: Question '${question.id}' requires recommendationIndex`;
+    }
+    if (question.recommendedIndices !== undefined) {
+      return `Error: Question '${question.id}' is a single-selection question; remove recommendedIndices`;
+    }
+    if (question.recommendationIndex >= question.options.length) {
+      return `Error: recommendationIndex ${String(question.recommendationIndex)} is out of range for question '${question.id}'`;
+    }
+    return undefined;
+  }
+  if (question.recommendedIndices === undefined) {
+    return `Error: Question '${question.id}' is a multiple-selection question and requires recommendedIndices`;
+  }
+  if (question.recommendationIndex !== undefined) {
+    return `Error: Question '${question.id}' is a multiple-selection question; remove recommendationIndex`;
+  }
+  const outOfRange = question.recommendedIndices.find(
+    (optionIndex) => optionIndex >= question.options.length,
+  );
+  if (outOfRange !== undefined) {
+    return `Error: recommendedIndices ${String(outOfRange)} is out of range for question '${question.id}'`;
+  }
+  return undefined;
+}
+
 export function renderOptions(question: AskQuestion): RenderOption[] {
   const options: RenderOption[] = question.options.map((option, index) => ({
     ...option,
-    isRecommended: index === question.recommendationIndex,
+    isRecommended: question.recommendedIndices.includes(index),
   }));
   options.push({
     value: OUT_OF_SCOPE_VALUE,
@@ -268,6 +356,13 @@ export function formatAnswerLines(
     if (answer.wasCustom) {
       return `${questionLabel}: user wrote: ${answer.label}`;
     }
+    const selections = answer.selections;
+    if (selections !== undefined && selections.length > 0) {
+      const picked = selections
+        .map((selection) => `${String(selection.index)}. ${selection.label}`)
+        .join(', ');
+      return `${questionLabel}: user selected: ${picked}`;
+    }
     if (answer.index !== undefined) {
       return `${questionLabel}: user selected: ${String(answer.index)}. ${answer.label}`;
     }
@@ -302,6 +397,15 @@ function schemaErrorMessage(value: unknown): string {
     }
   }
 
+  const recommendedMatch = /\/questions\/(\d+)\/recommendedIndices$/.exec(
+    error.instancePath,
+  );
+  if (recommendedMatch !== null && error.keyword === 'minItems') {
+    const questionIndex = Number(recommendedMatch[1]);
+    const id = questionId(questions, questionIndex);
+    return `Error: Question '${id}' must mark at least one recommended option`;
+  }
+
   const tabLabelMatch = /\/questions\/(\d+)\/label$/.exec(error.instancePath);
   if (error.keyword === 'maxLength' && tabLabelMatch !== null) {
     const questionIndex = Number(tabLabelMatch[1]);

package/extensions/ask/selection.ts

@@ -0,0 +1,47 @@
+import type { AskAnswer, AskQuestion, AskSelection } from './model.ts';
+
+/**
+ * Sorted ascending so the answer and its rendering stay stable no matter the
+ * order the user toggled the options in.
+ */
+export function toggleSelection(
+  selected: readonly number[],
+  optionIndex: number,
+): number[] {
+  if (selected.includes(optionIndex)) {
+    return selected.filter((index) => index !== optionIndex);
+  }
+  return [...selected, optionIndex].sort((left, right) => left - right);
+}
+
+export function answerFromSelections(
+  question: AskQuestion,
+  selected: readonly number[],
+): AskAnswer {
+  const selections = selected.map((optionIndex) =>
+    toSelection(question, optionIndex),
+  );
+  const [first] = selections;
+  if (first === undefined) {
+    throw new Error(`Question '${question.id}' needs at least one selection`);
+  }
+  return {
+    id: question.id,
+    value: first.value,
+    label: first.label,
+    index: first.index,
+    wasCustom: false,
+    outOfScope: false,
+    selections,
+  };
+}
+
+function toSelection(question: AskQuestion, optionIndex: number): AskSelection {
+  const option = question.options[optionIndex];
+  if (option === undefined) {
+    throw new Error(
+      `Unknown option index ${String(optionIndex)} for question '${question.id}'`,
+    );
+  }
+  return { value: option.value, label: option.label, index: optionIndex + 1 };
+}

package/extensions/ask/ui.ts

@@ -11,9 +11,11 @@ import {
   type AskAnswer,
   type AskQuestion,
   type AskResult,
+  MULTIPLE_SELECTION_MODE,
   type RenderOption,
   renderOptions,
 } from './model.ts';
+import { answerFromSelections, toggleSelection } from './selection.ts';
 
 export async function runAskUi(
   ui: Pick<ExtensionUIContext, 'custom'>,
@@ -25,8 +27,7 @@ export async function runAskUi(
   return ui.custom<AskResult>((tui, theme, _keybindings, done) => {
     let currentTab = 0;
     const firstQuestion = questions[0];
-    let optionIndex =
-      firstQuestion === undefined ? 0 : firstQuestion.recommendationIndex;
+    let optionIndex = firstQuestion?.recommendedIndices[0] ?? 0;
     let inputMode = false;
     let inputQuestionId: string | null = null;
     let cachedLines: string[] | undefined;
@@ -82,11 +83,10 @@ export async function runAskUi(
         return;
       }
       const saved = answers.get(question.id);
-      if (saved?.index !== undefined) {
-        optionIndex = saved.index - 1;
-      } else {
-        optionIndex = question.recommendationIndex;
-      }
+      optionIndex =
+        saved?.index !== undefined
+          ? saved.index - 1
+          : (question.recommendedIndices[0] ?? 0);
       refresh();
     }
 
@@ -106,6 +106,45 @@ export async function runAskUi(
       answers.set(answer.id, answer);
     }
 
+    function selectedIndices(question: AskQuestion): readonly number[] {
+      const saved = answers.get(question.id);
+      if (saved?.selections === undefined) {
+        return [];
+      }
+      return saved.selections.map((selection) => selection.index - 1);
+    }
+
+    function answerSummary(answer: AskAnswer): string {
+      if (answer.selections === undefined || answer.selections.length === 0) {
+        return answer.label;
+      }
+      return answer.selections.map((selection) => selection.label).join(', ');
+    }
+
+    function isReservedOption(opt: RenderOption): boolean {
+      return opt.isOther === true || opt.isOutOfScope === true;
+    }
+
+    function activateReservedOption(
+      question: AskQuestion,
+      opt: RenderOption,
+      index: number,
+    ): void {
+      if (opt.isOther === true) {
+        openCustomEditor(question);
+        return;
+      }
+      saveAnswer({
+        id: question.id,
+        value: opt.value,
+        label: opt.label,
+        wasCustom: false,
+        outOfScope: true,
+        index: index + 1,
+      });
+      advanceAfterAnswer();
+    }
+
     function openCustomEditor(question: AskQuestion): void {
       inputMode = true;
       inputQuestionId = question.id;
@@ -127,20 +166,8 @@ export async function runAskUi(
       if (opt === undefined) {
         return;
       }
-      if (opt.isOther === true) {
-        openCustomEditor(question);
-        return;
-      }
-      if (opt.isOutOfScope === true) {
-        saveAnswer({
-          id: question.id,
-          value: opt.value,
-          label: opt.label,
-          wasCustom: false,
-          outOfScope: true,
-          index: index + 1,
-        });
-        advanceAfterAnswer();
+      if (isReservedOption(opt)) {
+        activateReservedOption(question, opt, index);
         return;
       }
       const original = question.options[index];
@@ -155,6 +182,49 @@ export async function runAskUi(
       advanceAfterAnswer();
     }
 
+    function toggleMultipleOption(
+      question: AskQuestion,
+      opts: readonly RenderOption[],
+      index: number,
+    ): void {
+      const opt = opts[index];
+      if (opt === undefined) {
+        return;
+      }
+      if (isReservedOption(opt)) {
+        activateReservedOption(question, opt, index);
+        return;
+      }
+      const next = toggleSelection(selectedIndices(question), index);
+      if (next.length === 0) {
+        answers.delete(question.id);
+        refresh();
+        return;
+      }
+      answers.set(question.id, answerFromSelections(question, next));
+      refresh();
+    }
+
+    function confirmMultipleSelection(
+      question: AskQuestion,
+      opts: readonly RenderOption[],
+      index: number,
+    ): void {
+      const opt = opts[index];
+      if (opt === undefined) {
+        return;
+      }
+      if (isReservedOption(opt)) {
+        activateReservedOption(question, opt, index);
+        return;
+      }
+      if (selectedIndices(question).length === 0) {
+        refresh();
+        return;
+      }
+      advanceAfterAnswer();
+    }
+
     editor.onSubmit = (value) => {
       if (inputQuestionId === null) {
         return;
@@ -232,15 +302,31 @@ export async function runAskUi(
         return;
       }
 
+      if (
+        question?.selectionMode === MULTIPLE_SELECTION_MODE &&
+        matchesKey(data, Key.space)
+      ) {
+        toggleMultipleOption(question, opts, optionIndex);
+        return;
+      }
+
       const digit = optionIndexFromDigit(data, opts.length);
       if (digit !== undefined && question !== undefined) {
         optionIndex = digit;
-        confirmOption(question, opts, digit);
+        if (question.selectionMode === MULTIPLE_SELECTION_MODE) {
+          toggleMultipleOption(question, opts, digit);
+        } else {
+          confirmOption(question, opts, digit);
+        }
         return;
       }
 
       if (matchesKey(data, Key.enter) && question !== undefined) {
-        confirmOption(question, opts, optionIndex);
+        if (question.selectionMode === MULTIPLE_SELECTION_MODE) {
+          confirmMultipleSelection(question, opts, optionIndex);
+        } else {
+          confirmOption(question, opts, optionIndex);
+        }
         return;
       }
 
@@ -310,7 +396,10 @@ export async function runAskUi(
         lines.push('');
       }
 
-      function renderOptionList(): void {
+      function renderOptionList(questionForList: AskQuestion): void {
+        const isMultipleAnswer =
+          questionForList.selectionMode === MULTIPLE_SELECTION_MODE;
+        const selected = selectedIndices(questionForList);
         for (let index = 0; index < opts.length; index += 1) {
           const opt = opts[index];
           if (opt === undefined) {
@@ -319,10 +408,16 @@ export async function runAskUi(
           if (opt.isOutOfScope === true) {
             lines.push('');
           }
-          const selected = index === optionIndex;
-          const prefix = selected ? theme.fg('accent', '> ') : '  ';
-          const color = selected ? 'accent' : 'text';
-          let line = theme.fg(color, `${String(index + 1)}. ${opt.label}`);
+          const focused = index === optionIndex;
+          const prefix = focused ? theme.fg('accent', '> ') : '  ';
+          const color = focused ? 'accent' : 'text';
+          let line = '';
+          if (isMultipleAnswer && !isReservedOption(opt)) {
+            line += selected.includes(index)
+              ? theme.fg('success', '[x] ')
+              : theme.fg('dim', '[ ] ');
+          }
+          line += theme.fg(color, `${String(index + 1)}. ${opt.label}`);
           if (opt.isRecommended === true) {
             line = `${line} ${theme.fg('dim', 'recommended')}`;
           }
@@ -367,7 +462,7 @@ export async function runAskUi(
           }
           addWrappedWithPrefix(
             ' ',
-            `${name}${theme.fg('dim', kind)}${theme.fg('text', answer.label)}`,
+            `${name}${theme.fg('dim', kind)}${theme.fg('text', answerSummary(answer))}`,
           );
         }
         lines.push('');
@@ -395,19 +490,31 @@ export async function runAskUi(
         if (saved !== undefined) {
           addWrappedWithPrefix(
             ' ',
-            theme.fg('muted', `Current: ${saved.label}`),
+            theme.fg('muted', `Current: ${answerSummary(saved)}`),
           );
         }
         lines.push('');
-        renderOptionList();
+        renderOptionList(question);
       }
 
       if (!inputMode && currentTab !== questions.length) {
         lines.push('');
+        if (
+          question?.selectionMode === MULTIPLE_SELECTION_MODE &&
+          selectedIndices(question).length === 0
+        ) {
+          addWrappedWithPrefix(
+            ' ',
+            theme.fg('warning', 'Select at least one option'),
+          );
+        }
         const count = String(opts.length);
-        const help = isMulti
-          ? `↑↓ or 1–${count} · Enter · Tab next · Esc cancel`
-          : `↑↓ or 1–${count} · Enter select · Esc cancel`;
+        let help = `↑↓ or 1–${count} · Enter select · Esc cancel`;
+        if (question?.selectionMode === MULTIPLE_SELECTION_MODE) {
+          help = `↑↓ or 1–${count} toggle · Space toggle · Enter confirm · Esc cancel`;
+        } else if (isMulti) {
+          help = `↑↓ or 1–${count} · Enter · Tab next · Esc cancel`;
+        }
         addWrappedWithPrefix(' ', theme.fg('dim', help));
       }
       lines.push(theme.fg('accent', '─'.repeat(renderWidth)));