@agent-native/toolkit 0.201.1 → 0.202.0-nightly-20261006033736

package/src/app/chat/AgentKitAssistantChat.tsx

@@ -46,6 +46,7 @@ import {
 } from "@agent-native/core/client/agent-chat";
 import { dispatchAgentChatRunning } from "@agent-native/core/client/agent-chat";
 import {
+  fetchAgentEngineConfiguredState,
   useAgentEngineConfigured,
   type AgentEngineConfiguredState,
 } from "@agent-native/core/client/agent-chat";
@@ -84,6 +85,7 @@ import {
 import { cn } from "@agent-native/toolkit/utils";
 import {
   IconAlertTriangle,
+  IconLoader2,
   IconMessage,
   IconPlayerStopFilled,
   IconQuote,
@@ -728,6 +730,11 @@ export const AgentKitAssistantChat = forwardRef<
       },
       agents: t("agentChat.activity.agents"),
       tasks: t("agentChat.activity.tasks"),
+      toolInput: t("agentChat.tool.input"),
+      toolResult: t("agentChat.tool.result"),
+      activityValueIdentifierHidden: t("agentChat.tool.identifierHidden"),
+      activityValueOmitted: t("agentChat.tool.contentOmitted"),
+      activityValueCircular: t("agentChat.tool.circularReference"),
       working: t("agentChat.status.working"),
       workingFor: t("agentChat.status.workingFor", {
         duration: "{{duration}}",
@@ -1158,27 +1165,61 @@ const AgentKitAssistantChatBody = forwardRef<
     tabId: props.tabId,
     threadId,
   });
+  const [submissionReadiness, setSubmissionReadiness] =
+    useState<AgentEngineConfiguredState | null>(null);
+  const readinessRequestIdRef = useRef(0);
+  const providerReadinessRequestRef = useRef<{
+    requestId: number;
+    promise: Promise<AgentEngineConfiguredState>;
+  } | null>(null);
+  const latestResolvedReadinessRef = useRef<{
+    requestId: number;
+    state: AgentEngineConfiguredState;
+  } | null>(null);
+  const passiveReadinessRef = useRef(readiness.state);
+  const providerReadinessPassRef = useRef<number | null>(null);
+  const latestSubmissionReadinessRef = useRef(readiness.state);
+  useEffect(() => {
+    if (passiveReadinessRef.current !== readiness.state) {
+      const explicitReadinessPassed =
+        providerReadinessPassRef.current === readinessRequestIdRef.current &&
+        latestResolvedReadinessRef.current?.requestId ===
+          readinessRequestIdRef.current &&
+        latestResolvedReadinessRef.current.state === "configured";
+      if (readiness.state === "unavailable" && explicitReadinessPassed) {
+        return;
+      }
+      passiveReadinessRef.current = readiness.state;
+      readinessRequestIdRef.current += 1;
+      providerReadinessRequestRef.current = null;
+      providerReadinessPassRef.current = null;
+      latestSubmissionReadinessRef.current = readiness.state;
+      setSubmissionReadiness(null);
+      return;
+    }
+    if (submissionReadiness === readiness.state) {
+      latestSubmissionReadinessRef.current = readiness.state;
+      setSubmissionReadiness(null);
+    }
+  }, [readiness.state, submissionReadiness]);
   const modelCatalogPending =
     props.showModelSelector !== false && props.modelListLoading === true;
   const modelListUnavailable =
     props.showModelSelector !== false && props.modelListError === true;
-  const canChat = !providerChecksEnabled || readiness.canChat;
+  const effectiveReadiness = submissionReadiness ?? readiness.state;
+  const canChat = !providerChecksEnabled || effectiveReadiness === "configured";
   const setupMissing =
-    providerChecksEnabled &&
-    readiness.missing &&
-    !modelCatalogPending &&
-    !modelListUnavailable;
-  const providerStatus: AgentEngineConfiguredState = modelListUnavailable
-    ? "unavailable"
-    : modelCatalogPending
-      ? "unknown"
-      : providerChecksEnabled
-        ? readiness.state
-        : "configured";
-  const providerSubmissionPending =
-    !canChat &&
-    !setupMissing &&
-    (providerStatus === "unknown" || providerStatus === "unavailable");
+    providerChecksEnabled && effectiveReadiness === "missing";
+  const providerStatus: AgentEngineConfiguredState = setupMissing
+    ? "missing"
+    : modelListUnavailable
+      ? "unavailable"
+      : modelCatalogPending
+        ? "unknown"
+        : providerChecksEnabled
+          ? effectiveReadiness
+          : "configured";
+  const composerPreflightRunActiveRef = useRef<boolean | null>(null);
   const retryProviderStatus = useCallback(() => {
     window.dispatchEvent(new Event("agent-engine:configured-changed"));
   }, []);
@@ -1365,6 +1406,14 @@ const AgentKitAssistantChatBody = forwardRef<
   const bounceSetupCard = useCallback(() => {
     if (setupMissing) setSetupBouncePulse((pulse) => pulse + 1);
   }, [setupMissing]);
+  const reportMissingProvider = useCallback(() => {
+    bounceSetupCard();
+    window.dispatchEvent(
+      new CustomEvent("agent-chat:missing-api-key", {
+        detail: { tabId: props.tabId, threadId },
+      }),
+    );
+  }, [bounceSetupCard, props.tabId, threadId]);
   const lastCustomRunningStateRef = useRef<{
     custom: boolean;
     isRunning: boolean;
@@ -1849,71 +1898,139 @@ const AgentKitAssistantChatBody = forwardRef<
     return () => window.clearInterval(interval);
   }, [isRunning]);
 
