@agent-native/toolkit 0.228.0-nightly-20261111212500 → 0.228.0

package/src/app/chat/agentkit-chat/guided-questions.flow.spec.tsx

@@ -12,10 +12,36 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   askUserQuestion,
   GUIDED_QUESTIONS_SUBMITTED_EVENT,
+  GuidedQuestionCard,
   GuidedQuestionFlow,
   useGuidedQuestionFlow,
 } from "./guided-questions.js";
 
+// Real dictation needs the app's tooltip provider and a microphone.
+vi.mock("../../../composer/useVoiceDictation.js", () => ({
+  useVoiceDictation: (options: { onTranscript: (text: string) => void }) => ({
+    options,
+  }),
+}));
+vi.mock("../../../composer/VoiceButton.js", () => ({
+  VoiceButton: ({
+    voice,
+    disabled,
+  }: {
+    voice: { options: { onTranscript: (text: string) => void } };
+    disabled?: boolean;
+  }) => (
+    <button
+      type="button"
+      data-dictation="true"
+      disabled={disabled}
+      onClick={() => voice.options.onTranscript("Make it vegetarian")}
+    >
+      Dictate
+    </button>
+  ),
+}));
+
 vi.mock("@agent-native/core/client/agent-chat", async (importOriginal) => ({
   ...(await importOriginal<
     typeof import("@agent-native/core/client/agent-chat")
@@ -1287,6 +1313,361 @@ describe("useGuidedQuestionFlow scoped reads", () => {
     expect(onSkip).not.toHaveBeenCalled();
   });
 
+  const buttonNamed = (name: string) => {
+    const match = Array.from(
+      container.querySelectorAll<HTMLButtonElement>("button"),
+    ).find((button) => button.textContent?.trim() === name);
+    if (!match) throw new Error(`No ${name} button`);
+    return match;
+  };
+  const optionLabels = () =>
+    Array.from(
+      container.querySelectorAll(".agentkit-question-option-label"),
+      (label) => label.textContent,
+    );
+
+  it("renders choice questions as the Questions card, without the old chrome", async () => {
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[
+            {
+              id: "audience",
+              type: "text-options",
+              header: "Audience",
+              question: "Who is this for?",
+              options: [
+                { label: "Board", value: "board" },
+                { label: "Team", value: "team", recommended: true },
+                { label: "Customers", value: "customers" },
+              ],
+            },
+          ]}
+          onSubmit={vi.fn()}
+          onSkip={vi.fn()}
+        />,
+      );
+    });
+
+    expect(container.querySelector(".guided-question-flow")).toBe(null);
+    expect(
+      container.querySelector(".agentkit-question-title")?.textContent,
+    ).toBe("Question");
+    // One question has no step count, and no option is picked for the user.
+    expect(container.querySelector(".agentkit-question-progress")).toBe(null);
+    expect(container.querySelector(".agentkit-question-description")).toBe(
+      null,
+    );
+    expect(container.textContent).not.toContain("Audience");
+    expect(optionLabels()).toEqual(["Team", "Board", "Customers"]);
+    expect(
+      container.querySelectorAll('[role="radio"][aria-checked="true"]'),
+    ).toHaveLength(0);
+    expect(
+      container.querySelector<HTMLInputElement>(
+        ".agentkit-question-other input",
+      )?.placeholder,
+    ).toBe("Or write your own response");
+    expect(buttonNamed("Send").disabled).toBe(true);
+  });
+
+  it("renders a caller-supplied description", async () => {
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[{ id: "notes", type: "freeform", question: "Notes?" }]}
+          description="Answer what matters."
+          onSubmit={vi.fn()}
+          onSkip={vi.fn()}
+        />,
+      );
+    });
+
+    expect(
+      container.querySelector(".agentkit-question-description")?.textContent,
+    ).toBe("Answer what matters.");
+  });
+
+  it("adds Explore and Decide rows only when a question opts in", async () => {
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[
+            {
+              id: "style",
+              type: "text-options",
+              question: "Which style?",
+              allowOther: false,
+              includeExplore: true,
+              includeDecide: true,
+              options: [{ label: "Bold", value: "bold" }],
+            },
+            {
+              id: "tone",
+              type: "text-options",
+              question: "Which tone?",
+              allowOther: false,
+              includeDecide: true,
+              options: [{ label: "Calm", value: "calm" }],
+            },
+          ]}
+          onSubmit={vi.fn()}
+          onSkip={vi.fn()}
+        />,
+      );
+    });
+
+    expect(optionLabels()).toEqual([
+      "Bold",
+      "Explore a few options",
+      "Let the agent decide",
+    ]);
+    await act(async () => buttonNamed("Skip").click());
+    expect(optionLabels()).toEqual(["Calm", "Let the agent decide"]);
+  });
+
+  it("steps through several questions and sends every answer together", async () => {
+    const onSubmit = vi.fn();
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[
+            {
+              id: "tone",
+              type: "text-options",
+              question: "Which tone?",
+              options: [{ label: "Calm", value: "calm" }],
+            },
+            {
+              id: "length",
+              type: "text-options",
+              question: "How long?",
+              options: [{ label: "Short", value: "short" }],
+            },
+            { id: "notes", type: "freeform", question: "Anything else?" },
+          ]}
+          onSubmit={onSubmit}
+          onSkip={vi.fn()}
+        />,
+      );
+    });
+    const progress = () =>
+      container.querySelector(".agentkit-question-progress")?.textContent;
+    const optionNamed = (label: string) => {
+      const match = Array.from(
+        container.querySelectorAll<HTMLButtonElement>(
+          ".agentkit-question-option",
+        ),
+      ).find((option) => option.textContent?.includes(label));
+      if (!match) throw new Error(`No ${label} option`);
+      return match;
+    };
+
+    expect(progress()).toBe("1/3");
+    expect(
+      container.querySelector(".agentkit-question-title")?.textContent,
+    ).toBe("Question 1 of 3");
+    expect(buttonNamed("Next").disabled).toBe(true);
+    await act(async () => optionNamed("Calm").click());
+    await act(async () => buttonNamed("Next").click());
+    expect(progress()).toBe("2/3");
+    expect(
+      container.querySelector(".agentkit-question-text")?.textContent,
+    ).toBe("How long?");
+
+    // Skipping leaves that question unanswered, not answered with a guess.
+    await act(async () => buttonNamed("Skip").click());
+    expect(progress()).toBe("3/3");
+    const notes = container.querySelector<HTMLInputElement>(
+      ".agentkit-question-other input",
+    );
+    if (!notes) throw new Error("No written answer");
+    expect(notes.placeholder).toBe("Write your answer");
+    await act(async () => {
+      const setValue = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "value",
+      )?.set;
+      setValue?.call(notes, "Keep it warm");
+      notes.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+    await act(async () => buttonNamed("Send").click());
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith({
+      tone: "calm",
+      notes: "Keep it warm",
+    });
+  });
+
+  it("dismisses instead of sending when every question is skipped", async () => {
+    const onSubmit = vi.fn();
+    const onSkip = vi.fn();
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[
+            {
+              id: "tone",
+              type: "text-options",
+              question: "Which tone?",
+              options: [{ label: "Calm", value: "calm" }],
+            },
+          ]}
+          onSubmit={onSubmit}
+          onSkip={onSkip}
+        />,
+      );
+    });
+
+    await act(async () => buttonNamed("Skip").click());
+    expect(onSkip).toHaveBeenCalledTimes(1);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it("sends a slider's shown value as a number", async () => {
+    const onSubmit = vi.fn();
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[
+            {
+              id: "volume",
+              type: "slider",
+              question: "How loud?",
+              min: 0,
+              max: 10,
+              step: 2,
+            },
+          ]}
+          onSubmit={onSubmit}
+          onSkip={vi.fn()}
+        />,
+      );
+    });
+
+    // The midpoint on the slider's own steps, sent without touching it.
+    expect(
+      container.querySelector<HTMLInputElement>('input[type="range"]')?.value,
+    ).toBe("6");
+    await act(async () => buttonNamed("Send").click());
+    expect(onSubmit).toHaveBeenCalledWith({ volume: 6 });
+  });
+
+  it("dictates into the written response beside Skip", async () => {
+    const onSubmit = vi.fn();
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[
+            {
+              id: "menu",
+              type: "text-options",
+              question: "Which menu?",
+              options: [{ label: "Three courses", value: "three" }],
+            },
+          ]}
+          onSubmit={onSubmit}
+          onSkip={vi.fn()}
+        />,
+      );
+    });
+
+    const dictate = container.querySelector<HTMLButtonElement>(
+      ".agentkit-question-actions [data-dictation]",
+    );
+    expect(dictate?.nextElementSibling?.textContent).toBe("Skip");
+    await act(async () => dictate?.click());
+    expect(
+      container.querySelector<HTMLInputElement>(
+        ".agentkit-question-other input",
+      )?.value,
+    ).toBe("Make it vegetarian");
+    await act(async () => buttonNamed("Send").click());
+    expect(onSubmit).toHaveBeenCalledWith({
+      menu: "Other: Make it vegetarian",
+    });
+  });
+
+  it("disables question inputs and continuation controls while provider setup is required", async () => {
+    const onSubmit = vi.fn();
+    const onSkip = vi.fn();
+
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[
+            {
+              id: "variant",
+              type: "text-options",
+              question: "Which screen should I keep?",
+              required: true,
+              submitOnSelect: true,
+              options: [{ label: "Soft Cards", value: "soft-cards" }],
+            },
+          ]}
+          onSubmit={onSubmit}
+          onSkip={onSkip}
+          isSubmissionBlocked
+          providerStatus="unavailable"
+        />,
+      );
+    });
+
+    const softCards = container.querySelector<HTMLButtonElement>(
+      ".agentkit-question-option",
+    );
+    expect(softCards?.getAttribute("aria-disabled")).toBe("true");
+    expect(container.textContent).toContain("Couldn't confirm AI is ready.");
+
+    await act(async () => {
+      softCards?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      await Promise.resolve();
+    });
+
+    expect(softCards?.getAttribute("aria-checked")).toBe("false");
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(onSkip).not.toHaveBeenCalled();
+  });
+
+  it("allows question drafts while provider status is unknown but blocks continuation", async () => {
+    const onSubmit = vi.fn();
+    const onSkip = vi.fn();
+
+    await act(async () => {
+      root.render(
+        <GuidedQuestionCard
+          questions={[
+            {
+              id: "variant",
+              type: "text-options",
+              question: "Which screen should I keep?",
+              submitOnSelect: true,
+              options: [{ label: "Soft Cards", value: "soft-cards" }],
+            },
+          ]}
+          onSubmit={onSubmit}
+          onSkip={onSkip}
+          isSubmissionBlocked
+          providerStatus="unknown"
+        />,
+      );
+    });
+
+    const softCards = container.querySelector<HTMLButtonElement>(
+      ".agentkit-question-option",
+    );
+    await act(async () => {
+      softCards?.click();
+    });
+    expect(softCards?.getAttribute("aria-checked")).toBe("true");
+    expect(buttonNamed("Send").disabled).toBe(true);
+    expect(buttonNamed("Skip").disabled).toBe(true);
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(onSkip).not.toHaveBeenCalled();
+  });
+
   it("submits selected option values as authoritative context", async () => {
     const selectedInstruction =
       'Keep "Command Deck" (variant-command-deck.html, file id file-command). Then call edit-design with fileId file-command.';

package/src/app/chat/agentkit-chat/guided-questions.tsx

@@ -34,6 +34,13 @@ import {
   useState,
 } from "react";
 
+import { useVoiceDictation } from "../../../composer/useVoiceDictation.js";
+import { VoiceButton } from "../../../composer/VoiceButton.js";
+import {
+  QuestionCard as AgentKitQuestionCard,
+  type AgentKitQuestion,
+  type AgentKitQuestionAnswers,
+} from "../../agentkit/react/question-card.js";
 import { BuilderSetupCard } from "../chat/run-recovery.js";
 
 export type GuidedQuestionType =
@@ -454,11 +461,118 @@ export interface GuidedQuestionFlowProps {
   isSubmissionBlocked?: boolean;
   providerStatus?: AgentEngineConfiguredState;
   modelListUnavailable?: boolean;
-  onRetryProviderStatus?: () => void;
+  onRetryProviderStatus?: (() => void) | undefined;
   showProviderStatusGate?: boolean;
   className?: string;
 }
 
+function toQuestionCardQuestion(
+  question: GuidedQuestion,
+  defaults: { explore: GuidedQuestionOption; decide: GuidedQuestionOption },
+): AgentKitQuestion {
+  const choices =
+    question.type === "text-options"
+      ? withDefaultOptions(question, defaults)
+      : question.type === "color-options"
+        ? recommendedFirst(question.options ?? question.choices ?? [])
+        : [];
+  const options = choices.map((option) => ({
+    value: option.value,
+    label: option.label,
+    ...(option.recommended ? { recommended: true } : {}),
+    ...(question.type === "color-options"
+      ? { color: option.color || option.value }
+      : {}),
+  }));
+  const min = question.min ?? 0;
+  const max = question.max ?? 100;
+  const step = question.step ?? 1;
+  return {
+    id: question.id,
+    question: question.question,
+    options,
+    ...(question.description ? { description: question.description } : {}),
+    ...(question.placeholder ? { placeholder: question.placeholder } : {}),
+    ...(question.type === "slider"
+      ? {
+          range: {
+            min,
+            max,
+            step,
+            initial: min + Math.round((max - min) / 2 / step) * step,
+          },
+        }
+      : {}),
+    ...(question.type === "file" ? { files: true } : {}),
+    multiSelect: question.multiSelect === true,
+    allowOther:
+      question.type === "freeform" ||
+      (question.type === "text-options" && question.allowOther !== false),
+    required: question.required === true,
+    submitOnSelect: question.submitOnSelect === true,
+  };
+}
+
+function fromQuestionCardAnswers(
+  questions: readonly GuidedQuestion[],
+  answers: AgentKitQuestionAnswers,
+): GuidedQuestionAnswers {
+  const result: GuidedQuestionAnswers = {};
+  for (const question of questions) {
+    const answer = answers[question.id] as
+      | AgentKitQuestionAnswers[string]
+      | undefined;
+    if (!answer) continue;
+    const other = answer.other?.trim() ?? "";
+    if (question.type === "freeform") {
+      if (other) result[question.id] = other;
+      continue;
+    }
+    if (question.type === "slider") {
+      if (answer.values.length > 0) {
+        result[question.id] = Number(answer.values[0]);
+      }
+      continue;
+    }
+    if (question.type === "file") {
+      if (answer.files?.length) result[question.id] = answer.files;
+      continue;
+    }
+    if (question.multiSelect) {
+      result[question.id] = [
+        ...answer.values,
+        ...(other ? [makeOtherGuidedAnswer(other)] : []),
+      ];
+      continue;
+    }
+    if (answer.values.length > 0) result[question.id] = answer.values[0];
+    else if (other) result[question.id] = makeOtherGuidedAnswer(other);
+  }
+  return result;
+}
+
+function GuidedQuestionDictation({
+  onTranscript,
+  disabled,
+}: {
+  onTranscript: (text: string) => void;
+  disabled: boolean;
+}) {
+  const voice = useVoiceDictation({ onTranscript });
+  const isMac =
+    typeof navigator !== "undefined" &&
+    /Mac|iPhone|iPad/.test(navigator.userAgent);
+  return (
+    <VoiceButton
+      voice={voice}
+      isMac={isMac}
+      disabled={disabled}
+      voiceChat={false}
+      showShortcut={false}
+    />
+  );
+}
+
 export function GuidedQuestionProviderGate({
   providerStatus,
   modelListUnavailable = false,
@@ -505,6 +619,99 @@ export function GuidedQuestionProviderGate({
   );
 }
 
+/** Docked above a chat composer; full-panel hosts use `GuidedQuestionFlow`. */
+export function GuidedQuestionCard({
+  questions,
+  onSubmit,
+  onSkip,
+  title,
+  description,
+  skipLabel,
+  submitLabel,
+  isSubmitting = false,
+  isSubmissionBlocked = false,
+  providerStatus = "configured",
+  modelListUnavailable = false,
+  onRetryProviderStatus,
+  showProviderStatusGate = true,
+  className,
+}: GuidedQuestionFlowProps) {
+  const t = useT();
+  const questionsFingerprint = useMemo(
+    () => guidedQuestionsFingerprint(questions),
+    [questions],
+  );
+  const inputsDisabled =
+    isSubmitting || (isSubmissionBlocked && providerStatus !== "unknown");
+  const exploreLabel = t("agentChat.guided.exploreLabel");
+  const exploreDescription = t("agentChat.guided.exploreDescription");
+  const decideLabel = t("agentChat.guided.decideLabel");
+  const decideDescription = t("agentChat.guided.decideDescription");
+  const cardQuestions = useMemo(
+    () =>
+      questions.map((question) =>
+        toQuestionCardQuestion(question, {
+          explore: {
+            label: exploreLabel,
+            value: EXPLORE_OPTION_VALUE,
+            description: exploreDescription,
+          },
+          decide: {
+            label: decideLabel,
+            value: DECIDE_OPTION_VALUE,
+            description: decideDescription,
+          },
+        }),
+      ),
+    [
+      questions,
+      exploreLabel,
+      exploreDescription,
+      decideLabel,
+      decideDescription,
+    ],
+  );
+  const providerGate =
+    isSubmissionBlocked && showProviderStatusGate ? (
+      <div className="guided-question-provider-gate">
+        <GuidedQuestionProviderGate
+          providerStatus={providerStatus}
+          modelListUnavailable={modelListUnavailable}
+          {...(onRetryProviderStatus ? { onRetry: onRetryProviderStatus } : {})}
+        />
+      </div>
+    ) : null;
+
+  return (
+    <AgentKitQuestionCard
+      // A new set of questions starts over at the first one.
+      key={questionsFingerprint}
+      questions={cardQuestions}
+      {...(title ? { title } : {})}
+      {...(description ? { description } : {})}
+      {...(skipLabel ? { skipLabel } : {})}
+      {...(submitLabel ? { submitLabel } : {})}
+      {...(className ? { className } : {})}
+      busy={isSubmitting}
+      disabled={inputsDisabled}
+      submitBlocked={isSubmissionBlocked}
+      footer={providerGate}
+      renderResponseControl={({ append, disabled }) => (
+        <GuidedQuestionDictation onTranscript={append} disabled={disabled} />
+      )}
+      onDismiss={onSkip}
+      onSubmit={(cardAnswers) => {
+        if (isSubmissionBlocked || isSubmitting) return;
+        onSubmit(
+          normalizeGuidedAnswers(
+            fromQuestionCardAnswers(questions, cardAnswers),
+          ),
+        );
+      }}
+    />
+  );
+}
+
 export function GuidedQuestionFlow({
   questions,
   onSubmit,
@@ -661,7 +868,7 @@ function QuestionCard({
   const t = useT();
   const questionId = useId();
   return (
-    <section className="guided-question-card border-t border-border/60 py-3 first:border-t-0 first:pt-0 last:pb-0">
+    <section className="guided-question-card border-t border-border py-3 first:border-t-0 first:pt-0 last:pb-0">
       <div className="mb-2 flex gap-2.5">
         <div className="guided-question-index mt-0.5 min-w-4 text-xs font-medium tabular-nums text-muted-foreground">
           {index + 1}
@@ -899,7 +1106,7 @@ function OptionButton({
           </span>
         )}
         {option.preview && (
-          <span className="mt-1.5 block max-h-40 overflow-auto whitespace-pre-wrap rounded border border-border/60 bg-background/60 px-2 py-1.5 font-mono text-[11px] leading-4 text-muted-foreground">
+          <span className="mt-1.5 block max-h-40 overflow-auto whitespace-pre-wrap rounded border border-border bg-background/60 px-2 py-1.5 font-mono text-[11px] leading-4 text-muted-foreground">
             {option.preview}
           </span>
         )}
@@ -1507,3 +1714,29 @@ export function useGuidedQuestionFlow({
     refetchPendingQuestionStatus,
   };
 }
+
+/**
+ * Nothing else wakes the question reader when `ask-question` finishes: without
+ * this the question waits for window focus or a reload.
+ */
+export function useRefetchGuidedQuestionsWhenAsked({
+  tools,
+  refetch,
+}: {
+  /** The thread's tool calls, read by the host from its own AgentKit context. */
+  tools: Readonly<Record<string, { name: string; status: string }>>;
+  refetch: () => unknown;
+}) {
+  const askedIds = Object.entries(tools)
+    .filter(
+      ([, tool]) => tool.name === "ask-question" && tool.status === "completed",
+    )
+    .map(([id]) => id)
+    .sort()
+    .join("\n");
+  const refetchRef = useRef(refetch);
+  refetchRef.current = refetch;
+  useEffect(() => {
+    if (askedIds) void refetchRef.current();
+  }, [askedIds]);
+}

package/src/app/chat/agentkit-chat/history.tsx

@@ -421,7 +421,7 @@ function RevertConfirmPopover({
         side="top"
         align="start"
         sideOffset={6}
-        className="w-56 rounded-lg p-3"
+        className="w-56 rounded-[var(--agent-kit-radius-sm,0.5rem)] p-3"
       >
         {phase === "confirming" ? (
           <div className="grid gap-2">

package/src/app/chat/agentkit-chat/index.ts

@@ -1,8 +1,10 @@
 export { CoreComposerRuntimeProvider } from "../composer/runtime-adapters.js";
 export {
+  GuidedQuestionCard,
   GuidedQuestionFlow,
   GuidedQuestionProviderGate,
   useGuidedQuestionFlow,
+  useRefetchGuidedQuestionsWhenAsked,
 } from "./questions.js";
 export {
   askUserQuestion,