@agent-native/core 0.152.0 → 0.152.1

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8107
+- template files: 8109

package/corpus/templates/content/app/components/editor/BubbleToolbar.tsx

@@ -1,15 +1,13 @@
 import { useT } from "@agent-native/core/client/i18n";
 import {
   IconBold,
+  IconCheck,
+  IconChevronDown,
   IconItalic,
   IconStrikethrough,
   IconCode,
   IconLink,
   IconMessageCircle,
-  IconH1,
-  IconH2,
-  IconH3,
-  IconH4,
 } from "@tabler/icons-react";
 import {
   NodeSelection,
@@ -20,8 +18,13 @@ import {
 import { Decoration, DecorationSet } from "@tiptap/pm/view";
 import type { Editor } from "@tiptap/react";
 import { BubbleMenu } from "@tiptap/react/menus";
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
 import {
   Tooltip,
   TooltipContent,
@@ -56,6 +59,15 @@ type SelectionFillRange = {
   to: number;
 };
 
+type TextStyle = "paragraph" | 1 | 2 | 3 | 4 | 5 | 6;
+
+function activeTextStyle(editor: Editor): TextStyle {
+  for (const level of [1, 2, 3, 4, 5, 6] as const) {
+    if (editor.isActive("heading", { level })) return level;
+  }
+  return "paragraph";
+}
+
 const selectionFillPluginKey = new PluginKey<SelectionFillRange | null>(
   "contentSelectionFill",
 );
@@ -106,6 +118,86 @@ export function BubbleToolbar({ editor, onComment }: BubbleToolbarProps) {
   const t = useT();
   const [showLinkInput, setShowLinkInput] = useState(false);
   const [linkUrl, setLinkUrl] = useState("");
+  const [textStyleOpen, setTextStyleOpen] = useState(false);
+  const textStyleSelection = useRef<{ from: number; to: number } | null>(null);
+  const textStyleApplied = useRef(false);
+  const restoreEditorFocusOnClose = useRef(false);
+  const [textStyle, setTextStyle] = useState<TextStyle>(() =>
+    activeTextStyle(editor),
+  );
+
+  useEffect(() => {
+    const syncTextStyle = () => {
+      setTextStyle(activeTextStyle(editor));
+      const { from, to } = editor.state.selection;
+      if (from !== to) textStyleSelection.current = { from, to };
+    };
+    editor.on("selectionUpdate", syncTextStyle);
+    editor.on("transaction", syncTextStyle);
+    syncTextStyle();
+    return () => {
+      editor.off("selectionUpdate", syncTextStyle);
+      editor.off("transaction", syncTextStyle);
+    };
+  }, [editor]);
+
+  const textStyles = [
+    {
+      value: "paragraph" as const,
+      shortLabel: t("editor.slash.text"),
+      menuLabel: "T",
+      label: t("editor.slash.text"),
+    },
+    {
+      value: 1 as const,
+      shortLabel: "H1",
+      menuLabel: "H1",
+      label: t("editor.heading1"),
+    },
+    {
+      value: 2 as const,
+      shortLabel: "H2",
+      menuLabel: "H2",
+      label: t("editor.heading2"),
+    },
+    {
+      value: 3 as const,
+      shortLabel: "H3",
+      menuLabel: "H3",
+      label: t("editor.heading3"),
+    },
+    {
+      value: 4 as const,
+      shortLabel: "H4",
+      menuLabel: "H4",
+      label: t("editor.heading4"),
+    },
+  ];
+  const selectedTextStyle =
+    textStyles.find((style) => style.value === textStyle) ??
+    (typeof textStyle === "number"
+      ? {
+          value: textStyle,
+          shortLabel: `H${textStyle}`,
+          menuLabel: `H${textStyle}`,
+          label: textStyle === 5 ? t("editor.heading5") : t("editor.heading6"),
+        }
+      : textStyles[0]);
+
+  const applyTextStyle = (style: TextStyle) => {
+    const chain = editor.chain();
+    if (textStyleSelection.current) {
+      chain.setTextSelection(textStyleSelection.current);
+    }
+    if (style === "paragraph") {
+      chain.setParagraph().focus().run();
+    } else {
+      chain.setHeading({ level: style }).focus().run();
+    }
+    textStyleApplied.current = true;
+    setTextStyle(style);
+    setTextStyleOpen(false);
+  };
 
   const openLinkInput = useCallback(() => {
     setLinkUrl(editor.getAttributes("link").href || "");
@@ -251,30 +343,7 @@ export function BubbleToolbar({ editor, onComment }: BubbleToolbarProps) {
       isActive: () => editor.isActive("code"),
     },
     { type: "divider" as const },
-    {
-      icon: IconH1,
-      title: t("editor.heading1"),
-      action: () => editor.chain().focus().toggleHeading({ level: 1 }).run(),
-      isActive: () => editor.isActive("heading", { level: 1 }),
-    },
-    {
-      icon: IconH2,
-      title: t("editor.heading2"),
-      action: () => editor.chain().focus().toggleHeading({ level: 2 }).run(),
-      isActive: () => editor.isActive("heading", { level: 2 }),
-    },
-    {
-      icon: IconH3,
-      title: t("editor.heading3"),
-      action: () => editor.chain().focus().toggleHeading({ level: 3 }).run(),
-      isActive: () => editor.isActive("heading", { level: 3 }),
-    },
-    {
-      icon: IconH4,
-      title: t("editor.heading4"),
-      action: () => editor.chain().focus().toggleHeading({ level: 4 }).run(),
-      isActive: () => editor.isActive("heading", { level: 4 }),
-    },
+    { type: "text-style" as const },
     { type: "divider" as const },
     {
       icon: IconLink,
@@ -354,7 +423,7 @@ export function BubbleToolbar({ editor, onComment }: BubbleToolbarProps) {
         </div>
       ) : (
         <div
-          className="flex items-center gap-0.5 overflow-x-auto"
+          className="flex max-w-[calc(100vw-1rem)] items-center gap-0.5"
           onMouseDown={(e) => e.preventDefault()}
         >
           {items.map((item, i) => {
@@ -363,6 +432,103 @@ export function BubbleToolbar({ editor, onComment }: BubbleToolbarProps) {
                 <div key={`d-${i}`} className="w-px h-5 bg-border mx-0.5" />
               );
             }
+            if ("type" in item && item.type === "text-style") {
+              return (
+                <Popover
+                  key="text-style"
+                  open={textStyleOpen}
+                  onOpenChange={(open) => {
+                    if (open) {
+                      textStyleApplied.current = false;
+                      restoreEditorFocusOnClose.current = false;
+                      const { from, to } = editor.state.selection;
+                      if (from !== to)
+                        textStyleSelection.current = { from, to };
+                    }
+                    setTextStyleOpen(open);
+                  }}
+                >
+                  <PopoverTrigger asChild>
+                    <button
+                      type="button"
+                      aria-label={`${t("editor.slash.turnInto")}: ${selectedTextStyle.label}`}
+                      className="flex h-8 min-w-14 items-center justify-between gap-1 rounded px-2 text-sm font-medium text-popover-foreground/85 hover:bg-accent hover:text-accent-foreground"
+                    >
+                      <span>{selectedTextStyle.shortLabel}</span>
+                      <IconChevronDown size={14} strokeWidth={2} />
+                    </button>
+                  </PopoverTrigger>
+                  <PopoverContent
+                    portalled={false}
+                    align="start"
+                    sideOffset={24}
+                    className="w-44 p-1"
+                    onEscapeKeyDown={() => {
+                      restoreEditorFocusOnClose.current = true;
+                      window.setTimeout(() => editor.commands.focus(), 0);
+                    }}
+                    onCloseAutoFocus={(event) => {
+                      if (
+                        textStyleApplied.current ||
+                        restoreEditorFocusOnClose.current
+                      ) {
+                        event.preventDefault();
+                      }
+                      if (restoreEditorFocusOnClose.current) {
+                        editor.commands.focus();
+                      }
+                      textStyleApplied.current = false;
+                      restoreEditorFocusOnClose.current = false;
+                    }}
+                  >
+                    <div className="px-2 py-1 text-xs font-medium text-muted-foreground">
+                      {t("editor.slash.turnInto")}
+                    </div>
+                    <div
+                      role="menu"
+                      aria-label={t("editor.slash.turnInto")}
+                      className="flex flex-col gap-0.5"
+                    >
+                      {textStyles.map((style) => {
+                        const isSelected = style.value === textStyle;
+                        return (
+                          <button
+                            key={style.value}
+                            type="button"
+                            role="menuitemradio"
+                            aria-checked={isSelected}
+                            onPointerDown={(event) => {
+                              event.preventDefault();
+                              event.stopPropagation();
+                              applyTextStyle(style.value);
+                            }}
+                            onClick={(event) => {
+                              if (event.detail === 0) {
+                                applyTextStyle(style.value);
+                              }
+                            }}
+                            className={cn(
+                              "flex h-8 w-full items-center gap-2 rounded px-2 text-left text-sm",
+                              isSelected
+                                ? "bg-accent text-accent-foreground"
+                                : "text-popover-foreground hover:bg-accent hover:text-accent-foreground",
+                            )}
+                          >
+                            <span className="w-6 shrink-0 text-xs font-semibold text-muted-foreground">
+                              {style.menuLabel}
+                            </span>
+                            <span className="flex-1">{style.label}</span>
+                            {isSelected ? (
+                              <IconCheck size={15} strokeWidth={2.25} />
+                            ) : null}
+                          </button>
+                        );
+                      })}
+                    </div>
+                  </PopoverContent>
+                </Popover>
+              );
+            }
             const {
               icon: Icon,
               title,

package/corpus/templates/content/changelog/2026-08-03-choose-text-or-a-heading-from-one-compact-formatting-control.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-03
+---
+
+Choose Text or a heading from one compact formatting control.

package/corpus/templates/content/docs/solutions/evidence/content-text-selector/README.md

@@ -0,0 +1,26 @@
+# Content text selector visual evidence
+
+Matched desktop captures for the compact Text/H1-H4 selector in the Content editor.
+
+## Before
+
+- Source revision: `dcc028cb7d67a0f9279f9235cdc4c16710ce5689`
+- Route: `http://127.0.0.1:3317/page/j4a5KAEDBHXY`
+- Viewport: `1496 x 846`, desktop Chrome
+- Fixture account: disposable local account `toolbar-demo@example.com`
+- Fixture page: `Toolbar comparison`
+- Fixture paragraph: `Select this sentence to compare the formatting toolbar.`
+- UI state: Personal workspace expanded, agent panel closed, full paragraph selected, formatting bubble open, text-style submenu closed
+
+![Before: separate H1-H4 toolbar buttons](./before.png)
+
+## After
+
+- Source: this pull request's production build
+- Route: `http://127.0.0.1:3317/page/vDisteHisXMq`
+- Viewport: `1496 x 846`, desktop Chrome
+- Fixture account, page title, paragraph, sidebar state, and agent-panel state match the before capture
+- UI state: full paragraph selected, formatting bubble open, Text selector expanded, Text checked, H1-H4 visible
+- The route differs because the isolated worktree uses its own disposable local fixture database; the rendered fixture and viewport are matched
+
+![After: compact Text selector with H1-H4 menu](./after.png)

package/dist/agent/production-agent.d.ts

@@ -235,6 +235,14 @@ export interface ActionEntry {
      * `needsApproval` option. See `packages/core/docs/content/actions.mdx`.
      */
     needsApproval?: boolean | ((args: any, ctx?: import("../action.js").ActionRunContext) => boolean | Promise<boolean>);
+    /**
+     * The action hands control back to the user: once it succeeds the loop stops
+     * the turn instead of asking the model for another step, and any remaining
+     * tool calls in the same assistant message do not execute. Only for actions
+     * whose whole purpose is to wait on a human (`ask-question`) — telling the
+     * model to stop in the tool result does not make it stop.
+     */
+    endsTurn?: boolean;
     /** Which framework tool group contributed this action. Set by the framework,
      *  never by an app: apps own their action names, and a tagged action is one
      *  the app can switch off wholesale through `frameworkTools`. Tagged actions

package/dist/agent/production-agent.js

@@ -3823,6 +3823,23 @@ export async function runAgentLoop(opts) {
         emptyFinalResponseRetries = 0;
         flushUnstreamedAssistantText();
         let requestedActionStop = null;
+        // An `endsTurn` action ran and handed control to the user. Distinct from
+        // `requestedActionStop`, which also covers failure stops that must not
+        // suppress the remaining tool calls.
+        let turnYieldedToUser = false;
+        // Called by every path that completes a tool call successfully — a fresh
+        // invocation, a journal replay, a ledger recovery. A replayed
+        // `ask-question` that skipped this would let the resumed run ask a second
+        // time over the card the user is already looking at.
+        const noteToolCallSucceeded = (actionEntry) => {
+            if (actionEntry.endsTurn !== true)
+                return;
+            turnYieldedToUser = true;
+            requestedActionStop ??= {
+                message: "Waiting for your answer before continuing.",
+                errorCode: "awaiting-user-input",
+            };
+        };
         const noteRepeatedToolCall = (toolName, input) => {
             const key = toolCallCacheKey(toolName, input);
             const count = (repeatedToolCalls.get(key) ?? 0) + 1;
@@ -4167,6 +4184,7 @@ export async function runAgentLoop(opts) {
                         completedSideEffect: true,
                     });
                     recordToolResult(result, false);
+                    noteToolCallSucceeded(actionEntry);
                     return {
                         type: "tool-result",
                         toolCallId: toolCall.id,
@@ -4220,6 +4238,7 @@ export async function runAgentLoop(opts) {
                             ...(actionEntry.chatUI ? { chatUI: actionEntry.chatUI } : {}),
                         });
                         recordToolResult(result, false);
+                        noteToolCallSucceeded(actionEntry);
                         return {
                             type: "tool-result",
                             toolCallId: toolCall.id,
@@ -4645,6 +4664,7 @@ export async function runAgentLoop(opts) {
                 });
                 recordToolResult(result, isError);
                 if (!isError) {
+                    noteToolCallSucceeded(actionEntry);
                     if (cacheKey) {
                         readOnlyToolResultCache.set(cacheKey, result);
                     }
@@ -4715,7 +4735,46 @@ export async function runAgentLoop(opts) {
             parallelBatchKind = null;
             toolResultParts.push(...(await Promise.all(batch.map(runToolCall))));
         };
+        // An `endsTurn` action already handed control to the user, so the rest of
+        // this assistant message belongs to a turn that is over. Report those calls
+        // as not executed rather than running them: a second `ask-question` would
+        // overwrite the first one's card before anyone could answer it.
+        const skipToolCallAfterYield = (toolCall) => {
+            const result = `Not executed: ${toolCall.name} was called after an action that ends the turn. ` +
+                `The turn is paused for the user's answer — call it again on a later turn if still needed.`;
+            send({
+                type: "tool_start",
+                id: toolCall.id,
+                tool: toolCall.name,
+                input: toolCall.input,
+            });
+            send({
+                type: "tool_done",
+                id: toolCall.id,
+                tool: toolCall.name,
+                input: toolCall.input,
+                result,
+                completedSideEffect: false,
+            });
+            toolResultHistory.push({
+                name: toolCall.name,
+                content: result,
+                isError: false,
+            });
+            return {
+                type: "tool-result",
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+                toolInput: JSON.stringify(toolCall.input ?? {}),
+                content: result,
+            };
+        };
         for (const toolCall of toolCallParts) {
+            if (turnYieldedToUser) {
+                await flushParallelBatch();
+                toolResultParts.push(skipToolCallAfterYield(toolCall));
+                continue;
+            }
             const batchKind = getParallelBatchKind(toolCall);
             if (batchKind) {
                 if (parallelBatchKind && parallelBatchKind !== batchKind) {
@@ -4829,6 +4888,13 @@ export async function runAgentLoop(opts) {
             message: terminalActionStop.message,
         });
     }
+    else if (terminalActionStop?.errorCode === "awaiting-user-input") {
+        reportOutcome({
+            state: "input_required",
+            code: "awaiting_user_input",
+            message: terminalActionStop.message,
+        });
+    }
     else if (terminalActionStop) {
         reportOutcome({
             state: "failed",

package/dist/client/AssistantChat.js

@@ -4083,11 +4083,13 @@ const AssistantChatInner = forwardRef(function AssistantChatInner({ emptyStateTe
     // GuidedQuestionPayload to application_state under "guided-questions". The
     // hook polls that key, and on submit/skip composes the answer as a normal
     // user turn (via the shared sendToAgentChat) and clears the persisted key so
-    // the question does not reappear.
+    // the question does not reappear. The key is per browser tab, so `threadId`
+    // is what keeps a pending question in the chat that asked it.
     const { questions: guidedQuestions, title: guidedQuestionsTitle, description: guidedQuestionsDescription, skipLabel: guidedQuestionsSkipLabel, submitLabel: guidedQuestionsSubmitLabel, handleSubmit: handleGuidedQuestionsSubmit, handleSkip: handleGuidedQuestionsSkip, } = useGuidedQuestionFlow({
         stateKey: "guided-questions",
         queryKey: ["guided-questions"],
         ...(browserTabId ? { browserTabId } : {}),
+        ...(threadId ? { threadId } : {}),
     });
     const hasComposerAccessoryAboveStack = Boolean(composerError ||
         showComposerSlot ||

package/dist/client/guided-questions.d.ts

@@ -46,6 +46,13 @@ export interface GuidedQuestionPayload {
      * promise with the answer instead of forwarding it to the agent chat.
      */
     clientResolveId?: string;
+    /**
+     * Chat thread that asked. Set by the agent's `ask-question` tool. A payload
+     * carrying this only renders in that conversation; one without it (app code
+     * calling {@link askUserQuestion}, deterministic writes) is not thread-bound
+     * and renders wherever the flow is mounted.
+     */
+    threadId?: string;
 }
 export declare function isOtherGuidedAnswer(value: unknown): value is string;
 export declare function getOtherGuidedAnswerText(value: unknown): string;
@@ -137,6 +144,13 @@ export interface UseGuidedQuestionFlowOptions {
      * (which it almost always does — see `sessionBrowserTabId`).
      */
     browserTabId?: string;
+    /**
+     * The conversation this flow is mounted in. Agent-written payloads name the
+     * thread that asked, and a pending question belongs to that conversation
+     * only — the application-state key is per browser tab, so without this the
+     * same card follows the user into every other chat in the tab.
+     */
+    threadId?: string;
     queryKey?: readonly unknown[];
     refetchInterval?: number | false;
     submitMessage?: string;
@@ -147,7 +161,7 @@ export interface UseGuidedQuestionFlowOptions {
     }) => string;
     buildSkipContext?: () => string;
 }
-export declare function useGuidedQuestionFlow({ enabled, stateKey, browserTabId, queryKey, refetchInterval, submitMessage, skipMessage, buildSubmitContext, buildSkipContext, }?: UseGuidedQuestionFlowOptions): {
+export declare function useGuidedQuestionFlow({ enabled, stateKey, browserTabId, threadId, queryKey, refetchInterval, submitMessage, skipMessage, buildSubmitContext, buildSkipContext, }?: UseGuidedQuestionFlowOptions): {
     payload: GuidedQuestionPayload | null;
     questions: GuidedQuestion[] | null;
     title: string | undefined;

package/dist/client/guided-questions.js

@@ -406,7 +406,17 @@ function normalizeBrowserTabId(browserTabId) {
     const trimmed = browserTabId.trim();
     return SAFE_BROWSER_TAB_ID_RE.test(trimmed) ? trimmed : undefined;
 }
-export function useGuidedQuestionFlow({ enabled = true, stateKey = "show-questions", browserTabId, queryKey = ["show-questions"], refetchInterval = false, submitMessage = "Here are my answers — go ahead.", skipMessage = "Skip the questions — decide for me.", buildSubmitContext, buildSkipContext, } = {}) {
+/**
+ * Whether a stored payload belongs to the conversation currently on screen.
+ * Payloads with no `threadId` are not thread-bound and always match.
+ */
+function payloadBelongsToThread(payload, threadId) {
+    const asker = typeof payload.threadId === "string" ? payload.threadId.trim() : "";
+    if (!asker)
+        return true;
+    return asker === (threadId ?? "").trim();
+}
+export function useGuidedQuestionFlow({ enabled = true, stateKey = "show-questions", browserTabId, threadId, queryKey = ["show-questions"], refetchInterval = false, submitMessage = "Here are my answers — go ahead.", skipMessage = "Skip the questions — decide for me.", buildSubmitContext, buildSkipContext, } = {}) {
     const queryClient = useQueryClient();
     const [payload, setPayload] = useState(null);
     const normalizedBrowserTabId = useMemo(() => normalizeBrowserTabId(browserTabId), [browserTabId]);
@@ -458,7 +468,11 @@ export function useGuidedQuestionFlow({ enabled = true, stateKey = "show-questio
                 if (prev &&
                     guidedQuestionsFingerprint(prev.questions) ===
                         guidedQuestionsFingerprint(data.questions) &&
-                    prev.clientResolveId === data.clientResolveId) {
+                    prev.clientResolveId === data.clientResolveId &&
+                    // Two chats can ask a word-for-word identical question. Keeping the
+                    // old payload would bind the new one to the wrong thread, hiding it
+                    // in the chat that asked and re-showing it in the one that didn't.
+                    prev.threadId === data.threadId) {
                     return prev;
                 }
                 return data;
@@ -468,6 +482,10 @@ export function useGuidedQuestionFlow({ enabled = true, stateKey = "show-questio
             setPayload(null);
         }
     }, [data]);
+    // A question asked in another conversation stays in application state — the
+    // user can still answer it by going back to that chat — but it must not
+    // render here.
+    const visiblePayload = payload && payloadBelongsToThread(payload, threadId) ? payload : null;
     const clear = useCallback(() => {
         setPayload(null);
         queryClient.setQueryData(resolvedQueryKey, null);
@@ -481,15 +499,15 @@ export function useGuidedQuestionFlow({ enabled = true, stateKey = "show-questio
     const handleSubmit = useCallback((answers) => {
         // Client-initiated question (askUserQuestion): resolve the caller's
         // promise with the answer instead of forwarding it to the agent chat.
-        const resolveId = payload?.clientResolveId;
+        const resolveId = visiblePayload?.clientResolveId;
         if (resolveId) {
-            const firstId = payload?.questions?.[0]?.id ?? "q1";
+            const firstId = visiblePayload?.questions?.[0]?.id ?? "q1";
             resolveClientQuestion(resolveId, extractSingleAnswer(answers, firstId));
             clear();
             return;
         }
         const formattedAnswers = formatGuidedAnswersForAgent(answers);
-        const resolvedSubmitMessage = payload?.submitMessage ?? submitMessage;
+        const resolvedSubmitMessage = visiblePayload?.submitMessage ?? submitMessage;
         const context = buildSubmitContext?.({ answers, formattedAnswers }) ??
             defaultGuidedSubmitContext(formattedAnswers);
         sendToAgentChat({
@@ -498,28 +516,28 @@ export function useGuidedQuestionFlow({ enabled = true, stateKey = "show-questio
             submit: true,
         });
         clear();
-    }, [buildSubmitContext, clear, payload, submitMessage]);
+    }, [buildSubmitContext, clear, visiblePayload, submitMessage]);
     const handleSkip = useCallback(() => {
-        const resolveId = payload?.clientResolveId;
+        const resolveId = visiblePayload?.clientResolveId;
         if (resolveId) {
             resolveClientQuestion(resolveId, null);
             clear();
             return;
         }
         sendToAgentChat({
-            message: payload?.skipMessage ?? skipMessage,
+            message: visiblePayload?.skipMessage ?? skipMessage,
             context: buildSkipContext?.(),
             submit: true,
         });
         clear();
-    }, [buildSkipContext, clear, payload, skipMessage]);
+    }, [buildSkipContext, clear, visiblePayload, skipMessage]);
     return {
-        payload,
-        questions: payload?.questions ?? null,
-        title: payload?.title,
-        description: payload?.description,
-        skipLabel: payload?.skipLabel,
-        submitLabel: payload?.submitLabel,
+        payload: visiblePayload,
+        questions: visiblePayload?.questions ?? null,
+        title: visiblePayload?.title,
+        description: visiblePayload?.description,
+        skipLabel: visiblePayload?.skipLabel,
+        submitLabel: visiblePayload?.submitLabel,
         clear,
         handleSubmit,
         handleSkip,

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/integrations/webhook-handler.js

@@ -1534,14 +1534,22 @@ function getQueuedA2AContinuationAgent(completedRun) {
 }
 function extractSlackInputRequest(completedRun) {
     const events = completedRun.events.map((runEvent) => runEvent.event);
-    const didRequestInput = events.some((event) => event.type === "tool_done" &&
+    const delivered = events.find((event) => event.type === "tool_done" &&
         event.tool === "ask-question" &&
         String(event.result ?? "").startsWith("Asked the user a clarifying question and rendered it in the chat."));
-    if (!didRequestInput)
+    if (!delivered)
         return null;
+    // Match the start to the delivered call by id. A turn can also contain
+    // `ask-question` calls that never ran — the loop skips the rest of the
+    // message once one of them ends the turn, but still emits their start events
+    // — and scanning for the last start would project a question the user's chat
+    // never showed.
+    const deliveredId = delivered.type === "tool_done" ? delivered.id : "";
     for (let index = events.length - 1; index >= 0; index--) {
         const event = events[index];
-        if (event.type !== "tool_start" || event.tool !== "ask-question") {
+        if (event.type !== "tool_start" ||
+            event.tool !== "ask-question" ||
+            event.id !== deliveredId) {
             continue;
         }
         const input = event.input;

package/dist/mcp/screen-memory-stdio.d.ts

@@ -137,13 +137,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -159,7 +159,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -175,6 +174,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -190,7 +190,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             minutes: {
                 type: string;
                 description: string;
@@ -200,6 +199,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -216,7 +216,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -235,6 +234,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             };
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -250,7 +250,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
@@ -264,6 +263,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
                 description: string;
             };
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             includeMicrophone?: undefined;
@@ -314,13 +314,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt: {
                 type: string;
                 description: string;
@@ -349,13 +349,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;

package/dist/notifications/routes.d.ts

@@ -16,18 +16,18 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     ok?: undefined;
     error?: undefined;
 } | {
-    count?: undefined;
     updated: number;
     ok?: undefined;
     error?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
     error: string;
     ok?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
     ok: boolean;
     error?: undefined;
+    count?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    error?: undefined;
-    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-} | {
     error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
+    error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note: string;
-    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;

package/dist/server/agent-chat/context-tools.js

@@ -376,8 +376,12 @@ export function createUrlTools() {
             },
         },
         "ask-question": {
+            // The turn is over once the question is on screen. Without this the loop
+            // asks the model for another step, and it keeps working (and re-asking)
+            // over an unanswered question no matter what the tool result says.
+            endsTurn: true,
             tool: {
-                description: "Ask the user a multiple-choice clarifying question and render it inline in the chat. Use this ONLY when you are genuinely blocked on a decision you cannot resolve from context and a wrong guess would be costly — an ambiguous metric, date range, or grain; a real fork in approach. Present 2-5 concrete options and mark the most likely one recommended. Do NOT use it for confirmations, for things the user already specified, or to dodge easy work you could just do. Ask at most once per turn. Calling this yields the turn: stop and wait for the user's answer.",
+                description: "Ask the user a multiple-choice clarifying question and render it inline in the chat. Use this ONLY when you are genuinely blocked on a decision you cannot resolve from context and a wrong guess would be costly — an ambiguous metric, date range, or grain; a real fork in approach. Present 2-5 concrete options and mark the most likely one recommended. Do NOT use it for confirmations, for things the user already specified, or to dodge easy work you could just do. Calling this ends the turn: one question per turn, and any other tool call you emit alongside it will not run.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -408,9 +412,12 @@ export function createUrlTools() {
                 },
             },
             run: async (args) => {
+                // These must throw, not return an error string: `endsTurn` yields the
+                // turn on any non-error result, so a returned string would leave the
+                // run waiting on a question card that was never written.
                 const question = String(args?.question ?? "").trim();
                 if (!question)
-                    return "Error: 'question' is required.";
+                    throw new Error("'question' is required.");
                 const header = String(args?.header ?? "").trim();
                 const allowMultiple = String(args?.allowMultiple ?? "") === "true";
                 const allowFreeText = String(args?.allowFreeText ?? "true") !== "false";
@@ -419,10 +426,10 @@ export function createUrlTools() {
                     parsedOptions = JSON.parse(String(args?.options ?? "[]"));
                 }
                 catch {
-                    return "Error: 'options' must be a JSON array of { label, value?, description?, recommended? }.";
+                    throw new Error("'options' must be a JSON array of { label, value?, description?, recommended? }.");
                 }
                 if (!Array.isArray(parsedOptions) || parsedOptions.length === 0) {
-                    return "Error: 'options' must be a non-empty JSON array of { label, value?, description?, recommended? }.";
+                    throw new Error("'options' must be a non-empty JSON array of { label, value?, description?, recommended? }.");
                 }
                 const options = parsedOptions
                     .map((raw) => {
@@ -450,14 +457,26 @@ export function createUrlTools() {
                 })
                     .filter((opt) => opt !== null);
                 if (options.length === 0) {
-                    return "Error: 'options' must contain at least one option with a label.";
+                    throw new Error("'options' must contain at least one option with a label.");
                 }
                 // Shape must match the GuidedQuestionFlow renderer in
                 // client/guided-questions.tsx: a `text-options` question whose options
                 // carry `value`, with `multiSelect` for multi-pick and `allowOther` for
                 // free text. The renderer otherwise injects "Explore"/"Decide" options,
                 // which would be noise for a focused clarifying question, so disable them.
+                // The application-state key is scoped per browser tab, not per chat, so
+                // the payload has to name the thread that asked. The client hides a
+                // pending question in every other conversation instead of following the
+                // user from chat to chat.
+                // A request that carried no thread id falls back to the run id (see
+                // `onRunStart`), and a per-run value would never match the chat the user
+                // is looking at. Leave those surfaces unbound — they have one chat.
+                const askingRunCtx = getRequestRunContext();
+                const askingThreadId = askingRunCtx?.threadId && askingRunCtx.threadId !== askingRunCtx.runId
+                    ? askingRunCtx.threadId
+                    : undefined;
                 const payload = {
+                    ...(askingThreadId ? { threadId: askingThreadId } : {}),
                     questions: [
                         {
                             id: "q1",
@@ -475,7 +494,9 @@ export function createUrlTools() {
                 };
                 const { writeAppState } = await import("../../application-state/script-helpers.js");
                 await writeAppState(appStateKeyForBrowserTab("guided-questions", getRequestRunContext()?.browserTabId), payload);
-                return "Asked the user a clarifying question and rendered it in the chat. Stop here and wait for their answer — do not proceed or assume an answer.";
+                // The `startsWith` of this text is how integration surfaces recognize a
+                // delivered question (see `extractSlackInputRequest`). Keep the prefix.
+                return "Asked the user a clarifying question and rendered it in the chat. This turn is over — their answer arrives as a new message.";
             },
         },
     };

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    error?: undefined;
     text: string;
+    error?: undefined;
 }>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.152.0",
+  "version": "0.152.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {