@alia.onl/sdk 11.0.0 → 11.1.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @alia.onl/sdk
 
+## 11.1.0
+
+Alia can ask clarifying questions, as ChatGPT and Claude do.
+
+- **New:** `QuestionCard` (Bloom's `Questionnaire`: single or multiple choice, a free-text
+  "Other", one question per step), drawn under a reply that asked. `AliaChatMessageList`
+  renders it from the turn's `askUserQuestion` tool call; `AliaChatContent` sends the
+  answers as the person's next message (`onAnswerQuestions` on the list, for hosts that
+  compose their own).
+- **New, pure** (root entry and `@alia.onl/sdk/tools`): `askedQuestions`, `formatAnswers`,
+  `isQuestionInvocation`, `ASK_USER_QUESTION_TOOL`. The question is the stored tool call, so
+  it survives a reload; it is answered once any later message exists, typed or picked.
+- The turn **ends** at the card: the server stops after the call and writes no answer under it.
+
 ## 11.0.0
 
 The chat UI is Bloom's, not a copy of it. Breaking:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "11.0.0",
+  "version": "11.1.0",
   "description": "Alia AI chat SDK — reusable chat UI, voice, and streaming components for Oxy apps",
   "main": "src/index.ts",
   "react-native": "src/index.ts",

package/src/components/AliaChatContent.tsx

