@agentprojectcontext/apx 1.31.2 → 1.32.0

package/src/host/daemon/plugins/telegram.js

@@ -43,6 +43,7 @@ import { registerSender, resolveAllowedTools } from "../../../core/telegram-iden
 import { buildRelationshipBlock } from "../../../core/agent/index.js";
 import { getConfirmationStore as getConfirmStore } from "../../../core/confirmation/pending-store.js";
 import { createTelegramConfirmAdapter } from "../../../core/confirmation/adapters/telegram.js";
+import * as askFlow from "./telegram-ask.js";
 
 const API_BASE = "https://api.telegram.org";
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -577,6 +578,30 @@ class ChannelPoller {
       text = text ? `${audioBody}\n${text}` : audioBody;
     }
 
+    // If there's a pending ask_questions flow for this chat AND the current
+    // question is free-text, treat this message as the answer rather than a
+    // brand-new turn. Returns true when the message was consumed.
+    if (chat_id && text && await this._maybeConsumeAskTextAnswer({ chat_id, text })) {
+      // Still log the inbound so the chat history records what the user said.
+      appendGlobalMessage({
+        channel: "telegram",
+        direction: "in",
+        type: "user",
+        actor_id: msg.from?.id ? String(msg.from.id) : author,
+        external_id: String(u.update_id),
+        author,
+        body: text,
+        meta: {
+          chat_id,
+          user_id: msg.from?.id || null,
+          message_id: msg.message_id,
+          tg_channel: this.channel.name,
+          ask_answer: true,
+        },
+      });
+      return;
+    }
+
     // /reset or /new wipes the rolling context for this chat. We just
     // remember a marker timestamp; subsequent inbounds will only consider
     // history newer than this. Implemented by writing a synthetic message
