rift-ds 1.9.0 → 1.10.0

package/chat/questions.js

@@ -0,0 +1,140 @@
+import { SUGGESTION_MAX_CHARS, fitsChip } from "./suggestions.js";
+const MAX_QUESTIONS = 4;
+const MAX_QUESTION_OPTIONS = 5;
+const MIN_QUESTION_OPTIONS = 2;
+const QUESTION_PROMPT_MAX_CHARS = 60;
+const OPTION_DESCRIPTION_MAX_CHARS = 80;
+const str = (value) => typeof value === "string" ? value.trim() : "";
+const slug = (text, index) => text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || `option-${index + 1}`;
+function sanitizeQuestion(input, index) {
+  if (typeof input !== "object" || input === null) return null;
+  const raw = input;
+  const prompt = str(raw.prompt);
+  if (!prompt || prompt.length > QUESTION_PROMPT_MAX_CHARS) return null;
+  const mode = raw.mode === "multi" ? "multi" : "single";
+  if (!Array.isArray(raw.options)) return null;
+  const options = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [optionIndex, entry] of raw.options.entries()) {
+    if (typeof entry !== "object" || entry === null) return null;
+    const option = entry;
+    const label = str(option.label);
+    if (!fitsChip(label)) return null;
+    const value = str(option.value) || slug(label, optionIndex);
+    if (seen.has(value) || seen.has(label.toLowerCase())) return null;
+    seen.add(value);
+    seen.add(label.toLowerCase());
+    const description = str(option.description);
+    options.push(
+      description && description.length <= OPTION_DESCRIPTION_MAX_CHARS ? { value, label, description } : { value, label }
+    );
+  }
+  if (options.length < MIN_QUESTION_OPTIONS || options.length > MAX_QUESTION_OPTIONS) return null;
+  const question = {
+    id: str(raw.id) || `q${index + 1}`,
+    prompt,
+    mode,
+    options
+  };
+  if (raw.other === true) question.other = true;
+  if (mode === "multi") {
+    const available = options.length + (question.other ? 1 : 0);
+    const min = typeof raw.min === "number" ? Math.floor(raw.min) : 1;
+    const max = typeof raw.max === "number" ? Math.floor(raw.max) : available;
+    if (min < 1 || max < min || max > available) return null;
+    if (min !== 1) question.min = min;
+    if (max !== available) question.max = max;
+  }
+  return question;
+}
+function sanitizeQuestionSet(input, fallbackId = "questions") {
+  if (typeof input !== "object" || input === null) return null;
+  const raw = input;
+  if (!Array.isArray(raw.questions) || raw.questions.length > MAX_QUESTIONS) return null;
+  const questions = raw.questions.map((question, index) => sanitizeQuestion(question, index)).filter((question) => question !== null);
+  if (questions.length === 0) return null;
+  if (new Set(questions.map((question) => question.id)).size !== questions.length) return null;
+  return { id: str(raw.id) || fallbackId, questions };
+}
+function isBlockingQuestion(turn, live) {
+  return !live && turn?.role === "assistant" && !!turn.question && turn.question.questions.length > 1 && turn.answers === void 0;
+}
+function describeAnswers(set, answers) {
+  return {
+    items: set.questions.map((question) => {
+      const answer = answers.find((entry) => entry.questionId === question.id);
+      const labels = question.options.filter((option) => answer?.values.includes(option.value)).map((option) => option.label);
+      if (answer?.other) labels.push(answer.other);
+      return { prompt: question.prompt, answers: labels };
+    })
+  };
+}
+function serializeReply(reply) {
+  const answered = (labels) => labels.length > 0 ? labels.join(", ") : "(no answer)";
+  if (reply.items.length === 1) return answered(reply.items[0].answers);
+  return reply.items.map((item) => `${item.prompt} ${answered(item.answers)}`).join("\n");
+}
+const ASK_USER_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    questions: {
+      type: "array",
+      minItems: 1,
+      maxItems: MAX_QUESTIONS,
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: 'A short stable key for the question, e.g. "framework".' },
+          prompt: {
+            type: "string",
+            description: `The question in a few words, at most ${QUESTION_PROMPT_MAX_CHARS} characters, e.g. "Which framework?".`
+          },
+          mode: {
+            type: "string",
+            enum: ["single", "multi"],
+            description: "single when exactly one answer fits; multi when several can be true at once."
+          },
+          options: {
+            type: "array",
+            minItems: MIN_QUESTION_OPTIONS,
+            maxItems: MAX_QUESTION_OPTIONS,
+            items: {
+              type: "object",
+              properties: {
+                label: {
+                  type: "string",
+                  description: `The answer as the person would say it, at most ${SUGGESTION_MAX_CHARS} characters.`
+                },
+                description: {
+                  type: "string",
+                  description: `Optional: what choosing it means, at most ${OPTION_DESCRIPTION_MAX_CHARS} characters.`
+                }
+              },
+              required: ["label"]
+            }
+          },
+          other: {
+            type: "boolean",
+            description: 'Offer a free-text "Something else" when the options may not cover every answer.'
+          },
+          min: { type: "integer", description: "multi only: the fewest picks that make an answer." },
+          max: { type: "integer", description: "multi only: the most picks allowed." }
+        },
+        required: ["prompt", "options"]
+      }
+    }
+  },
+  required: ["questions"]
+};
+export {
+  ASK_USER_INPUT_SCHEMA,
+  MAX_QUESTIONS,
+  MAX_QUESTION_OPTIONS,
+  MIN_QUESTION_OPTIONS,
+  OPTION_DESCRIPTION_MAX_CHARS,
+  QUESTION_PROMPT_MAX_CHARS,
+  describeAnswers,
+  isBlockingQuestion,
+  sanitizeQuestionSet,
+  serializeReply
+};