@@ -404,6 +404,7 @@ function AliaChatContentBody({
             onThumbsDown={onThumbsDown}
             onApprovePlan={onApprovePlan}
             onRejectPlan={onRejectPlan}
+            onAnswerQuestions={(message) => send(message)}
             renderMarkdown={renderMarkdown}
             welcomeComponent={welcomeComponent}
           />

package/src/components/AliaChatMessageList.tsx

@@ -33,6 +33,8 @@ import {
 } from '@oxy.so/bloom/icons';
 import { ThinkingBlock } from './ThinkingBlock';
 import { PlanPreviewCard } from './PlanPreviewCard';
+import { QuestionCard } from './QuestionCard';
+import { askedQuestions, isQuestionInvocation } from '../lib/questions';
 import { chatMessageEnter } from '../animations';
 import { getToolLabel, getToolActiveLabel, getResearchActiveLabel } from '../lib/tool-registry';
 import { getTextFromContent, getImagesFromContent } from '../lib/content-utils';
@@ -67,6 +69,8 @@ export interface AliaChatMessageListProps {
   onThumbsDown?: (messageId: string) => void;
   onApprovePlan?: (planId: string) => void;
   onRejectPlan?: (planId: string) => void;
+  /** Sends the answers to Alia's questions as the person's next message. */
+  onAnswerQuestions?: (message: string) => void;
   // Welcome
   welcomeComponent?: React.ReactNode;
   // Markdown renderer override (app passes CustomMarkdown, SDK uses AliaMarkdown)
@@ -188,6 +192,7 @@ const AssistantMessage = React.memo(function AssistantMessage({
   onThumbsDown,
   onApprovePlan,
   onRejectPlan,
+  onAnswerQuestions,
   renderMarkdown,
 }: {
   message: ChatMessage;
@@ -203,6 +208,7 @@ const AssistantMessage = React.memo(function AssistantMessage({
   onThumbsDown?: (messageId: string) => void;
   onApprovePlan?: (planId: string) => void;
   onRejectPlan?: (planId: string) => void;
+  onAnswerQuestions?: (message: string) => void;
   renderMarkdown?: (content: string) => React.ReactNode;
 }) {
   const labels = useLabels();
@@ -217,8 +223,16 @@ const AssistantMessage = React.memo(function AssistantMessage({
     () => webSearchLog(toolInvocations, researchProgress, { t: labels.workLog }),
     [toolInvocations, researchProgress, labels.workLog],
   );
+  // The questions Alia asked, drawn as a card. Answerable only on the last message once the
+  // turn is over; any later message (typed or sent from the card) is the answer.
+  const questions = useMemo(
+    () => (toolInvocations ?? []).flatMap((inv) => askedQuestions(inv) ?? []),
+    [toolInvocations],
+  );
   const taskLog = useMemo(() => {
-    const tasks = (toolInvocations ?? []).filter((inv) => !isWebInvocation(inv));
+    const tasks = (toolInvocations ?? []).filter(
+      (inv) => !isWebInvocation(inv) && !isQuestionInvocation(inv),
+    );
     return tasks.length === 0 || isStreamingThis
       ? null
       : taskListLog(tasks, false, { t: labels.workLog });
@@ -338,6 +352,16 @@ const AssistantMessage = React.memo(function AssistantMessage({
         </View>
       )}
 
+      {questions.length === 0 ? null : (
+        <QuestionCard
+          questions={questions}
+          onSubmit={
+            isLastMessage && !isLoading && onAnswerQuestions !== undefined
+              ? onAnswerQuestions
+              : undefined
+          }
+        />
+      )}
       {thinkingIndicator}
     </View>
   );
@@ -356,6 +380,7 @@ export function AliaChatMessageList({
   onThumbsDown,
   onApprovePlan,
   onRejectPlan,
+  onAnswerQuestions,
   welcomeComponent,
   renderMarkdown,
 }: AliaChatMessageListProps) {
@@ -459,6 +484,7 @@ export function AliaChatMessageList({
                     onThumbsDown={onThumbsDown}
                     onApprovePlan={onApprovePlan}
                     onRejectPlan={onRejectPlan}
+                    onAnswerQuestions={onAnswerQuestions}
                     renderMarkdown={renderMarkdown}
                   />
                 )}

package/src/components/QuestionCard.tsx

@@ -0,0 +1,62 @@
+import { Questionnaire, type QuestionnaireAnswers } from '@oxy.so/bloom/questionnaire';
+import { Muted } from '@oxy.so/bloom/typography';
+import { View } from 'react-native';
+import { type AskedQuestion, formatAnswers } from '../lib/questions';
+
+interface QuestionCardProps {
+  questions: AskedQuestion[];
+  /** Sends the answers as the person's next message. Absent: the card is read-only. */
+  onSubmit?: (message: string) => void;
+}
+
+/** Ids are positions: the questions are the model's, and carry none. */
+const idOf = (index: number) => `q${index}`;
+
+/**
+ * The questions Alia asked: Bloom's `Questionnaire` while the person can still answer, and
+ * the questions as plain lines once they have (the answer is their message, right below).
+ * Typing a reply in the composer answers just as well, which is why there is no dismiss.
+ */
+export function QuestionCard({ questions, onSubmit }: QuestionCardProps) {
+  if (onSubmit === undefined) {
+    return (
+      <View className="my-2 gap-1">
+        {questions.map((q, i) => (
+          // The model's questions never reorder: the position is the identity.
+          // biome-ignore lint/suspicious/noArrayIndexKey: see above
+          <Muted key={i}>{q.question}</Muted>
+        ))}
+      </View>
+    );
+  }
+
+  const complete = (answers: QuestionnaireAnswers) =>
+    onSubmit(
+      formatAnswers(
+        questions,
+        questions.map((_, i) => ({
+          picked: (answers[idOf(i)]?.values ?? []).map(Number),
+          other: answers[idOf(i)]?.other,
+        })),
+      ),
+    );
+
+  return (
+    <View className="my-2">
+      <Questionnaire
+        questions={questions.map((q, i) => ({
+          id: idOf(i),
+          question: q.question,
+          select: q.multiSelect ? 'multiple' : 'single',
+          other: true,
+          options: q.options.map((option, index) => ({
+            value: String(index),
+            label: option.label,
+            description: option.description,
+          })),
+        }))}
+        onComplete={complete}
+      />
+    </View>
+  );
+}

package/src/index.ts

@@ -22,6 +22,14 @@ export { AliaMarkdown } from './components/Markdown';
 export type { AliaMarkdownProps, RenderCodeBlock } from './components/Markdown';
 export { AliaWelcomeMessage } from './components/AliaWelcomeMessage';
 export { PlanPreviewCard } from './components/PlanPreviewCard';
+export { QuestionCard } from './components/QuestionCard';
+export {
+  ASK_USER_QUESTION_TOOL,
+  askedQuestions,
+  formatAnswers,
+  isQuestionInvocation,
+} from './lib/questions';
+export type { AskedOption, AskedQuestion, QuestionAnswer } from './lib/questions';
 
 // ── Chat hook ──
 export { useAliaChat } from './hooks/useAliaChat';

package/src/lib/questions.ts

@@ -0,0 +1,78 @@
+// The clarifying questions an assistant turn asked, read back from the stored tool call.
+//
+// The server's `askUserQuestion` ends the turn at the card, so the question IS the tool
+// call: it is stored with the message, survives a reload, and is answered by the person's
+// next message. Pure functions, no React Native, so a host's models and tests can use them.
+
+import type { ToolInvocation } from '../types';
+
+/** The tool's name on the wire. */
+export const ASK_USER_QUESTION_TOOL = 'askUserQuestion';
+
+export interface AskedOption {
+  label: string;
+  description?: string;
+}
+
+export interface AskedQuestion {
+  question: string;
+  options: AskedOption[];
+  multiSelect: boolean;
+}
+
+/** What the person picked for one question: option indexes, in option order, and typed text. */
+export interface QuestionAnswer {
+  picked: number[];
+  other?: string;
+}
+
+export const isQuestionInvocation = (inv: Pick<ToolInvocation, 'toolName'>): boolean =>
+  inv.toolName === ASK_USER_QUESTION_TOOL;
+
+const text = (value: unknown): string | null =>
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+
+/**
+ * The questions of a finished call, or `null` when it is not one or its arguments are not
+ * drawable. Model output is data the app did not write: every field is checked, and a
+ * malformed card is no card rather than a thrown render.
+ */
+export function askedQuestions(inv: ToolInvocation): AskedQuestion[] | null {
+  if (!isQuestionInvocation(inv) || inv.state !== 'result') return null;
+  const raw = (inv.args as { questions?: unknown } | undefined)?.questions;
+  if (!Array.isArray(raw)) return null;
+
+  const questions: AskedQuestion[] = [];
+  for (const item of raw) {
+    const q = item as { question?: unknown; options?: unknown; multiSelect?: unknown };
+    const question = text(q.question);
+    if (question === null || !Array.isArray(q.options)) return null;
+    const options: AskedOption[] = [];
+    for (const o of q.options) {
+      const label = text((o as { label?: unknown })?.label);
+      if (label === null) return null;
+      const description = text((o as { description?: unknown }).description);
+      options.push(description === null ? { label } : { label, description });
+    }
+    if (options.length < 2) return null;
+    questions.push({ question, options, multiSelect: q.multiSelect === true });
+  }
+  return questions.length === 0 ? null : questions;
+}
+
+/**
+ * The answers as the message the person "sends": one line per question, so the thread reads
+ * as what they said and the model reads the same text. Language-neutral on purpose.
+ */
+export function formatAnswers(questions: AskedQuestion[], answers: QuestionAnswer[]): string {
+  return questions
+    .map((q, i) => {
+      const answer = answers[i];
+      const parts = [
+        ...(answer?.picked ?? []).map((index) => q.options[index]?.label),
+        answer?.other?.trim(),
+      ].filter((part): part is string => !!part);
+      return `${q.question}\n→ ${parts.join(', ')}`;
+    })
+    .join('\n\n');
+}

package/src/tools.ts

@@ -5,6 +5,13 @@
 export { extractCitationSources } from './lib/citations';
 export type { CitationSource } from './lib/citations';
 export { getToolDoneLabel, getToolPillLabel } from './lib/task-labels';
+export {
+  ASK_USER_QUESTION_TOOL,
+  askedQuestions,
+  formatAnswers,
+  isQuestionInvocation,
+} from './lib/questions';
+export type { AskedOption, AskedQuestion, QuestionAnswer } from './lib/questions';
 export { toolCallStatus } from './lib/tool-call-status';
 export type { ToolCallStatus } from './lib/tool-call-status';
 export { englishWorkLog } from './lib/work-log-copy';