feat(browser-ext): implement agent context and configuration guide

package.json

@@ -13,6 +13,7 @@
   },
   "scripts": {
     "postinstall": "prek install",
+    "dev": "pnpm --filter @aipexstudio/cool-aipex dev",
     "preflight": "npm run format && npm run lint:fix && npm run typecheck && npm run test",
     "format": "biome format . --write",
     "format:check": "biome format .",
@@ -25,8 +26,9 @@
     "@biomejs/biome": "^2.3.2",
     "@j178/prek": "^0.2.19",
     "@types/node": "^24.9.2",
+    "@typescript/native-preview": "^7.0.0-dev.20251201.1",
     "@vitest/coverage-v8": "^4.0.6",
-    "typescript": "5.9.3",
+    "typescript": "^5.9.3",
     "vitest": "^4.0.6"
   }
 }

packages/browser-ext/package.json

@@ -19,7 +19,7 @@
     "build": "vite build",
     "preview": "vite preview",
     "build:css": "npx tailwindcss -i ./src/tailwind.css -o ./src/style.css --minify",
-    "test": "pnpm --filter @aipexstudio/aipex-core build && vitest run",
+    "test": "vitest run",
     "test:watch": "vitest"
   },
   "files": [
@@ -29,6 +29,7 @@
     "host-access-config.json"
   ],
   "dependencies": {
+    "@ai-sdk/openai": "^2.0.72",
     "@aipexstudio/aipex-core": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.17.4",
     "@radix-ui/react-avatar": "^1.1.10",
@@ -62,7 +63,8 @@
     "tailwindcss": "4.1.13",
     "tokenlens": "^1.3.1",
     "tw-animate-css": "^1.4.0",
-    "use-stick-to-bottom": "^1.1.1"
+    "use-stick-to-bottom": "^1.1.1",
+    "zod": "^3.25.40"
   },
   "devDependencies": {
     "@crxjs/vite-plugin": "^2.2.0",

packages/browser-ext/src/components/chatbot/components/chatbot.tsx

@@ -4,12 +4,14 @@ import { cn } from "~/lib/utils";
 import type { ChatbotThemeVariables, ContextItem } from "~/types";
 import { DEFAULT_MODELS } from "../constants";
 import {
+  AgentContext,
   type ChatbotProviderProps,
   ChatContext,
   ComponentsContext,
   ConfigContext,
   ThemeContext,
 } from "../core/context";
+import { ConfigurationGuide } from "./configuration-guide";
 import { Header } from "./header";
 import { InputArea } from "./input-area";
 import { MessageList } from "./message-list";
@@ -37,6 +39,7 @@ function themeToStyle(
  */
 export function ChatbotProvider({
   agent,
+  configError,
   config,
   handlers,
   components = {},
@@ -64,6 +67,15 @@ export function ChatbotProvider({
     [theme.className, className],
   );
 
+  // Agent context value
+  const agentContextValue = useMemo(
+    () => ({
+      isReady: Boolean(agent),
+      configError,
+    }),
+    [agent, configError],
+  );
+
   // Context values
   const chatContextValue = useMemo(
     () => ({
@@ -108,9 +120,11 @@ export function ChatbotProvider({
     <ThemeContext.Provider value={themeContextValue}>
       <ComponentsContext.Provider value={componentsContextValue}>
         <ConfigContext.Provider value={configContextValue}>
-          <ChatContext.Provider value={chatContextValue}>
-            {children}
-          </ChatContext.Provider>
+          <AgentContext.Provider value={agentContextValue}>
+            <ChatContext.Provider value={chatContextValue}>
+              {children}
+            </ChatContext.Provider>
+          </AgentContext.Provider>
         </ConfigContext.Provider>
       </ComponentsContext.Provider>
     </ThemeContext.Provider>
@@ -150,6 +164,7 @@ export interface ChatbotProps extends Omit<ChatbotProviderProps, "children"> {
  */
 export function Chatbot({
   agent,
+  configError,
   config,
   handlers,
   components,
@@ -164,6 +179,7 @@ export function Chatbot({
   return (
     <ChatbotProvider
       agent={agent}
+      configError={configError}
       config={config}
       handlers={handlers}
       components={components}
@@ -195,10 +211,12 @@ function ChatbotContent({
 }) {
   const themeCtx = useContext(ThemeContext);
   const chatCtx = useContext(ChatContext);
+  const agentCtx = useContext(AgentContext);
 
   const { className, style } = themeCtx;
   const { messages, status, sendMessage, interrupt, reset, regenerate } =
     chatCtx;
+  const { isReady: isAgentReady } = agentCtx;
 
   const [input, setInput] = useState("");
   const [showSettings, setShowSettings] = useState(false);
@@ -227,6 +245,10 @@ function ChatbotContent({
     setInput("");
   }, [reset]);
 
+  const handleOpenSettings = useCallback(() => {
+    setShowSettings(true);
+  }, []);
+
   return (
     <div
       className={cn(
@@ -238,29 +260,39 @@ function ChatbotContent({
       {/* Header */}
       <Header
         title={title}
-        onSettingsClick={() => setShowSettings(true)}
+        onSettingsClick={handleOpenSettings}
         onNewChat={handleNewChat}
       />
 
-      {/* Message List */}
-      <MessageList
-        messages={messages}
-        status={status}
-        onRegenerate={regenerate}
-        onCopy={handleCopy}
-        onSuggestionClick={handleSuggestion}
-      />
+      {/* Show configuration guide when agent is not ready */}
+      {!isAgentReady ? (
+        <ConfigurationGuide
+          onOpenSettings={handleOpenSettings}
+          className="flex-1"
+        />
+      ) : (
+        <>
+          {/* Message List */}
+          <MessageList
+            messages={messages}
+            status={status}
+            onRegenerate={regenerate}
+            onCopy={handleCopy}
+            onSuggestionClick={handleSuggestion}
+          />
 
-      {/* Input Area */}
-      <InputArea
-        value={input}
-        onChange={setInput}
-        onSubmit={handleSubmit}
-        onStop={interrupt}
-        status={status}
-        models={models}
-        placeholderTexts={placeholderTexts}
-      />
+          {/* Input Area */}
+          <InputArea
+            value={input}
+            onChange={setInput}
+            onSubmit={handleSubmit}
+            onStop={interrupt}
+            status={status}
+            models={models}
+            placeholderTexts={placeholderTexts}
+          />
+        </>
+      )}
 
       {/* Settings Dialog */}
       <SettingsDialog open={showSettings} onOpenChange={setShowSettings} />

packages/browser-ext/src/components/chatbot/components/configuration-guide.tsx

@@ -0,0 +1,55 @@
+import { SettingsIcon } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { useTranslation } from "~/i18n/context";
+import { cn } from "~/lib/utils";
+
+export interface ConfigurationGuideProps {
+  onOpenSettings: () => void;
+  className?: string;
+}
+
+export function ConfigurationGuide({
+  onOpenSettings,
+  className,
+}: ConfigurationGuideProps) {
+  const { t } = useTranslation();
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col items-center justify-center h-full p-4 sm:p-8",
+        className,
+      )}
+    >
+      <div className="text-center max-w-md">
+        <div className="mb-6 flex justify-center">
+          <div className="w-16 h-16 rounded-full bg-amber-100 dark:bg-amber-900/30 flex items-center justify-center">
+            <SettingsIcon className="w-8 h-8 text-amber-600 dark:text-amber-400" />
+          </div>
+        </div>
+
+        <h3 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-3">
+          {t("config.title")}
+        </h3>
+
+        <p className="text-sm text-gray-600 dark:text-gray-400 mb-2">
+          {t("config.description")}
+        </p>
+
+        <p className="text-xs text-gray-500 dark:text-gray-500 mb-6">
+          {t("config.apiTokenRequired")}
+        </p>
+
+        <Button
+          onClick={onOpenSettings}
+          className="gap-2"
+          variant="default"
+          size="lg"
+        >
+          <SettingsIcon className="w-4 h-4" />
+          {t("config.openSettings")}
+        </Button>
+      </div>
+    </div>
+  );
+}

packages/browser-ext/src/components/chatbot/components/index.ts

@@ -2,6 +2,10 @@
 export { Chatbot, type ChatbotProps, ChatbotProvider } from "./chatbot";
 
 // Individual components
+export {
+  ConfigurationGuide,
+  type ConfigurationGuideProps,
+} from "./configuration-guide";
 export { DefaultHeader, Header } from "./header";
 export {
   DefaultInputArea,

packages/browser-ext/src/components/chatbot/core/context.ts

@@ -134,11 +134,36 @@ export function useThemeContext(): ThemeContextValue {
 
 export { ThemeContext };
 
+// ============ Agent Context ============
+
+export interface AgentContextValue {
+  /** Whether the agent is configured and ready */
+  isReady: boolean;
+  /** Configuration error if agent creation failed */
+  configError?: Error;
+}
+
+const AgentContext = createContext<AgentContextValue>({
+  isReady: false,
+  configError: undefined,
+});
+
+/**
+ * Hook to access agent state
+ */
+export function useAgentContext(): AgentContextValue {
+  return useContext(AgentContext);
+}
+
+export { AgentContext };
+
 // ============ Provider Props ============
 
 export interface ChatbotProviderProps {
-  /** The AIPex instance from @aipexstudio/aipex-core */
-  agent: AIPex;
+  /** The AIPex instance from @aipexstudio/aipex-core (undefined when not configured) */
+  agent: AIPex | undefined;
+  /** Configuration error message */
+  configError?: Error;
   /** Chat configuration */
   config?: ChatConfig;
   /** Event handlers */

packages/browser-ext/src/components/chatbot/index.ts

@@ -49,6 +49,8 @@ export type {
 } from "../../types";
 // Individual component exports
 export {
+  ConfigurationGuide,
+  type ConfigurationGuideProps,
   DefaultHeader,
   DefaultInputArea,
   DefaultMessageItem,
@@ -90,6 +92,8 @@ export {
 export { models, SYSTEM_PROMPT } from "./constants";
 // Context exports
 export {
+  AgentContext,
+  type AgentContextValue,
   type ChatbotProviderProps,
   ChatContext,
   type ChatContextValue,
@@ -99,6 +103,7 @@ export {
   type ConfigContextValue,
   ThemeContext,
   type ThemeContextValue,
+  useAgentContext,
   useChatContext,
   useComponentsContext,
   useConfigContext,

packages/browser-ext/src/hooks/index.ts

@@ -1,3 +1,8 @@
+export {
+  type UseAgentOptions,
+  type UseAgentReturn,
+  useAgent,
+} from "./use-agent";
 export {
   type ChatbotEventHandlers,
   type UseChatOptions,