@@ -848,6 +873,35 @@ class ChannelPoller {
         replyActorId = SUPERAGENT_ACTOR_ID;
         replyKind = "superagent";
         saUsage = sa.usage;
+
+        // ── ask_questions integration ────────────────────────────────────
+        // If the super-agent ended this turn by calling ask_questions, hand
+        // off to the inline-keyboard flow instead of sending the bare
+        // assistant text. The flow keeps state per chat_id and re-runs the
+        // super-agent once every answer is collected.
+        const askQuestions = askFlow.extractAskQuestionsFromTrace(sa.trace);
+        if (askQuestions && chat_id) {
+          if (chat_id) this.activeRequests.delete(chat_id);
+          stopTyping();
+          try {
+            await this._startAskFlow({
+              chat_id,
+              projectId: target?.id,
+              authorId: msg.from?.id,
+              questions: askQuestions,
+              author,
+              agentDisplay,
+              relationshipBlock,
+              allowedTools,
+              target,
+              sender,
+              update_id: u.update_id,
+            });
+          } catch (e) {
+            this.log(`telegram[${this.channel.name}] ask flow start failed: ${e.message}`);
+          }
+          return; // The reply for this turn IS the ask flow.
+        }
       } catch (e) {
         if (abortCtrl.signal.aborted) {
           // A newer message superseded this one. Whatever streamed so far is
@@ -928,6 +982,14 @@ class ChannelPoller {
   }
 
   async _handleCallbackQuery(callbackQuery) {
+    // Route ask_questions button presses before the confirmation adapter —
+    // both use `apx:<verb>:...` namespacing but ask owns its own state.
+    const data = callbackQuery.data || "";
+    if (data.startsWith("apx:ask:")) {
+      await this._handleAskCallback(callbackQuery);
+      return;
+    }
+
     const adapter = createTelegramConfirmAdapter({
       token: resolveBotToken(this.channel),
       chatId: callbackQuery.message?.chat?.id,
@@ -939,6 +1001,230 @@ class ChannelPoller {
     }
   }
 
+  // ── ask_questions: state-machine helpers ───────────────────────────────
+  // The flow lives in telegram-ask.js; this class owns the I/O (sending
+  // messages, editing keyboards, re-entering the super-agent loop with the
+  // compiled answer once the flow finishes).
+
+  async _renderQuestion(state) {
+    const text = askFlow.formatQuestionText(state);
+    const reply_markup = askFlow.buildKeyboard(state);
+    // If we already have a message for the previous question, leave its
+    // keyboard wiped — we draw a fresh message per question for clearer
+    // history in the chat (the question text stays as a record).
+    if (state.messageId) {
+      try {
+        await this._editKeyboard({
+          chat_id: state.chatId,
+          message_id: state.messageId,
+          reply_markup: { inline_keyboard: [] },
+        });
+      } catch { /* best-effort */ }
+    }
+    const sent = await this._send({
+      chat_id: state.chatId,
+      text,
+      reply_markup,
+      parse_mode: "Markdown",
+    });
+    state.messageId = sent?.message_id || null;
+    askFlow.saveState(state.chatId, state);
+  }
+
+  // Kick off a brand-new ask flow after the super-agent called ask_questions.
+  // The flow's `resume` callback captures the per-turn context (sender,
+  // relationship, project) so when the compiled answer arrives we can run
+  // another super-agent turn without retyping all the inputs.
+  async _startAskFlow(ctx) {
+    const state = askFlow.startFlow({
+      chatId: ctx.chat_id,
+      projectId: ctx.projectId,
+      authorId: ctx.authorId,
+      questions: ctx.questions,
+      resume: async (compiled) => {
+        await this._runResumedTurn({ ...ctx, compiled });
+      },
+    });
+    await this._renderQuestion(state);
+  }
+
+  // Apply an inline-keyboard press, then react: redraw, advance, or finish.
+  async _handleAskCallback(callbackQuery) {
+    const chatId = callbackQuery.message?.chat?.id;
+    if (!chatId) return;
+    const result = askFlow.applyCallback(chatId, callbackQuery.data || "");
+    // Ack the press regardless — keeps the spinner from hanging client-side.
+    await this._answerCallback({ callback_query_id: callbackQuery.id });
+    if (!result) return; // stale or unknown — adapter already ack'd.
+
+    if (result.action === "redraw") {
+      // Multi-select toggle: just refresh the keyboard on the SAME message.
+      try {
+        await this._editKeyboard({
+          chat_id: chatId,
+          message_id: callbackQuery.message?.message_id,
+          reply_markup: askFlow.buildKeyboard(result.state),
+        });
+      } catch (e) {
+        this.log(`telegram[${this.channel.name}] redraw failed: ${e.message}`);
+      }
+      return;
+    }
+    if (result.action === "advance") {
+      await this._renderQuestion(result.state);
+      return;
+    }
+    if (result.action === "cancel") {
+      try {
+        await this._editKeyboard({
+          chat_id: chatId,
+          message_id: callbackQuery.message?.message_id,
+          reply_markup: { inline_keyboard: [] },
+        });
+        await this._send({ chat_id: chatId, text: "Pregunta cancelada." });
+      } catch { /* best-effort */ }
+      return;
+    }
+    if (result.action === "done") {
+      try {
+        await this._editKeyboard({
+          chat_id: chatId,
+          message_id: callbackQuery.message?.message_id,
+          reply_markup: { inline_keyboard: [] },
+        });
+      } catch { /* best-effort */ }
+      // Feed the compiled answer back as a synthetic user turn.
+      if (typeof result.state.resume === "function") {
+        await result.state.resume(result.compiled);
+      }
+    }
+  }
+
+  // Apply a free-text user reply when there's a pending free-text question.
+  // Returns true iff the message was consumed by the ask flow (so the normal
+  // super-agent path should be skipped for this update).
+  async _maybeConsumeAskTextAnswer({ chat_id, text }) {
+    if (!chat_id || !text) return false;
+    if (!askFlow.hasPendingFreeText(chat_id)) return false;
+    const state = askFlow.applyTextAnswer(chat_id, text);
+    if (!state) return false;
+    // Advance: emit a synthetic "next" to move past this question.
+    const next = askFlow.applyCallback(
+      chat_id,
+      `apx:ask:${state.correlationId}:next`,
+    );
+    if (!next) return true;
+    if (next.action === "advance") {
+      await this._renderQuestion(next.state);
+      return true;
+    }
+    if (next.action === "done") {
+      if (typeof next.state.resume === "function") {
+        await next.state.resume(next.compiled);
+      }
+      return true;
+    }
+    return true;
+  }
+
+  // Run a follow-up super-agent turn with the compiled answers as the user
+  // prompt. Mirrors the post-runSuperAgent reply path in _handleUpdate but
+  // skipped of the photo/audio/reset preamble. Re-enters the ask flow if the
+  // model decides to ask again.
+  async _runResumedTurn(ctx) {
+    const { chat_id, compiled, target, relationshipBlock, allowedTools, author, agentDisplay, update_id, sender, authorId } = ctx;
+    if (!chat_id) return;
+    // Log the synthetic user message so getRecentTelegramTurnsFromFs picks
+    // it up on the NEXT inbound. Mirrors how a normal text reply would be
+    // recorded.
+    appendGlobalMessage({
+      channel: "telegram",
+      direction: "in",
+      type: "user",
+      actor_id: authorId ? String(authorId) : (author || "ask_flow"),
+      external_id: `ask-${Date.now()}`,
+      author: author || "user",
+      body: compiled,
+      meta: {
+        chat_id,
+        user_id: authorId || null,
+        tg_channel: this.channel.name,
+        ask_flow: true,
+      },
+    });
+
+    const previousMessages = getRecentTelegramTurnsFromFs({
+      chat_id,
+      keepRecent: 40,
+      max_age_hours: 24,
+    });
+
+    const stopTyping = this._startTyping(chat_id);
+    try {
+      const sa = await runSuperAgent({
+        globalConfig: this.globalConfig,
+        projects: this.projects,
+        plugins: this.plugins,
+        registries: this.registries,
+        prompt: compiled,
+        previousMessages,
+        channel: "telegram",
+        relationshipBlock,
+        allowedTools,
+        channelMeta: { channel: "telegram", chat_id, author, route_to_agent: this.channel.route_to_agent },
+      });
+      stopTyping();
+
+      // Did the model ask again? Restart the flow instead of replying.
+      const followupAsk = askFlow.extractAskQuestionsFromTrace(sa.trace);
+      if (followupAsk) {
+        await this._startAskFlow({
+          chat_id,
+          projectId: target?.id,
+          authorId,
+          questions: followupAsk,
+          author,
+          agentDisplay,
+          relationshipBlock,
+          allowedTools,
+          target,
+          sender,
+          update_id,
+        });
+        return;
+      }
+
+      const replyText = sa.text ? stripThinking(sa.text).trim() : "";
+      if (replyText) {
+        await this._send({ chat_id, text: replyText });
+        appendGlobalMessage({
+          channel: "telegram",
+          direction: "out",
+          type: "agent",
+          actor_id: SUPERAGENT_ACTOR_ID,
+          actor_kind: "superagent",
+          agent_slug: SUPERAGENT_ACTOR_ID,
+          author: sa.name || agentDisplay,
+          body: replyText,
+          meta: {
+            chat_id,
+            tg_channel: this.channel.name,
+            in_reply_to: update_id,
+            final: true,
+            ask_resume: true,
+            ...(sa.usage ? { usage: sa.usage } : {}),
+          },
+        });
+      }
+    } catch (e) {
+      stopTyping();
+      this.log(`telegram[${this.channel.name}] ask resume failed: ${e.message}`);
+      try {
+        await this._send({ chat_id, text: `⚠️ Error procesando tus respuestas (${e.message}).` });
+      } catch { /* best-effort */ }
+    }
+  }
+
   // Show "typing..." indicator in the chat. Telegram clears it automatically
   // after 5 seconds, so call this every ~4s while a long operation is going.
   async _typing(chat_id) {
@@ -971,22 +1257,64 @@ class ChannelPoller {
     return () => { stopped = true; };
   }
 
-  async _send({ chat_id, text }) {
+  async _send({ chat_id, text, reply_markup, parse_mode }) {
     const token = resolveBotToken(this.channel);
     if (!token) throw new Error(`channel ${this.channel.name}: no bot_token`);
     const target = chat_id || resolveChatId(this.channel);
     if (!target) throw new Error(`channel ${this.channel.name}: no chat_id`);
     const url = `${API_BASE}/bot${token}/sendMessage`;
+    const body = { chat_id: target, text };
+    if (reply_markup) body.reply_markup = reply_markup;
+    if (parse_mode) body.parse_mode = parse_mode;
     const res = await fetch(url, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ chat_id: target, text }),
+      body: JSON.stringify(body),
     });
     const json = await res.json();
     if (!json.ok) throw new Error(json.description || `send failed (${res.status})`);
     return json.result;
   }
 
+  // Replace just the inline keyboard on a previously-sent message (used to
+  // refresh after a multi-select toggle, or to wipe buttons once the flow
+  // has moved on). Best-effort: failures are logged but don't break the flow.
+  async _editKeyboard({ chat_id, message_id, reply_markup }) {
+    const token = resolveBotToken(this.channel);
+    if (!token) return;
+    try {
+      const url = `${API_BASE}/bot${token}/editMessageReplyMarkup`;
+      const body = { chat_id, message_id };
+      if (reply_markup) body.reply_markup = reply_markup;
+      await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      });
+    } catch (e) {
+      this.log(`telegram[${this.channel.name}] editMessageReplyMarkup failed: ${e.message}`);
+    }
+  }
+
+  // Acknowledge a callback button press so the user's Telegram client clears
+  // the spinner on the tapped button. Optional `text` shows a small toast.
+  async _answerCallback({ callback_query_id, text }) {
+    const token = resolveBotToken(this.channel);
+    if (!token) return;
+    try {
+      const url = `${API_BASE}/bot${token}/answerCallbackQuery`;
+      const body = { callback_query_id };
+      if (text) body.text = text;
+      await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      });
+    } catch (e) {
+      this.log(`telegram[${this.channel.name}] answerCallbackQuery failed: ${e.message}`);
+    }
+  }
+
   /** Send a photo via this channel */
   async _sendPhoto({ chat_id, photo, caption, parse_mode }) {
     const token = resolveBotToken(this.channel);

package/src/host/daemon/super-agent-tools/tools/ask-questions.js

@@ -1,3 +1,38 @@
+// Normalize a raw question entry into the canonical shape rendered by every
+// surface (web InlineAskPanel, future desktop/telegram/CLI). The model can
+// pass either a plain string (legacy) or a rich object with options.
+function normalizeQuestion(q) {
+  if (typeof q === "string") {
+    return { question: q, options: [], multiSelect: false, allowText: true };
+  }
+  if (!q || typeof q !== "object") return null;
+  const text = typeof q.question === "string" ? q.question : "";
+  if (!text) return null;
+  const options = Array.isArray(q.options)
+    ? q.options
+        .map((o) => {
+          if (typeof o === "string") return { label: o };
+          if (o && typeof o === "object" && typeof o.label === "string") {
+            return {
+              label: o.label,
+              description: typeof o.description === "string" ? o.description : undefined,
+            };
+          }
+          return null;
+        })
+        .filter(Boolean)
+    : [];
+  return {
+    question: text,
+    header: typeof q.header === "string" ? q.header : undefined,
+    options,
+    multiSelect: q.multiSelect === true,
+    // Free-text fallback: on by default. Set false explicitly to force a
+    // pick from `options`. Has no effect when options is empty.
+    allowText: q.allowText === false ? false : true,
+  };
+}
+
 export default {
   name: "ask_questions",
   schema: {
@@ -7,26 +42,74 @@ export default {
     type: "function",
     function: {
       name: "ask_questions",
-      description: "Ask the user one or more specific questions to clarify the task or gather requirements.",
+      description:
+        "Ask the user one or more questions when you genuinely need input to proceed. " +
+        "Each question can be free-text OR a selectable list of options (single- or multi-select). " +
+        "Call this ONCE per turn — the loop hands control back to the user immediately.",
       parameters: {
         type: "object",
         properties: {
           questions: {
             type: "array",
-            items: { type: "string" },
-            description: "A list of questions for the user."
-          }
+            description:
+              "Questions for the user. Each item is an object with the question text " +
+              "and optional `options` for selectable answers (single- or multi-select). " +
+              "Leave `options` empty for free-text questions.",
+            items: {
+              type: "object",
+              properties: {
+                question: { type: "string", description: "The question text." },
+                header: {
+                  type: "string",
+                  description: "Optional short chip (≤12 chars) shown next to the question.",
+                },
+                options: {
+                  type: "array",
+                  description:
+                    "Selectable answers. Omit or leave empty for a free-text question. " +
+                    "Prefer 2–4 distinct, mutually-exclusive choices.",
+                  items: {
+                    type: "object",
+                    properties: {
+                      label: { type: "string", description: "Visible label." },
+                      description: {
+                        type: "string",
+                        description: "Optional explanation shown under the label.",
+                      },
+                    },
+                    required: ["label"],
+                  },
+                },
+                multiSelect: {
+                  type: "boolean",
+                  description:
+                    "true → user can pick several options (checkboxes). Default false (single-select).",
+                },
+                allowText: {
+                  type: "boolean",
+                  description:
+                    "When options is non-empty, also show an 'Otro' free-text field. Default true.",
+                },
+              },
+              required: ["question"],
+            },
+          },
         },
-        required: ["questions"]
-      }
-    }
+        required: ["questions"],
+      },
+    },
   },
   makeHandler: () => async ({ questions }) => {
-    // This tool is used by the agent to explicitly signal that it is waiting for 
-    // answers to specific questions. The UI can then highlight these.
-    return { 
-      status: "Questions presented to user. Waiting for input.", 
-      count: questions.length 
+    // Normalize so downstream code (UI panels, persistence) always sees the
+    // canonical shape. The agent loop treats this tool as turn-ending
+    // (see TURN_ENDING_TOOLS in src/core/agent/constants.js).
+    const normalized = Array.isArray(questions)
+      ? questions.map(normalizeQuestion).filter(Boolean)
+      : [];
+    return {
+      status: "Questions presented to user. Waiting for input.",
+      count: normalized.length,
+      questions: normalized,
     };
-  }
+  },
 };