package/chat/registry.json.d.ts

@@ -6,11 +6,11 @@ declare const _default: {
       "slug": "ai-chat",
       "label": "AI chat",
       "category": "ai",
-      "description": "The whole AI chat, assembled: the panel, the streaming replies, the history, the cards a reply can carry and the server handlers, set up with props.",
+      "description": "The whole AI chat: the panel, the streaming replies, the history, the cards and questions a reply can carry and the server handlers, set up with props.",
       "command": "init chat",
       "subpaths": {
         "./chat": "The widget, the provider, the launcher and the engine under them.",
-        "./chat/server": "The streaming chat handler and its follow-ups and feedback siblings, for any web-standard route.",
+        "./chat/server": "The streaming chat handler, with an opt-in tool for asking the visitor questions, and its follow-ups and feedback siblings, for any web-standard route.",
         "./chat/upstash": "Rate limits, a daily budget and the exchange log over Upstash Redis, as the handlers' guardrails.",
         "./chat/demo": "A scripted conversation with rich cards and fixtures, for a preview that needs no key.",
         "./chat/chat.css": "The widget's stylesheet."
@@ -52,6 +52,7 @@ declare const _default: {
         "PixelAvatar",
         "PromptSuggestions",
         "Prose",
+        "QuestionCard",
         "Reasoning",
         "ThreadPanel",
         "ThreadTabs"

package/chat/registry.json.js

@@ -1,5 +1,5 @@
 const $comment = "The widget registry: the fourth kind of thing the package ships, between the components and the templates. One member by design. `parts` names the library components the widget composes (held to src/components/registry.json by scripts/validate-chat-widget.mjs), `subpaths` the package exports it occupies (held to scripts/package-manifest.mjs), `category` the component category whose section and sidebar group its page joins (held to src/components/registry.json), `peers` the optional peer dependencies each subpath needs (held to package.json). The widget's page under /components, the /docs/chat page, the chat corpus and the MCP tools read this file; never type its facts elsewhere.";
-const widgets = [{ "name": "ChatWidget", "slug": "ai-chat", "label": "AI chat", "category": "ai", "description": "The whole AI chat, assembled: the panel, the streaming replies, the history, the cards a reply can carry and the server handlers, set up with props.", "command": "init chat", "subpaths": { "./chat": "The widget, the provider, the launcher and the engine under them.", "./chat/server": "The streaming chat handler and its follow-ups and feedback siblings, for any web-standard route.", "./chat/upstash": "Rate limits, a daily budget and the exchange log over Upstash Redis, as the handlers' guardrails.", "./chat/demo": "A scripted conversation with rich cards and fixtures, for a preview that needs no key.", "./chat/chat.css": "The widget's stylesheet." }, "peers": { "./chat": ["react-markdown", "remark-gfm"], "./chat/server": ["@anthropic-ai/sdk"], "./chat/upstash": ["@upstash/ratelimit", "@upstash/redis"], "./chat/demo": ["recharts"] }, "parts": ["AgentRail", "AgentStatus", "AiButton", "ArtifactCard", "ArtifactPanel", "AttachmentDropZone", "AttachmentGroup", "ChatHeader", "ChatMessage", "ChatThread", "CircularButton", "CodeBlock", "Composer", "DropdownMenu", "EmptyState", "Mention", "ModelPicker", "PixelAvatar", "PromptSuggestions", "Prose", "Reasoning", "ThreadPanel", "ThreadTabs"], "documented": ["ChatWidget", "ChatProvider", "ChatLauncher", "ChatThreads", "ChatTabs", "ChatAgentPane", "ChatArtifactPane", "ChatArtifactCard"] }];
+const widgets = [{ "name": "ChatWidget", "slug": "ai-chat", "label": "AI chat", "category": "ai", "description": "The whole AI chat: the panel, the streaming replies, the history, the cards and questions a reply can carry and the server handlers, set up with props.", "command": "init chat", "subpaths": { "./chat": "The widget, the provider, the launcher and the engine under them.", "./chat/server": "The streaming chat handler, with an opt-in tool for asking the visitor questions, and its follow-ups and feedback siblings, for any web-standard route.", "./chat/upstash": "Rate limits, a daily budget and the exchange log over Upstash Redis, as the handlers' guardrails.", "./chat/demo": "A scripted conversation with rich cards and fixtures, for a preview that needs no key.", "./chat/chat.css": "The widget's stylesheet." }, "peers": { "./chat": ["react-markdown", "remark-gfm"], "./chat/server": ["@anthropic-ai/sdk"], "./chat/upstash": ["@upstash/ratelimit", "@upstash/redis"], "./chat/demo": ["recharts"] }, "parts": ["AgentRail", "AgentStatus", "AiButton", "ArtifactCard", "ArtifactPanel", "AttachmentDropZone", "AttachmentGroup", "ChatHeader", "ChatMessage", "ChatThread", "CircularButton", "CodeBlock", "Composer", "DropdownMenu", "EmptyState", "Mention", "ModelPicker", "PixelAvatar", "PromptSuggestions", "Prose", "QuestionCard", "Reasoning", "ThreadPanel", "ThreadTabs"], "documented": ["ChatWidget", "ChatProvider", "ChatLauncher", "ChatThreads", "ChatTabs", "ChatAgentPane", "ChatArtifactPane", "ChatArtifactCard"] }];
 const registry = {
   $comment,
   widgets

package/chat/server.d.ts

@@ -16,6 +16,13 @@ export interface ChatTool {
     /** The trace point shown while the round runs, e.g. "Checked the Button prop contract". */
     tracePoint?: (input: Record<string, unknown>) => string;
 }
+/** The name of the built-in tool the model asks the visitor questions through. */
+export declare const ASK_USER_TOOL_NAME = "ask_user";
+/**
+ * What the model is told about asking. Lives in the tool's description, not
+ * the system prompt, so switching it on never disturbs a cached prefix.
+ */
+export declare const DEFAULT_ASK_USER_DESCRIPTION: string;
 /**
  * How much of the day's budget remains, as a model policy: `open` means the
  * default model serves, `reduced` means the budget model is the default (the
@@ -105,6 +112,8 @@ export interface ChatHandlerCopy {
     thinking: string;
     /** The status label while a tool round runs. */
     lookingUp: string;
+    /** The reply text when the model asks several questions without writing any. One question stands in for itself. */
+    questionsIntro: string;
     /** The error for a busy or overloaded model. */
     busy: string;
     /** The error for a rejected key. */
@@ -140,6 +149,16 @@ export interface ChatHandlerOptions {
     /** The wire value that serves once the budget steps down, and the only one past the lock. Defaults to `defaultModel`. */
     budgetModel?: string;
     tools?: ChatTool[];
+    /**
+     * Give the model the built-in `ask_user` tool, through which a reply can
+     * end in questions the widget draws as answers to pick. Pass an object to
+     * replace the guidance the model reads. Off by default. Calling it ends
+     * the exchange: no further model call is made, so it never counts against
+     * `maxModelCalls` beyond the pass that asked.
+     */
+    askUser?: boolean | {
+        description?: string;
+    };
     /** Model calls per exchange: the first pass plus tool rounds. The last allowed pass withholds the tools. */
     maxModelCalls?: number;
     /** Caps thinking and response text together. */

package/chat/server.js

@@ -1,5 +1,15 @@
 import Anthropic from "@anthropic-ai/sdk";
+import { ASK_USER_INPUT_SCHEMA, sanitizeQuestionSet } from "./questions.js";
 import { SUGGESTION_MAX_CHARS, fitsChip } from "./suggestions.js";
+const ASK_USER_TOOL_NAME = "ask_user";
+const DEFAULT_ASK_USER_DESCRIPTION = [
+  "Offer the person answers to pick for a question your reply has just asked in words.",
+  "Use it only when the most useful next step depends on their answer and the likely answers can be listed: which framework, which of these options, which parts apply.",
+  "Do not use it for open questions, for confirming something they already said, or when you can simply answer. Most replies should not ask.",
+  "Write the question in your reply first, then call this once, as your last action. The conversation waits for their answer.",
+  "Prefer one question. Use several (at most 4) only when you need all the answers before you can continue. mode is single when one answer fits and multi when several can be true together.",
+  "Set other to true when the options may not cover every answer."
+].join(" ");
 const DEFAULT_CHAT_LIMITS = {
   maxTurns: 10,
   maxMessageChars: 4e3,
@@ -15,6 +25,7 @@ const DEFAULT_CHAT_COPY = {
   reading: "Reading",
   thinking: "Thinking",
   lookingUp: "Looking it up",
+  questionsIntro: "A few questions before I go on.",
   busy: "The model is busy right now. Give it a moment and ask again.",
   unauthorised: "This chat is not configured correctly at the moment.",
   failed: "Something went wrong reaching the model. Try that again in a moment."
@@ -121,7 +132,15 @@ function createChatHandler(options) {
   const copy = { ...DEFAULT_CHAT_COPY, ...options.copy };
   const sanitise = options.sanitiseContext ?? sanitisePath;
   const tools = options.tools ?? [];
-  const toolDefinitions = tools.map((tool) => tool.definition);
+  const askUserDefinition = options.askUser ? {
+    name: ASK_USER_TOOL_NAME,
+    description: (typeof options.askUser === "object" ? options.askUser.description : void 0) ?? DEFAULT_ASK_USER_DESCRIPTION,
+    input_schema: ASK_USER_INPUT_SCHEMA
+  } : null;
+  const toolDefinitions = [
+    ...tools.map((tool) => tool.definition),
+    ...askUserDefinition ? [askUserDefinition] : []
+  ];
   const toolByName = new Map(tools.map((tool) => [tool.definition.name, tool]));
   const maxModelCalls = options.maxModelCalls ?? 3;
   const maxTokens = options.maxTokens ?? 3e3;
@@ -273,7 +292,30 @@ function createChatHandler(options) {
               (block) => block.type === "tool_use"
             );
             const results = [];
+            const ask = askUserDefinition ? toolUses.find((block) => block.name === ASK_USER_TOOL_NAME) : void 0;
+            const set = ask ? sanitizeQuestionSet(ask.input, `${exchangeId}-questions`) : null;
+            if (set) {
+              if (!streamedText) {
+                const lead = set.questions.length === 1 ? set.questions[0].prompt : copy.questionsIntro;
+                reasoning.close();
+                streamedText = true;
+                firstTextMs = Date.now() - startedAt;
+                answerText += lead;
+                send({ type: "delta", text: lead });
+              }
+              send({ type: "question", set });
+              break;
+            }
             for (const block of toolUses) {
+              if (block.name === ASK_USER_TOOL_NAME) {
+                results.push({
+                  type: "tool_result",
+                  tool_use_id: block.id,
+                  is_error: true,
+                  content: `Those questions could not be shown. Each needs a short prompt and 2 to 5 distinct options of at most ${SUGGESTION_MAX_CHARS} characters, and a set holds at most 4. Fix them, or ask in plain text.`
+                });
+                continue;
+              }
               const args = typeof block.input === "object" && block.input !== null ? block.input : {};
               send({
                 type: "status",
@@ -477,6 +519,8 @@ function createFeedbackHandler(options = {}) {
   };
 }
 export {
+  ASK_USER_TOOL_NAME,
+  DEFAULT_ASK_USER_DESCRIPTION,
   DEFAULT_CHAT_COPY,
   DEFAULT_CHAT_LIMITS,
   createChatHandler,

package/chat/sim.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { ChatCard, ChatTransport } from './types';
+import { ChatCard, ChatQuestionSet, ChatTransport } from './types';
 /** One status beat shown while the scripted reply "thinks". */
 export interface ScriptStep {
     /** The AgentStatus label. */
@@ -19,6 +19,17 @@ export interface ScriptedReply {
     content?: ReactNode;
     /** The chips offered under the reply. Each should be a scripted prompt so no path dead-ends. */
     followups?: string[];
+    /**
+     * Questions the reply asks, drawn as a QuestionCard in place of the chips.
+     * The `text` should ask them in words too, as a live model's reply would.
+     */
+    question?: ChatQuestionSet;
+    /**
+     * The reply to whatever the visitor answers to `question`: one reply for
+     * every answer, or a function of the answer as the message it was sent
+     * as. A scripted prompt that matches the answer exactly still wins.
+     */
+    answered?: ScriptedReply | ((answer: string) => ScriptedReply);
 }
 /** A prompt the visitor can send, and the reply it routes to. */
 export interface ScriptNode extends ScriptedReply {

package/chat/sim.js

@@ -50,11 +50,23 @@ function createSimTransport(script, timing = {}) {
   const byPrompt = new Map(script.nodes.map((node) => [normalize(node.prompt), node]));
   const fallbacks = script.fallbacks.length > 0 ? script.fallbacks : [DEFAULT_FALLBACK_REPLY];
   const filesReply = script.filesReply ?? defaultFilesReply;
+  const asking = /* @__PURE__ */ new Map();
+  const collect = (reply) => {
+    if (!reply.question || asking.has(normalize(reply.text))) return;
+    asking.set(normalize(reply.text), reply);
+    if (reply.answered && typeof reply.answered !== "function") collect(reply.answered);
+  };
+  for (const reply of [...script.nodes, ...script.fallbacks]) collect(reply);
   const defaultFollowups = script.nodes.map((node) => node.prompt).filter(fitsChip).slice(0, STARTER_COUNT);
   let exchangeCount = 0;
   return async function* simTransport(messages, signal) {
     const lastUser = [...messages].reverse().find((m) => m.role === "user");
-    const node = lastUser ? byPrompt.get(normalize(lastUser.content)) : void 0;
+    const prompted = lastUser ? byPrompt.get(normalize(lastUser.content)) : void 0;
+    const previous = messages[messages.length - 2];
+    const asked = !prompted && previous?.role === "assistant" ? asking.get(normalize(previous.content)) : void 0;
+    const answered = asked?.answered && lastUser ? typeof asked.answered === "function" ? asked.answered(lastUser.content) : asked.answered : void 0;
+    if (answered) collect(answered);
+    const node = prompted ?? answered;
     const attached = !node ? lastUser?.attachments ?? [] : [];
     const reply = node ?? (attached.length > 0 ? filesReply(attached.map((file) => file.name)) : fallbacks[exchangeCount % fallbacks.length]);
     if (!node && attached.length === 0) exchangeCount += 1;
@@ -70,8 +82,12 @@ function createSimTransport(script, timing = {}) {
     }
     if (reply.content) yield { type: "content", node: reply.content };
     if (reply.card) yield { type: "card", card: reply.card };
-    const followups = (reply.followups ?? defaultFollowups).filter(fitsChip);
-    if (followups.length > 0) yield { type: "followups", items: followups };
+    if (reply.question) {
+      yield { type: "question", set: reply.question };
+    } else {
+      const followups = (reply.followups ?? defaultFollowups).filter(fitsChip);
+      if (followups.length > 0) yield { type: "followups", items: followups };
+    }
     yield { type: "done" };
   };
 }

package/chat/types.d.ts

@@ -1,5 +1,6 @@
 import { ReactNode } from 'react';
 import { AttachmentItem } from '../components/Attachment/fileTypes';
+import { QuestionCardAnswer, QuestionCardQuestion } from '../components/QuestionCard/QuestionCard';
 /**
  * Rich content that can cross a network: a kind the host knows how to draw
  * and the data to draw it from. The provider's `renderers` map turns one
@@ -48,6 +49,33 @@ export interface ChatArtifact {
 }
 /** The card kind an artifact travels as. Its `data` is a `ChatArtifact`. */
 export declare const ARTIFACT_CARD_KIND = "artifact";
+/** One question the agent asks: a prompt and the answers on offer. The shape QuestionCard draws. */
+export type ChatQuestion = QuestionCardQuestion;
+/** What the visitor answered to one question. */
+export type ChatQuestionAnswer = QuestionCardAnswer;
+/**
+ * Questions the agent asks at the end of a reply, with the answers it can
+ * list: one question or a short set, each taking one option or several.
+ * The reply's text asks in words too, so a transport or a renderer that
+ * drops the set still leaves a conversation that reads correctly.
+ */
+export interface ChatQuestionSet {
+    /** Stable identity within the conversation. */
+    id: string;
+    /** Asked one at a time when there is more than one. A set of more than one holds the composer until it is answered or skipped. */
+    questions: ChatQuestion[];
+}
+/**
+ * The answers to a question set as a user turn draws them: each question's
+ * prompt and the labels picked. The turn's `text` is the same answers as
+ * the plain message the model reads.
+ */
+export interface ChatReply {
+    items: {
+        prompt: string;
+        answers: string[];
+    }[];
+}
 export type ChatEvent = 
 /** A live status step: the AgentStatus label, with an optional reasoning trace point. */
 {
@@ -106,6 +134,12 @@ export type ChatEvent =
     type: 'card';
     card: ChatCard;
 }
+/** Questions the agent asks with answers to pick, drawn under the committed
+    turn in place of follow-ups: a turn that asks is never asked about. */
+ | {
+    type: 'question';
+    set: ChatQuestionSet;
+}
 /** Terminal: the response is complete. */
  | {
     type: 'done';
@@ -121,7 +155,7 @@ export type ChatEvent =
     message: string;
 };
 /** Every event kind, for documentation that enumerates the protocol. */
-export declare const CHAT_EVENT_KINDS: readonly ["status", "model", "models", "delta", "exchange", "followups", "content", "card", "done", "notice", "error"];
+export declare const CHAT_EVENT_KINDS: readonly ["status", "model", "models", "delta", "exchange", "followups", "content", "card", "question", "done", "notice", "error"];
 export interface ChatTransportMessage {
     role: 'user' | 'assistant';
     content: string;
@@ -187,6 +221,27 @@ export interface ChatTurn {
      * carried from a transport's `card` event. Drawn where `content` is.
      */
     card?: ChatCard;
+    /**
+     * Questions this assistant turn asks, drawn under it as a QuestionCard in
+     * place of follow-ups. Carried from a transport's `question` event.
+     */
+    question?: ChatQuestionSet;
+    /**
+     * The answers given to `question`. Undefined while it is open; an empty
+     * array records a skip. Kept on the asking turn, so the card renders its
+     * answered state where it was asked.
+     */
+    answers?: ChatQuestionAnswer[];
+    /**
+     * The answers a user turn carries, drawn as the bubble when there is more
+     * than one to show. Its `text` is the same answers as a plain message.
+     */
+    reply?: ChatReply;
+    /**
+     * The follow-up chip the visitor sent from under this turn. Once set the
+     * row is a record: the chip marked, the rest dimmed and inert.
+     */
+    followupChosen?: string;
     /**
      * Render `content` on its own in the thread, outside any message chrome,
      * for conversation furniture like a day marker.
@@ -216,6 +271,8 @@ export interface LiveResponse {
     content?: ReactNode;
     /** Carried from the transport's `card` event into the committed turn. */
     card?: ChatCard;
+    /** Carried from the transport's `question` event into the committed turn. */
+    question?: ChatQuestionSet;
 }
 /**
  * One model the widget can offer in its picker and the server handler can

package/chat/types.js

@@ -8,6 +8,7 @@ const CHAT_EVENT_KINDS = [
   "followups",
   "content",
   "card",
+  "question",
   "done",
   "notice",
   "error"

package/chat/useChat.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
 import { AttachmentItem } from '../components/Attachment/fileTypes';
-import { ChatTransport, ChatTurn, LiveResponse } from './types';
+import { ChatQuestionAnswer, ChatReply, ChatTransport, ChatTurn, LiveResponse } from './types';
 /** The copy the hook shows when a transport ends a turn with nothing to show. */
 export interface ChatPlaceholderCopy {
     /** A completion that produced no text. */
@@ -35,7 +35,22 @@ export interface ChatState {
     send: (text: string, options?: {
         content?: ReactNode;
         attachments?: AttachmentItem[];
+        reply?: ChatReply;
     }) => boolean;
+    /**
+     * Answer the questions an assistant turn asked: records the answers on
+     * that turn, so its card renders the record, and sends them as the next
+     * message. Returns false, recording nothing, when the send is refused
+     * (a response in flight) or the turn asks nothing.
+     */
+    answerQuestion: (turnId: string, answers: ChatQuestionAnswer[]) => boolean;
+    /** Decline the questions an assistant turn asked. Records the skip and sends nothing. */
+    skipQuestion: (turnId: string) => void;
+    /**
+     * Send a follow-up chip from under a turn and record which it was, so the
+     * row keeps the choice. Returns whether the send was accepted.
+     */
+    chooseFollowup: (turnId: string, label: string) => boolean;
     /** Stop the in-flight response, keeping the text that already arrived. */
     stop: () => void;
     /** New chat: abort anything in flight and clear the conversation. */

package/chat/useChat.js

@@ -2,6 +2,7 @@
 import { useState, useRef, useEffect, useCallback } from "react";
 import { revokeAttachmentUrls } from "../components/Attachment/useAttachments.js";
 import { createStreamReveal } from "../components/StreamingText/useStreamReveal.js";
+import { describeAnswers, serializeReply, sanitizeQuestionSet } from "./questions.js";
 let nextId = 0;
 const makeId = () => `turn-${++nextId}`;
 const DEFAULT_PLACEHOLDER_COPY = {
@@ -50,6 +51,7 @@ function useChat(transport, placeholders = DEFAULT_PLACEHOLDER_COPY) {
           followups: finished.followups,
           content: finished.content,
           card: finished.card,
+          question: finished.question,
           durationSeconds: finished.durationSeconds ?? Math.max(1, Math.round((Date.now() - startedAt) / 1e3))
         }
       ]);
@@ -83,7 +85,8 @@ function useChat(transport, placeholders = DEFAULT_PLACEHOLDER_COPY) {
           role: "user",
           text: trimmed,
           content: options?.content,
-          attachments
+          attachments,
+          reply: options?.reply
         }
       ]);
       let current = {
@@ -126,6 +129,11 @@ function useChat(transport, placeholders = DEFAULT_PLACEHOLDER_COPY) {
               case "card":
                 current = { ...current, card: event.card };
                 break;
+              case "question": {
+                const set = sanitizeQuestionSet(event.set, `${current.id}-questions`);
+                if (set) current = { ...current, question: set };
+                break;
+              }
               case "status":
                 update({
                   ...current,
@@ -206,6 +214,32 @@ function useChat(transport, placeholders = DEFAULT_PLACEHOLDER_COPY) {
       (prev) => prev.map((turn) => turn.id === turnId ? { ...turn, followups } : turn)
     );
   }, []);
+  const patchTurn = useCallback((turnId, patch) => {
+    setTurns((prev) => prev.map((turn) => turn.id === turnId ? { ...turn, ...patch } : turn));
+  }, []);
+  const answerQuestion = useCallback(
+    (turnId, answers) => {
+      const set = turnsRef.current.find((turn) => turn.id === turnId)?.question;
+      if (!set) return false;
+      const reply = describeAnswers(set, answers);
+      if (!send(serializeReply(reply), { reply })) return false;
+      patchTurn(turnId, { answers });
+      return true;
+    },
+    [send, patchTurn]
+  );
+  const skipQuestion = useCallback(
+    (turnId) => patchTurn(turnId, { answers: [] }),
+    [patchTurn]
+  );
+  const chooseFollowup = useCallback(
+    (turnId, label) => {
+      if (!send(label)) return false;
+      patchTurn(turnId, { followupChosen: label });
+      return true;
+    },
+    [send, patchTurn]
+  );
   const injectTurn = useCallback((turn) => {
     setTurns((prev) => [...prev, { ...turn, id: makeId() }]);
   }, []);
@@ -232,7 +266,10 @@ function useChat(transport, placeholders = DEFAULT_PLACEHOLDER_COPY) {
     reset,
     injectTurn,
     setTurnFeedback,
-    setTurnFollowups
+    setTurnFollowups,
+    answerQuestion,
+    skipQuestion,
+    chooseFollowup
   };
 }
 export {

package/components/AlertDialog/AlertDialog.css

@@ -6,7 +6,7 @@
 .ds-alert-dialog {
   position: fixed;
   inset: 0;
-  z-index: 100;
+  z-index: var(--layer-modal);
   display: flex;
   align-items: center;
   justify-content: center;

package/components/AnchorNav/AnchorNav.css

@@ -102,7 +102,7 @@
 
 .ds-anchor-nav__panel {
   position: absolute;
-  z-index: 10;
+  z-index: var(--layer-dropdown);
   top: 50%;
   right: 0;
   min-width: 200px;

package/components/AppSidebar/AppSidebar.css

@@ -11,7 +11,7 @@
   position: fixed;
   top: 0;
   left: 0;
-  z-index: 100;
+  z-index: var(--layer-nav-rail);
   display: flex;
   flex-direction: column;
   justify-content: space-between;
@@ -548,7 +548,7 @@
   top: 0;
   left: 64px;
   /* One step under the rail, so the slide starts from beneath it. */
-  z-index: 99;
+  z-index: calc(var(--layer-nav-rail) - 1);
   height: 100vh;
   border-left: var(--border-025) solid var(--color-bg-container-border);
   border-right: var(--border-025) solid var(--color-bg-container-border);
@@ -762,7 +762,7 @@
        a 40px header row's. */
     top: var(--padding-400);
     left: var(--padding-400);
-    z-index: 80;
+    z-index: var(--layer-nav);
     display: flex;
     align-items: center;
     justify-content: center;
@@ -781,7 +781,7 @@
     display: block;
     position: fixed;
     inset: 0;
-    z-index: 90;
+    z-index: var(--layer-nav-scrim);
     background: var(--color-scrim);
   }
 
@@ -794,7 +794,7 @@
     top: 0;
     left: 0;
     bottom: 0;
-    z-index: 100;
+    z-index: var(--layer-nav-rail);
     width: 280px;
     height: 100dvh;
     padding: var(--padding-500) 0;