-  const acquireSubmission = useCallback(async () => {
-    if (
-      isRestoring ||
-      props.composerDisabled ||
-      props.composerSubmissionDisabled
-    )
-      return null;
-    if (!canChat) {
-      if (setupMissing) {
-        bounceSetupCard();
-        window.dispatchEvent(
-          new CustomEvent("agent-chat:missing-api-key", {
-            detail: { tabId: props.tabId, threadId },
-          }),
-        );
-      }
-      return null;
+  const refreshProviderReadiness = useCallback(async () => {
+    if (!providerChecksEnabled) return "configured";
+    let request = providerReadinessRequestRef.current;
+    if (!request || request.requestId !== readinessRequestIdRef.current) {
+      const requestId = ++readinessRequestIdRef.current;
+      providerReadinessPassRef.current = null;
+      request = {
+        requestId,
+        promise: fetchAgentEngineConfiguredState(true, { fresh: true }),
+      };
+      providerReadinessRequestRef.current = request;
     }
-    if (history) {
-      const release = await history.beginSubmission();
-      if (!release) return null;
-      return release;
+    let currentRequest = request;
+    while (true) {
+      const nextReadiness = await currentRequest.promise;
+      if (currentRequest.requestId === readinessRequestIdRef.current) {
+        if (providerReadinessRequestRef.current === currentRequest) {
+          providerReadinessRequestRef.current = null;
+        }
+        latestResolvedReadinessRef.current = {
+          requestId: currentRequest.requestId,
+          state: nextReadiness,
+        };
+        latestSubmissionReadinessRef.current = nextReadiness;
+        setSubmissionReadiness(nextReadiness);
+        return nextReadiness;
+      }
+      const latestRequest = providerReadinessRequestRef.current;
+      if (
+        latestRequest &&
+        latestRequest.requestId === readinessRequestIdRef.current &&
+        latestRequest.requestId > currentRequest.requestId
+      ) {
+        currentRequest = latestRequest;
+        continue;
+      }
+      const latestResolved = latestResolvedReadinessRef.current;
+      if (latestResolved?.requestId === readinessRequestIdRef.current) {
+        return latestResolved.state;
+      }
+      return latestSubmissionReadinessRef.current;
     }
-    return () => undefined;
-  }, [
-    bounceSetupCard,
-    canChat,
-    history,
-    isRestoring,
-    props.composerDisabled,
-    props.composerSubmissionDisabled,
-    props.tabId,
-    setupMissing,
-    threadId,
-  ]);
+  }, [providerChecksEnabled]);
+
+  const acquireSubmission = useCallback(
+    async (useReadinessPass = false) => {
+      const readinessPass = providerReadinessPassRef.current;
+      const hasReadinessPass =
+        useReadinessPass &&
+        readinessPass !== null &&
+        readinessPass === readinessRequestIdRef.current &&
+        latestResolvedReadinessRef.current?.requestId === readinessPass &&
+        latestResolvedReadinessRef.current.state === "configured";
+      if (useReadinessPass) providerReadinessPassRef.current = null;
+      if (
+        isRestoring ||
+        props.composerDisabled ||
+        props.composerSubmissionDisabled
+      )
+        return null;
+      if (providerChecksEnabled) {
+        const currentReadiness = hasReadinessPass
+          ? "configured"
+          : await refreshProviderReadiness();
+        if (currentReadiness !== "configured") {
+          if (currentReadiness === "missing") reportMissingProvider();
+          return null;
+        }
+      }
+      if (history) {
+        const release = await history.beginSubmission();
+        if (!release) return null;
+        return release;
+      }
+      return () => undefined;
+    },
+    [
+      history,
+      isRestoring,
+      props.composerDisabled,
+      props.composerSubmissionDisabled,
+      providerChecksEnabled,
+      refreshProviderReadiness,
+      reportMissingProvider,
+    ],
+  );
 
   const beforeSubmit = useCallback(async () => {
+    providerReadinessPassRef.current = null;
+    composerPreflightRunActiveRef.current = null;
     if (
       isRestoring ||
       props.composerDisabled ||
       props.composerSubmissionDisabled
     )
       return false;
-    if (!canChat) {
-      if (setupMissing) {
-        bounceSetupCard();
-        window.dispatchEvent(
-          new CustomEvent("agent-chat:missing-api-key", {
-            detail: { tabId: props.tabId, threadId },
-          }),
-        );
-      }
-      return providerSubmissionPending;
+    const runWasActive = isThreadRunning();
+    if (!providerChecksEnabled) {
+      composerPreflightRunActiveRef.current = runWasActive;
+      return true;
     }
+    let currentReadiness = await refreshProviderReadiness();
+    let resolvedReadiness = latestResolvedReadinessRef.current;
+    while (
+      currentReadiness === "configured" &&
+      (!resolvedReadiness ||
+        resolvedReadiness.requestId !== readinessRequestIdRef.current ||
+        resolvedReadiness.state !== "configured")
+    ) {
+      currentReadiness = await refreshProviderReadiness();
+      resolvedReadiness = latestResolvedReadinessRef.current;
+    }
+    if (currentReadiness !== "configured") {
+      if (currentReadiness === "missing") reportMissingProvider();
+      return false;
+    }
+    if (
+      !resolvedReadiness ||
+      resolvedReadiness.requestId !== readinessRequestIdRef.current
+    ) {
+      return false;
+    }
+    composerPreflightRunActiveRef.current = runWasActive;
+    providerReadinessPassRef.current = resolvedReadiness.requestId;
     return true;
   }, [
-    bounceSetupCard,
-    canChat,
     isRestoring,
     props.composerDisabled,
     props.composerSubmissionDisabled,
-    props.tabId,
-    providerSubmissionPending,
-    setupMissing,
-    threadId,
+    providerChecksEnabled,
+    isThreadRunning,
+    refreshProviderReadiness,
+    reportMissingProvider,
   ]);
 
   const dispatch = useCallback(
@@ -2120,13 +2237,7 @@ const AgentKitAssistantChatBody = forwardRef<
       );
       const release = await acquireSubmission();
       if (!release) {
-        if (
-          !setupMissing &&
-          (isRestoring ||
-            (providerChecksEnabled &&
-              (readiness.state === "unknown" ||
-                readiness.state === "unavailable")))
-        ) {
+        if (isRestoring) {
           try {
             const selectionHydration = pendingSelectionHydrationRef.current;
             await selectionHydration?.promise;
@@ -2218,9 +2329,10 @@ const AgentKitAssistantChatBody = forwardRef<
             throw error;
           }
         }
-        const reason = setupMissing
-          ? "engine-not-configured"
-          : "submission-unavailable";
+        const reason =
+          setupMissing || latestSubmissionReadinessRef.current === "missing"
+            ? "engine-not-configured"
+            : "submission-unavailable";
         reportAgentChatSubmitResult(options.submitMessageId, false, reason);
         return { status: "rejected", reason };
       }
@@ -2260,8 +2372,6 @@ const AgentKitAssistantChatBody = forwardRef<
       isRestoring,
       isThreadRunning,
       props.tabId,
-      providerChecksEnabled,
-      readiness.state,
       setupMissing,
       t,
       threadId,
@@ -2276,38 +2386,13 @@ const AgentKitAssistantChatBody = forwardRef<
       composerOptions: AgentKitSuggestionSubmitOptions,
       prepare?: () => Promise<PromptComposerSubmitOptions>,
     ) => {
-      const runWasActiveAtSubmit = isThreadRunning();
-      const release = await acquireSubmission();
-      if (!release) {
-        if (
-          providerSubmissionPending &&
-          !props.composerDisabled &&
-          !props.composerSubmissionDisabled
-        ) {
-          try {
-            const preparedOptions = prepare ? await prepare() : composerOptions;
-            const submittedOptions = captureQueuedRunState(
-              preserveQueuedIntent(preparedOptions, composerOptions),
-              runWasActiveAtSubmit,
-            );
-            const result = await submit(
-              text,
-              files,
-              references,
-              submittedOptions,
-            );
-            if (result.status === "rejected") {
-              throw new Error(t("agentChat.recovery.deferredSubmissionFailed"));
-            }
-          } catch (error) {
-            dispatchSetupRequiredEvent(error, props.tabId, threadId);
-            throw error;
-          }
-        } else {
-          throw new Error(t("agentChat.recovery.deferredSubmissionFailed"));
-        }
-        return;
-      }
+      const runWasActiveAtSubmit = providerReadinessPassRef.current
+        ? (composerPreflightRunActiveRef.current ?? isThreadRunning())
+        : isThreadRunning();
+      composerPreflightRunActiveRef.current = null;
+      const release = await acquireSubmission(true);
+      if (!release)
+        throw new Error(t("agentChat.recovery.deferredSubmissionFailed"));
       try {
         const preparedOptions = prepare ? await prepare() : composerOptions;
         await dispatch(
@@ -2333,8 +2418,6 @@ const AgentKitAssistantChatBody = forwardRef<
       props.composerDisabled,
       props.composerSubmissionDisabled,
       props.tabId,
-      providerSubmissionPending,
-      submit,
       t,
       threadId,
     ],
@@ -3102,7 +3185,9 @@ function AgentKitTranscript({ children, threadId }: AgentKitRegionRenderProps) {
       ? []
       : getAgentKitThreadHandoffMessages(thread, surface.handoffSnapshot);
   const guided = useGuidedQuestionFlow({
-    enabled: surface.props.isActiveComposer !== false,
+    enabled:
+      surface.props.isActiveComposer !== false &&
+      surface.props.showGuidedQuestions !== false,
     stateKey: "guided-questions",
     queryKey: ["guided-questions", "agentkit"],
     browserTabId: surface.props.browserTabId,
@@ -3337,7 +3422,8 @@ function AgentKitTranscript({ children, threadId }: AgentKitRegionRenderProps) {
           </span>
         </div>
       ) : null}
-      {guided.questions?.length ? (
+      {surface.props.showGuidedQuestions !== false &&
+      guided.questions?.length ? (
         <div className="px-3 pb-3">
           <GuidedQuestionFlow
             questions={guided.questions}
@@ -3797,8 +3883,9 @@ function AgentKitComposerSurface({
           }
         />
       ) : null}
-      {modelListUnavailable ||
-      (!canChat && !setupMissing && providerStatus !== "configured") ? (
+      {!setupMissing &&
+      (modelListUnavailable ||
+        (!canChat && providerStatus !== "configured")) ? (
         <GuidedQuestionProviderGate
           providerStatus={providerStatus}
           modelListUnavailable={modelListUnavailable}
@@ -3911,7 +3998,23 @@ function AgentKitComposerSurface({
               {props.composerToolbarSlot}
             </>
           }
-          extraActionButton={props.composerExtraActionButton}
+          extraActionButton={
+            <>
+              {props.composerExtraActionButton}
+              {composerSubmissionPending ? (
+                <span
+                  className="inline-flex items-center gap-1.5 text-xs text-muted-foreground"
+                  role="status"
+                  aria-live="polite"
+                  aria-label={t("agentChat.common.waiting")}
+                  data-testid="provider-preflight-pending"
+                >
+                  <IconLoader2 className="size-3.5 animate-spin motion-reduce:animate-none" />
+                  <span>{t("agentChat.common.waiting")}</span>
+                </span>
+              ) : null}
+            </>
+          }
           includeDefaultSlashCommands
           includeDefaultSlashSkills
           onSlashCommand={props.onSlashCommand}

package/src/app/chat/AgentSidebar.tsx

@@ -266,6 +266,7 @@ export interface AgentSidebarProps {
   suppressInlineOpenApp?: AssistantChatProps["suppressInlineOpenApp"];
   composerPlaceholder?: AssistantChatProps["composerPlaceholder"];
   showMissingApiKeySetup?: AssistantChatProps["showMissingApiKeySetup"];
+  showGuidedQuestions?: AssistantChatProps["showGuidedQuestions"];
   openOnChatRunning?: boolean;
   onFullscreenRequest?: (threadId?: string) => void;
   onOpenSettings?: (section?: string) => void;
@@ -340,6 +341,7 @@ export function AgentSidebar({
   suppressInlineOpenApp,
   composerPlaceholder,
   showMissingApiKeySetup,
+  showGuidedQuestions,
   openOnChatRunning = false,
   onFullscreenRequest,
   onOpenSettings,
@@ -1158,6 +1160,7 @@ export function AgentSidebar({
             suppressInlineOpenApp={suppressInlineOpenApp}
             composerPlaceholder={composerPlaceholder}
             showMissingApiKeySetup={showMissingApiKeySetup}
+            showGuidedQuestions={showGuidedQuestions}
             missingApiKeySetupLayout="sidebar"
             defaultMode={defaultMode}
             onCollapse={() => setOpenPersisted(false)}

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

@@ -235,6 +235,29 @@ describe("useGuidedQuestionFlow scoped reads", () => {
     expect(result.current().questions?.length).toBe(1);
   });
 
+  it("hides a thread-scoped question until its owner thread is known", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: RequestInfo | URL) =>
+        readResponse(String(input), (key) =>
+          key === "guided-questions:tab123"
+            ? JSON.stringify({ ...payload, threadId: "chat-a" })
+            : "",
+        ),
+      ),
+    );
+
+    const result = await renderFlow({
+      stateKey: "guided-questions",
+      queryKey: ["guided-questions"],
+      browserTabId: "tab123",
+      refetchInterval: false,
+    });
+
+    expect(result.current().questions).toBeNull();
+    expect(result.current().payload).toBeNull();
+  });
+
   it("renders a payload with no threadId in any chat", async () => {
     vi.stubGlobal(
       "fetch",
@@ -401,6 +424,68 @@ describe("useGuidedQuestionFlow scoped reads", () => {
     expect(deleted).toContain("guided-questions:tab123");
   });
 
+  it("does not restore an in-flight read after clear", async () => {
+    let resolveRead: (() => void) | null = null;
+    const fetchMock = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (init?.method === "DELETE") {
+        return Promise.resolve(new Response("", { status: 200 }));
+      }
+      return new Promise<Response>((resolve) => {
+        resolveRead = () =>
+          resolve(
+            readResponse(url, (key) =>
+              key === "guided-questions" ? JSON.stringify(payload) : "",
+            ),
+          );
+      });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    let latest: HookResult | null = null;
+    function Harness() {
+      const flow = useGuidedQuestionFlow({
+        providerStatusChecksEnabled: false,
+        stateKey: "guided-questions",
+        queryKey: ["guided-questions"],
+        refetchInterval: false,
+      });
+      latest = flow;
+      return flow.questions ? (
+        <GuidedQuestionFlow
+          questions={flow.questions}
+          onSubmit={() => {}}
+          onSkip={() => {}}
+        />
+      ) : null;
+    }
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={client}>
+          <Harness />
+        </QueryClientProvider>,
+      );
+      await Promise.resolve();
+    });
+    for (let i = 0; i < 20 && !resolveRead; i += 1) await flush();
+    expect(resolveRead).toEqual(expect.any(Function));
+
+    await act(async () => {
+      latest!.clear();
+      expect(latest!.questions).toBeNull();
+      resolveRead!();
+      await Promise.resolve();
+    });
+    await flush();
+
+    expect(latest!.questions).toBeNull();
+    expect(container.textContent).not.toContain("Which range?");
+  });
+
   // The agent ids every question it asks `q1`, so an answer that travels as
   // `q1: 7d` only means something while the turn that asked it survives
   // history trimming alongside it. When it did not, the agent re-asked the

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

@@ -1095,10 +1095,12 @@ function payloadBelongsToThread(
   payload: GuidedQuestionPayload,
   threadId: string | undefined,
 ): boolean {
+  const requestedThread = threadId?.trim();
   const asker =
     typeof payload.threadId === "string" ? payload.threadId.trim() : "";
   if (!asker) return true;
-  return asker === (threadId ?? "").trim();
+  if (!requestedThread) return false;
+  return asker === requestedThread;
 }
 
 export function useGuidedQuestionFlow({
@@ -1119,6 +1121,7 @@ export function useGuidedQuestionFlow({
 }: UseGuidedQuestionFlowOptions = {}) {
   const queryClient = useQueryClient();
   const [payload, setPayload] = useState<GuidedQuestionPayload | null>(null);
+  const queryGenerationRef = useRef(0);
   const normalizedBrowserTabId = useMemo(
     () => normalizeBrowserTabId(browserTabId),
     [browserTabId],
@@ -1154,6 +1157,7 @@ export function useGuidedQuestionFlow({
     queryKey: resolvedQueryKey,
     enabled,
     queryFn: async () => {
+      const queryGeneration = queryGenerationRef.current;
       const read = async (key: string) => {
         const parsed = await readClientAppState<GuidedQuestionPayload>(
           key,
@@ -1163,10 +1167,11 @@ export function useGuidedQuestionFlow({
         }
         return null;
       };
-      return (
-        (normalizedBrowserTabId ? await read(scopedKey) : null) ??
-        (await read(stateKey))
-      );
+      const scopedPayload = normalizedBrowserTabId
+        ? await read(scopedKey)
+        : null;
+      const result = scopedPayload ?? (await read(stateKey));
+      return queryGeneration === queryGenerationRef.current ? result : null;
     },
     refetchInterval: resolvedRefetchInterval,
     structuralSharing: false,
@@ -1221,6 +1226,8 @@ export function useGuidedQuestionFlow({
   const submissionInFlightRef = useRef(false);
 
   const clear = useCallback(() => {
+    // A read already in flight may return the submitted question after clear.
+    queryGenerationRef.current += 1;
     setPayload(null);
     queryClient.setQueryData(resolvedQueryKey, null);
     const del = (key: string) => deleteClientAppState(key).catch(() => {});

package/src/app/chat/chat/surface-types.ts

@@ -353,6 +353,8 @@ export interface AssistantChatProps {
   providerStatusChecksEnabled?: boolean;
   /** Replace the built-in transport with an AgentKit-native BYO transport. */
   createTransport?: (context: AssistantChatAdapterContext) => AgentTransport;
+  /** Hide the default guided-question card when another host owns its flow. */
+  showGuidedQuestions?: boolean;
   /**
    * Bring-your-own agent runtime. When supplied, AssistantChat keeps the
    * standard composer/transcript/tool rendering shell but sends turns through