package/src/interfaces/cli/commands/artifact.js

@@ -1,6 +1,40 @@
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import path from "node:path";
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
 
+// First two bytes of an executable script. Used as a hint when the file
+// doesn't have the exec bit but clearly intends to run (shebang line).
+const SHEBANG = "#!";
+
+// Decide if an artifact is "runnable": exec bit on the file, OR the file
+// starts with a shebang. If shebang-but-not-exec, we set the bit before
+// spawning so `./script` works without the user having to chmod +x.
+function detectRunnable(absPath) {
+  let stat;
+  try {
+    stat = fs.statSync(absPath);
+  } catch {
+    return { runnable: false, reason: "not_found" };
+  }
+  if (!stat.isFile()) return { runnable: false, reason: "not_a_file" };
+  const execBit = (stat.mode & 0o111) !== 0;
+  let hasShebang = false;
+  try {
+    const fd = fs.openSync(absPath, "r");
+    const buf = Buffer.alloc(2);
+    fs.readSync(fd, buf, 0, 2, 0);
+    fs.closeSync(fd);
+    hasShebang = buf.toString("utf8") === SHEBANG;
+  } catch {
+    // ignore: hasShebang stays false
+  }
+  if (execBit) return { runnable: true, reason: "exec_bit", autoChmod: false };
+  if (hasShebang) return { runnable: true, reason: "shebang", autoChmod: true };
+  return { runnable: false, reason: "no_exec_no_shebang" };
+}
+
 export async function cmdArtifactCreate(args) {
   const name = args._[0];
   if (!name) throw new Error("apx artifact create: missing <name>");
@@ -43,3 +77,68 @@ export async function cmdArtifactRemove(args) {
   await http.delete(`/projects/${pid}/artifacts/${encodeURIComponent(name)}`);
   console.log(`removed artifact "${name}"`);
 }
+
+// `apx artifact run <name> [-- args...]`
+//
+// Resolves the artifact's absolute path via the daemon (single source of
+// truth for project storage), then spawns the file LOCALLY with stdio
+// inherited so the caller sees output as if they typed `./artifact <args>`.
+// Detection is lenient: exec bit OR shebang → runnable; shebang-only files
+// get a one-shot chmod +x so the user doesn't have to do it themselves.
+//
+// The remaining argv after `run <name>` is passed straight to the script,
+// so `apx artifact run hello.sh -- hola mundo` becomes `./hello.sh hola mundo`.
+export async function cmdArtifactRun(args) {
+  const name = args._[0];
+  if (!name) throw new Error("apx artifact run: missing <name>");
+  const pid = await resolveProjectId(args?.flags?.project);
+  // Pull the artifact record from the daemon for the absolute path.
+  let entry;
+  try {
+    entry = await http.get(`/projects/${pid}/artifacts/${encodeURIComponent(name)}`);
+  } catch (e) {
+    throw new Error(`artifact "${name}" not found in project #${pid}: ${e.message}`);
+  }
+  const absPath = entry.path;
+  if (!absPath || !fs.existsSync(absPath)) {
+    throw new Error(`artifact "${name}" path missing on disk: ${absPath}`);
+  }
+
+  const detection = detectRunnable(absPath);
+  if (!detection.runnable) {
+    const hint = detection.reason === "no_exec_no_shebang"
+      ? "no es ejecutable (sin shebang ni bit +x). Probá `apx artifact show` para ver el contenido."
+      : `no se puede ejecutar (${detection.reason}).`;
+    throw new Error(`artifact "${name}" ${hint}`);
+  }
+  if (detection.autoChmod) {
+    try {
+      const st = fs.statSync(absPath);
+      fs.chmodSync(absPath, st.mode | 0o111);
+    } catch (e) {
+      throw new Error(`could not chmod +x ${absPath}: ${e.message}`);
+    }
+  }
+
+  // Everything after the artifact name is forwarded to the script. The CLI's
+  // argv parser already strips top-level flags; what's left in `_` is name
+  // + script args.
+  const scriptArgs = (args._ || []).slice(1);
+  const cwd = path.dirname(absPath);
+  const child = spawn(absPath, scriptArgs, { stdio: "inherit", cwd });
+
+  await new Promise((resolve) => {
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        // Killed by signal — surface a non-zero exit for shell pipelines.
+        process.exit(128 + (signal === "SIGINT" ? 2 : 15));
+      }
+      process.exit(code ?? 0);
+    });
+    child.on("error", (err) => {
+      console.error(`apx artifact run: spawn failed — ${err.message}`);
+      resolve();
+      process.exit(1);
+    });
+  });
+}

