@rmrdeveloper/sideroom-pi 5.0.1 → 6.0.1

package/README.md

@@ -5,26 +5,30 @@
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 
 Sideroom Pi is a global [Pi package](https://pi.dev/docs/latest/packages). It
-registers the `/sideroom` command inside Pi and runs planner, implementer,
-reviewer, verifier, and fixer as isolated Pi SDK sessions.
+registers two parent-agent tools: `sideroom_ask`, a TUI questionnaire for
+clarifying decisions, and `sideroom_todo`, a live work board shown above the
+editor. It also shows a session-scoped list of files successfully edited by Pi.
+It writes no `.pi` configuration, task graph, or other Sideroom files into the
+repository you are working in.
 
-It creates no `.pi` configuration, task graph, harness state, or other files
-in the repository being changed.
+## Quick path
 
-## Install
+1. Install globally from npm. Pi writes this installation to your user
+   settings, so do not use `-l`.
 
-Install Sideroom globally from npm. Pi writes this installation to your user
-settings, so do not use `-l`.
+   ```bash
+   pi install npm:@rmrdeveloper/sideroom-pi
+   ```
 
-```bash
-pi install npm:@rmrdeveloper/sideroom-pi
-```
+2. Start Pi in the repository you want to work in.
+3. Ask the parent agent a question that needs a decision or a visible work
+   board. It can call `sideroom_ask` or `sideroom_todo` in the TUI.
 
-For a reproducible environment, install a specific release instead. A pinned
-version does not move when you run Pi's package update command.
+For a reproducible environment, pin a release. A pinned version does not move
+when you run Pi's package update command.
 
 ```bash
-pi install npm:@rmrdeveloper/sideroom-pi@5.0.0
+pi install npm:@rmrdeveloper/sideroom-pi@7.0.0
 ```
 
 To update an unpinned installation:
@@ -33,74 +37,80 @@ To update an unpinned installation:
 pi update --extension npm:@rmrdeveloper/sideroom-pi
 ```
 
-Start Pi from the repository you want to work in, then invoke the extension:
-
-```text
-/sideroom "Add a health endpoint"
-/sideroom --language php-laravel "Add invoice export"
-/sideroom --read-only "Review the retry behavior"
-```
-
-Pi extension commands are necessarily slash commands, so `/sideroom` is the
-single command; there is no subcommand or separate binary to run. When the
-request is omitted, Pi asks for it using its own UI.
-
-Supported guideline variants are `typescript` (default), `javascript`,
-`php-laravel`, `python`, and `java`. `--read-only` removes write-capable tools
-from every role. `--max-fix-passes <number>` changes the default limit of two
-repair passes.
-
-## Provenance and isolation
-
-`/sideroom` is dispatched to the extension before Pi expands skills or sends
-the command to the interactive agent. The extension then creates direct,
-in-memory SDK sessions for the five Sideroom roles. Those child sessions load
-only this package's skills and explicit policy; global Pi skills, extensions,
-prompt templates, and global context files are excluded.
-
-At the end of every run, Pi displays a `Sideroom completed` or `Sideroom
-failed` message with its provenance and the completed roles. It also records
-the same trace in Pi's session history as `sideroom:run`; this is Pi session
-metadata, never a file in the target repository.
-
-The packaged `sideroom-grilling` skill runs as the design-decision gate. Its
-questions use Pi's native decision UI. During a run, a persistent Pi widget
-shows the active phase, the waiting-for-answer state, and the direct-SDK
-provenance. Selecting a recommendation accepts it; selecting the alternate
-option opens a custom-answer field. The widget is removed automatically when a
-run completes or fails; the final Pi session message remains as the durable
-record. It is not a request to any global skill with the same name.
-
-## Content and guidelines
-
-The five role prompts are in `src/assets/agents/`. The shared policy is
-`src/assets/artifacts/GUIDELINES_TEMPLATE.md`; the language layers live in
-`src/assets/artifacts/guidelines/`. Implementer and fixer receive those
-policies before their write gate and must read them before every code-writing
-tool call.
-
-Reusable Pi skills ship in `skills/`: `sideroom-grilling`, `sideroom-critic`,
-`sideroom-spec`, and `sideroom-transcribe-audio`. Pi loads them directly through
-the package manifest.
-The transcription skill needs `uv`, Python, and `ffmpeg` only when explicitly
-used.
+## Details
+
+| Topic | Decision |
+| --- | --- |
+| Surface | Two LLM-callable tools: `sideroom_ask` and `sideroom_todo`. No `/sideroom` command. |
+| Questionnaire | One `sideroom_ask` call is one 1–N question batch; every question has `recommendationIndex`. |
+| Always-on rows | The questionnaire UI adds Out of scope and a custom answer. Do not send those options. |
+| Work board | `sideroom_todo propose` replaces a visible board; `update` patches items by id. |
+| Headless | `sideroom_todo update` works in print, JSON, and RPC. `propose` and `sideroom_ask` return `Error: UI not available` there. |
+| Edited files | Successful `write` and `edit` results appear below an active work board; `F8` opens the full list. |
+| Session state | The work board and edited-file history live in the Pi session branch, not in the target repository. |
+| Seed artifact | `assets/artifacts/GUIDELINES_TEMPLATE.md` ships unwired. |
+
+## Tool
+
+`sideroom_ask` follows Pi's questionnaire UI: a simple list for one question,
+tabs plus Submit for several. English copy. Each question needs:
+
+- `id`
+- `prompt`
+- at least two `{ value, label, description? }` options
+- `recommendationIndex` pointing at the recommended option
+- optional `label` for the tab bar (defaults to `Q1`, `Q2`, …)
+
+The recommended option is marked in the list. Escape cancels the batch.
+
+## Work board
+
+`sideroom_todo` keeps an ordered, display-only board above the editor. The
+agent maintains it and the user steers through chat. It never creates a
+repository task file or a `/todos` command.
+
+- `propose` replaces the full board and is available only in the interactive
+  TUI.
+- `update` applies one or more `{ id, status?, content? }` patches and works in
+  every Pi mode.
+- Items have stable string ids, short content, and one of `pending`,
+  `in_progress`, `completed`, or `cancelled`.
+- While items are pending, exactly one item must be `in_progress`. Complete the
+  current item and start the next one in the same update.
+- Snapshots are stored in the active session branch. The board is rebuilt after
+  session navigation and compaction.
+
+## Edited files
+
+The package automatically records successful Pi `write` and `edit` calls for
+the active session. It does not infer filesystem changes from shell commands,
+Git, people, or subagents. The compact list is shown below the work board when
+one is active and contains at most five recent paths.
+
+- `F8` opens or closes the extended, scrollable list; press `R` there
+  to clear the current session's history.
+- Every path is an OSC 8 `file://` link. Your terminal determines whether that
+  is a click, Ctrl+click, or another modifier-assisted action.
+- Paths outside the active project are labelled `external`.
+- A new session starts with a new list; the current session's history survives
+  reload, tree navigation, and compaction.
 
 ## Development
 
 ```bash
 npm install
 npm run check
-npm run build
 ```
 
-Biome is the sole formatter and linter. Runtime code uses Pi's SDK only; Pi
-provides `@earendil-works/pi-coding-agent` as a peer dependency.
+Biome is the sole formatter and linter. Pi loads TypeScript from `extensions/`
+directly; do not bundle. Pi provides `@earendil-works/pi-coding-agent`,
+`@earendil-works/pi-tui`, and `typebox` as peer dependencies.
 
 ## Releases and commits
 
 Commit messages must follow the Conventional Commits format. The existing
 Husky `commit-msg` hook validates each local commit with Commitlint, for
-example `feat: add a pipeline summary` or `fix: validate malformed findings`.
+example `feat: mark the recommended sideroom_ask option`.
 
 Every user-visible package change needs a Changeset. Create one with:
 
@@ -108,21 +118,31 @@ Every user-visible package change needs a Changeset. Create one with:
 npm run changeset
 ```
 
-Review pending release work with `npm run changeset:status`. On the release
-branch, run `npm run version-packages`, review and commit the updated
-`package.json`, `package-lock.json`, and `CHANGELOG.md`, then publish
-deliberately with `npm run release`. The repository does not publish
-automatically from CI.
+Review pending release work with `npm run changeset:status`. When Changesets
+are merged to `main`, the `Release` workflow creates or updates a reviewable
+Changesets version PR. That PR contains the generated `package.json`,
+`package-lock.json`, and `CHANGELOG.md` updates. Merge the version PR only after
+review; its merge runs `npm ci` and `npm run check`, then uses
+npm 11.5.1 and npm Trusted Publishing (GitHub OIDC) to publish. Changesets then
+pushes the release Git tag and creates the GitHub Release automatically.
+
+Never run `npm publish`, create release tags, or create GitHub Releases locally.
+Publishing is allowed only through the merged Changesets version PR and the
+`Release` workflow. The npm package's Trusted Publisher must be configured for
+this GitHub repository, the workflow filename `release.yml` (not its path),
+and the `npm` environment; configure the matching GitHub `npm` environment
+before the first release.
 
 ## Layout
 
 ```text
-src/
-  pi-extension.ts        Pi extension entry point for /sideroom
-  pi-command.ts          slash-command parsing
-  app.ts                 Pi pipeline assembly
-  core/                  orchestration, roles, contracts, and content catalog
-  runtimes/pi.ts         direct Pi SDK adapter for isolated child sessions
-  assets/                role prompts and coding guidelines
-skills/                  package-provided Pi skills
+extensions/
+  ask/                   sideroom_ask (index.ts, execute.ts, model.ts, ui.ts)
+  todo/                  sideroom_todo (index.ts, execute.ts, session.ts,
+                         guards.ts, model.ts, ui.ts)
+  modified-files/        session-backed edited-file tracker and view
+assets/artifacts/        unwired GUIDELINES_TEMPLATE.md seed
 ```
+
+Add another tool as `extensions/<name>/index.ts`. Pi discovers
+`extensions/*/index.ts`; helpers in that folder are not loaded as extensions.

package/{src/assets → assets}/artifacts/GUIDELINES_TEMPLATE.md

@@ -8,6 +8,7 @@ Each row is expanded, with examples, in the matching section below.
 
 | Do                                                 | Don't                                                                                       |
 | -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Use braces around every `if` body                  | Write an unbraced, single-statement conditional body                                       |
 | Early return on bad input                          | Pyramid `if/else` nesting                                                                   |
 | Explicit error, fail now                           | Multiple fallbacks that hide the real failure                                               |
 | One responsibility per unit                        | Validate + transform + persist + notify in one place                                        |
@@ -55,13 +56,26 @@ function getDiscount(user) {
 
 // Good — guard clauses, happy path at the end, shallow indent
 function getDiscount(user) {
-  if (!user) return 0;
-  if (!user.isActive) return 0;
-  if (!user.hasSubscription) return 0;
+  if (!user) {
+    return 0;
+  }
+  if (!user.isActive) {
+    return 0;
+  }
+  if (!user.hasSubscription) {
+    return 0;
+  }
   return 0.2;
 }
 ```
 
+### Braced conditionals
+
+Every `if` and `else` body must use braces in languages that support them,
+including a one-line guard clause. Never rely on indentation alone to bind a
+statement to a conditional. In Python, which has no braces, use a complete
+indented suite and never a one-line conditional body.
+
 ### Fail fast
 
 Invalid input, impossible state, or a broken dependency should fail immediately with a clear error. Prefer that over chains of fallbacks, silent defaults, or "keep going somehow."
@@ -78,7 +92,9 @@ function getShippingCost(order) {
 // Good — fails immediately with a clear error
 function getShippingCost(order) {
   const zone = ZONES[order.zoneId];
-  if (!zone) throw new Error(`Unknown zoneId: ${order.zoneId}`);
+  if (!zone) {
+    throw new Error(`Unknown zoneId: ${order.zoneId}`);
+  }
   return zone.baseCost;
 }
 ```
@@ -90,7 +106,9 @@ A function, class, or module has one reason to change. If it does two jobs, spli
 ```js
 // Bad — validates, transforms, persists, and notifies all in one place
 async function saveUser(data) {
-  if (!data.email) throw new Error('email required');
+  if (!data.email) {
+    throw new Error('email required');
+  }
   const normalized = { ...data, email: data.email.trim().toLowerCase() };
   await db.users.insert(normalized);
   await mailer.send(normalized.email, 'welcome');
@@ -98,7 +116,9 @@ async function saveUser(data) {
 
 // Good — each unit has a single reason to change
 function validateUser(data) {
-  if (!data.email) throw new Error('email required');
+  if (!data.email) {
+    throw new Error('email required');
+  }
 }
 function normalizeUser(data) {
   return { ...data, email: data.email.trim().toLowerCase() };
@@ -284,14 +304,22 @@ Pick one convention and apply it consistently: e.g. `undefined` for "not yet set
 ```js
 // Bad — null is overloaded to mean three different things
 function getDiscount(user) {
-  if (!user) return null; // no user
-  if (!user.plan) return null; // no plan
-  if (user.plan.discount === 0) return null; // legitimately zero discount
+  if (!user) {
+    return null; // no user
+  }
+  if (!user.plan) {
+    return null; // no plan
+  }
+  if (user.plan.discount === 0) {
+    return null; // legitimately zero discount
+  }
 }
 
 // Good — each case is explicit, zero is a real value
 function getDiscount(user) {
-  if (!user || !user.plan) return 0;
+  if (!user || !user.plan) {
+    return 0;
+  }
   return user.plan.discount;
 }
 ```
@@ -439,7 +467,8 @@ class UpdateProfileRequest extends FormRequest {
 }
 class ProfileService {
     public function update(array $data) {
-        if (empty($data['email'])) { // redundant re-validation
+        // Redundant re-validation.
+        if (empty($data['email'])) {
             throw new \InvalidArgumentException('email required');
         }
         $this->user->update($data);

package/extensions/ask/execute.ts

@@ -0,0 +1,56 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import {
+  type AskParams,
+  type AskQuestion,
+  type AskResult,
+  formatAnswerLines,
+  parseAskParams,
+  UI_UNAVAILABLE,
+} from './model.ts';
+import { runAskUi } from './ui.ts';
+
+interface AskToolResult {
+  readonly content: [{ readonly type: 'text'; readonly text: string }];
+  readonly details: AskResult;
+}
+
+export async function executeAsk(
+  params: AskParams,
+  ctx: Pick<ExtensionContext, 'mode' | 'ui'>,
+): Promise<AskToolResult> {
+  const parsed = parseAskParams(params);
+  if (!parsed.ok) {
+    return cancelledResult(parsed.message);
+  }
+  if (ctx.mode !== 'tui') {
+    return cancelledResult(UI_UNAVAILABLE, parsed.questions);
+  }
+
+  const result = await runAskUi(ctx.ui, parsed.questions);
+  if (result.cancelled) {
+    return {
+      content: [{ type: 'text', text: 'User cancelled the questionnaire' }],
+      details: result,
+    };
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: formatAnswerLines(parsed.questions, result.answers).join('\n'),
+      },
+    ],
+    details: result,
+  };
+}
+
+function cancelledResult(
+  message: string,
+  questions: readonly AskQuestion[] = [],
+): AskToolResult {
+  return {
+    content: [{ type: 'text', text: message }],
+    details: { questions, answers: [], cancelled: true },
+  };
+}

package/extensions/ask/index.ts

@@ -0,0 +1,77 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { executeAsk } from './execute.ts';
+import { AskParamsSchema, type AskResult, TOOL_NAME } from './model.ts';
+
+export const ASK_DESCRIPTION =
+  'Ask the user one or more questions. 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.';
+
+export const ASK_PROMPT_SNIPPET =
+  'Ask the user one or more questions with a recommended option.';
+
+export const ASK_PROMPT_GUIDELINES = [
+  'Use sideroom_ask to clarify requirements, preferences, or decisions with the user.',
+  'Each sideroom_ask question needs an id, a prompt, at least two options, and a recommendationIndex pointing at the recommended option.',
+  'sideroom_ask always adds Out of scope and a custom answer; do not include those options yourself.',
+  '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.',
+];
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerAsk(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: 'Sideroom Ask',
+    description: ASK_DESCRIPTION,
+    promptSnippet: ASK_PROMPT_SNIPPET,
+    promptGuidelines: ASK_PROMPT_GUIDELINES,
+    parameters: AskParamsSchema,
+    executionMode: 'sequential',
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) =>
+      executeAsk(params, ctx),
+    renderCall(args, theme) {
+      const questions = args.questions;
+      const count = questions.length;
+      const labels = questions
+        .map(
+          (question, index) =>
+            question.label || question.id || `Q${String(index + 1)}`,
+        )
+        .join(', ');
+      let text = theme.fg('toolTitle', theme.bold(`${TOOL_NAME} `));
+      text += theme.fg(
+        'muted',
+        `${String(count)} question${count !== 1 ? 's' : ''}`,
+      );
+      if (labels.length > 0) {
+        text += theme.fg('dim', ` (${labels})`);
+      }
+      return new Text(text, 0, 0);
+    },
+    renderResult(result, _options, theme) {
+      const details = result.details as AskResult | undefined;
+      if (details === undefined) {
+        const text = result.content[0];
+        return new Text(text?.type === 'text' ? text.text : '', 0, 0);
+      }
+      if (details.cancelled) {
+        return new Text(theme.fg('warning', 'Cancelled'), 0, 0);
+      }
+      const lines = details.answers.map((answer) => {
+        const mark = theme.fg('success', '✓ ');
+        const id = theme.fg('accent', answer.id);
+        if (answer.outOfScope) {
+          return `${mark}${id}: ${theme.fg('muted', '(out of scope)')}`;
+        }
+        if (answer.wasCustom) {
+          return `${mark}${id}: ${theme.fg('muted', '(wrote) ')}${answer.label}`;
+        }
+        if (answer.index !== undefined) {
+          return `${mark}${id}: ${String(answer.index)}. ${answer.label}`;
+        }
+        return `${mark}${id}: ${answer.label}`;
+      });
+      return new Text(lines.join('\n'), 0, 0);
+    },
+  });
+}

package/extensions/ask/model.ts

@@ -0,0 +1,196 @@
+import { type Static, Type } from 'typebox';
+import { Check, Errors } from 'typebox/value';
+
+export const TOOL_NAME = 'sideroom_ask';
+export const OUT_OF_SCOPE_VALUE = 'Out of scope';
+export const OUT_OF_SCOPE_LABEL = 'Out of scope';
+export const CUSTOM_VALUE = '__other__';
+export const CUSTOM_LABEL = 'Write a custom answer';
+export const UI_UNAVAILABLE =
+  'Error: UI not available (running in non-interactive mode)';
+
+const QuestionOptionSchema = Type.Object({
+  value: Type.String({ description: 'The value returned when selected' }),
+  label: Type.String({ description: 'Display label for the option' }),
+  description: Type.Optional(
+    Type.String({ description: 'Optional description shown below the label' }),
+  ),
+});
+
+const QuestionSchema = Type.Object({
+  id: Type.String({ description: 'Unique identifier for this question' }),
+  label: Type.Optional(
+    Type.String({
+      description:
+        "Short contextual label for the tab bar, e.g. 'Scope' (defaults to Q1, Q2)",
+    }),
+  ),
+  prompt: Type.String({ description: 'The full question text to display' }),
+  options: Type.Array(QuestionOptionSchema, {
+    minItems: 2,
+    description: 'At least two mutually exclusive options',
+  }),
+  recommendationIndex: Type.Integer({
+    minimum: 0,
+    description: 'Index into options pointing at the recommended option',
+  }),
+});
+
+export const AskParamsSchema = Type.Object({
+  questions: Type.Array(QuestionSchema, {
+    minItems: 1,
+    description: 'Questions to ask the user in this batch',
+  }),
+});
+
+export type AskParams = Static<typeof AskParamsSchema>;
+export type QuestionOption = AskParams['questions'][number]['options'][number];
+
+export interface AskQuestion {
+  readonly id: string;
+  readonly label: string;
+  readonly prompt: string;
+  readonly options: readonly QuestionOption[];
+  readonly recommendationIndex: number;
+}
+
+export interface AskAnswer {
+  readonly id: string;
+  readonly value: string;
+  readonly label: string;
+  readonly wasCustom: boolean;
+  readonly outOfScope: boolean;
+  readonly index?: number;
+}
+
+export interface AskResult {
+  readonly questions: readonly AskQuestion[];
+  readonly answers: readonly AskAnswer[];
+  readonly cancelled: boolean;
+}
+
+export type RenderOption = QuestionOption & {
+  readonly isOther?: boolean;
+  readonly isOutOfScope?: boolean;
+  readonly isRecommended?: boolean;
+};
+
+export type ParseAskResult =
+  | { readonly ok: true; readonly questions: readonly AskQuestion[] }
+  | { readonly ok: false; readonly message: string };
+
+export function parseAskParams(value: unknown): ParseAskResult {
+  if (!Check(AskParamsSchema, value)) {
+    return { ok: false, message: schemaErrorMessage(value) };
+  }
+
+  const seen = new Set<string>();
+  for (const question of value.questions) {
+    if (seen.has(question.id)) {
+      return {
+        ok: false,
+        message: `Error: Duplicate question id: ${question.id}`,
+      };
+    }
+    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}'`,
+      };
+    }
+  }
+
+  return { ok: true, questions: normalizeQuestions(value.questions) };
+}
+
+export function normalizeQuestions(
+  questions: AskParams['questions'],
+): AskQuestion[] {
+  return questions.map((question, index) => {
+    const label = question.label;
+    return {
+      id: question.id,
+      label:
+        label !== undefined && label.trim().length > 0
+          ? label
+          : `Q${String(index + 1)}`,
+      prompt: question.prompt,
+      options: question.options,
+      recommendationIndex: question.recommendationIndex,
+    };
+  });
+}
+
+export function renderOptions(question: AskQuestion): RenderOption[] {
+  const options: RenderOption[] = question.options.map((option, index) => ({
+    ...option,
+    isRecommended: index === question.recommendationIndex,
+  }));
+  options.push({
+    value: OUT_OF_SCOPE_VALUE,
+    label: OUT_OF_SCOPE_LABEL,
+    isOutOfScope: true,
+  });
+  options.push({
+    value: CUSTOM_VALUE,
+    label: CUSTOM_LABEL,
+    isOther: true,
+  });
+  return options;
+}
+
+export function formatAnswerLines(
+  questions: readonly AskQuestion[],
+  answers: readonly AskAnswer[],
+): string[] {
+  return answers.map((answer) => {
+    const question = questions.find((entry) => entry.id === answer.id);
+    const questionLabel = question?.label ?? answer.id;
+    if (answer.outOfScope) {
+      return `${questionLabel}: Out of scope`;
+    }
+    if (answer.wasCustom) {
+      return `${questionLabel}: user wrote: ${answer.label}`;
+    }
+    if (answer.index !== undefined) {
+      return `${questionLabel}: user selected: ${String(answer.index)}. ${answer.label}`;
+    }
+    return `${questionLabel}: user selected: ${answer.label}`;
+  });
+}
+
+function schemaErrorMessage(value: unknown): string {
+  const [error] = Errors(AskParamsSchema, value);
+  if (error === undefined) {
+    return 'Error: Invalid sideroom_ask parameters';
+  }
+  if (error.keyword === 'minItems' && error.instancePath === '/questions') {
+    return 'Error: No questions provided';
+  }
+  const optionsMatch = /\/questions\/(\d+)\/options$/.exec(error.instancePath);
+  if (error.keyword === 'minItems' && optionsMatch !== null) {
+    const questionIndex = Number(optionsMatch[1]);
+    const questions = asQuestions(value);
+    const question = questions[questionIndex];
+    const id =
+      question !== undefined && typeof question.id === 'string'
+        ? question.id
+        : String(questionIndex);
+    return `Error: Question '${id}' must include at least two options`;
+  }
+  return `Error: Invalid sideroom_ask parameters`;
+}
+
+function asQuestions(value: unknown): readonly Record<string, unknown>[] {
+  if (typeof value !== 'object' || value === null) {
+    return [];
+  }
+  if (!('questions' in value) || !Array.isArray(value.questions)) {
+    return [];
+  }
+  return value.questions.filter(
+    (question): question is Record<string, unknown> =>
+      typeof question === 'object' && question !== null,
+  );
+}