package/src/interfaces/cli/index.js

@@ -125,6 +125,7 @@ import {
   cmdArtifactList,
   cmdArtifactShow,
   cmdArtifactRemove,
+  cmdArtifactRun,
 } from "./commands/artifact.js";
 import {
   cmdTaskAdd,
@@ -1273,12 +1274,14 @@ const HELP_TOPICS = new Map(Object.entries({
       ["create <name>", "Create a new empty artifact. Prints its absolute path."],
       ["list | ls", "List artifacts in the project."],
       ["show <name>", "Print artifact content."],
+      ["run <name> [args...]", "Execute a runnable artifact (shebang or +x). Stdio is inherited."],
       ["remove | rm <name>", "Delete an artifact."],
     ],
     examples: [
       "apx artifact create check_asana.sh --project 0",
       "apx artifact list",
       "apx artifact show check_asana.sh",
+      "apx artifact run check_asana.sh",
     ],
   }),
   "artifact create": topic({
@@ -2490,6 +2493,7 @@ async function dispatch(cmd, rest) {
         else if (sub === "create" || sub === "new") await cmdArtifactCreate(a);
         else if (sub === "show" || sub === "get") await cmdArtifactShow(a);
         else if (sub === "remove" || sub === "rm") await cmdArtifactRemove(a);
+        else if (sub === "run") await cmdArtifactRun(a);
         else die(`unknown artifact subcommand: ${sub}`);
         break;
       }

package/src/interfaces/cli/terminal-chat/renderer.js

@@ -326,11 +326,31 @@ function transcriptLines(transcript, width) {
       if (isQuestion && trace.args?.questions) {
         addLine(lines, "", C.bg);
         addLine(lines, margin + label + C.muted + " (…)" + C.bg, C.bg);
-        for (const q of trace.args.questions) {
-          const qWrapped = wrapText(`• ${q}`, inner - 2);
+        for (const rawQ of trace.args.questions) {
+          // Rich shape: {question, options[], multiSelect, allowText}. Legacy: string.
+          const q = typeof rawQ === "string" ? { question: rawQ } : (rawQ || {});
+          const qText = typeof q.question === "string" ? q.question : "";
+          if (!qText) continue;
+          const qWrapped = wrapText(`• ${qText}`, inner - 2);
           for (const line of qWrapped) {
             addLine(lines, margin + C.primary + "┃ " + C.text + padAnsi(line, inner - 2), C.bg);
           }
+          const opts = Array.isArray(q.options) ? q.options : [];
+          if (opts.length > 0) {
+            const marker = q.multiSelect ? "[ ]" : "( )";
+            opts.forEach((opt, i) => {
+              const label = (opt && typeof opt === "object" && typeof opt.label === "string")
+                ? opt.label
+                : (typeof opt === "string" ? opt : "");
+              if (!label) return;
+              const desc = (opt && typeof opt === "object" && typeof opt.description === "string")
+                ? ` — ${opt.description}` : "";
+              const optLine = `   ${marker} ${i + 1}. ${label}${desc}`;
+              for (const line of wrapText(optLine, inner - 2)) {
+                addLine(lines, margin + C.primary + "┃ " + C.muted + padAnsi(line, inner - 2), C.bg);
+              }
+            });
+          }
         }
       } else {
         addLine(lines, margin + label + " " + name + C.bg, C.bg);