mirror of
https://github.com/browseros-ai/BrowserOS.git
synced 2026-05-21 04:45:12 +00:00
a228c278c6
* feat(agents): decouple chat turn lifecycle from SSE response
Introduce a per-process ActiveTurnRegistry that owns each agent turn's
lifecycle and a ring-buffered event stream, so chat tabs that close,
refresh, or navigate away no longer cancel the in-flight turn. New
endpoints:
POST /agents/:id/chat starts a turn (now returns 409 when
one is already running, with the
active turnId for attaching)
GET /agents/:id/chat/active reports the running turn for a UI
that just mounted
GET /agents/:id/chat/stream subscribes to a turn; supports
Last-Event-ID resume via per-event
seq ids
POST /agents/:id/chat/cancel explicit cancel — fetch abort no
longer affects the underlying turn
The chat hook now captures X-Turn-Id, tracks lastSeq from SSE id lines,
re-attaches on mount when the server still has an active turn, and
routes Stop through the cancel endpoint. The runtime call uses the
registry's per-turn AbortController instead of the HTTP request signal,
which is the core decoupling that lets turns outlive their initiator.
* feat(agents): add ActiveTurnRegistry primitive backing the new chat lifecycle
The previous commit referenced these files in tests and the harness
service but global gitignore swallowed them on the first add.
The registry owns the per-turn ring buffer (drop-oldest, terminal frame
preserved), the per-turn AbortController, and subscriber fan-out used
by /chat/stream resume.
BrowserOS Agent Extension
The built-in browser extension that powers BrowserOS's AI interface — new tab with unified search, side panel chat, onboarding, and settings. Built with WXT and React.
For user-facing feature documentation, see docs.browseros.com.
Features
- AI-Powered New Tab: Custom new tab page with unified search across Google and AI assistants
- Side Panel Chat: Full-featured chat interface for interacting with BrowserOS
- Multi-Provider Support: Connect to various LLM providers (OpenAI, Anthropic, Azure, Bedrock, and more)
- MCP Integration: Model Context Protocol support for extending AI capabilities
- Visual Feedback: Animated glow effect on tabs during AI agent operations
- Privacy-First: Local data handling with configurable provider settings
How It Connects
The extension communicates with the BrowserOS Server running locally. The server handles the AI agent loop, MCP tools, and CDP connections — the extension provides the UI layer.
Project Structure
entrypoints/
├── background.ts # Service worker for extension lifecycle
├── content.ts # Content script (Google pages)
├── glow.content/ # Visual glow effect for active AI operations
├── newtab/ # Custom new tab page
├── sidepanel/ # AI chat side panel
├── onboarding/ # First-time user onboarding flow
└── options/ # Extension settings dashboard
components/
└── ui/ # Shadcn UI components
lib/ # Shared utilities and hooks
Entrypoints
Background (background.ts)
The service worker that manages:
- Side panel toggling via browser action
- BrowserOS Core health checks
- MCP tools fetching
- LLM provider configuration backup
- Extension installation triggers (opens onboarding)
New Tab (newtab/)
Custom new tab replacement featuring:
- Unified Search Bar: Search Google or ask AI directly
- Tab Context: Attach open tabs to provide context for AI queries
- Search Suggestions: Real-time suggestions from multiple providers (Google, Bing, DuckDuckGo, Yahoo, Yandex)
- AI Suggestions: Context-aware BrowserOS action suggestions
- Top Sites: Quick access to frequently visited sites
- Theme Toggle: Light/dark mode support
Side Panel (sidepanel/)
The main chat interface for BrowserOS:
- Chat Modes: Switch between chat and agent modes
- Provider Selector: Choose from configured LLM providers
- Tab Attachment: Include browser tab content as context
- Tool Calls: Visual display of MCP tool invocations
- Message Actions: Like/dislike feedback, copy responses
- Conversation Management: Start new conversations, view history
Onboarding (onboarding/)
Multi-step onboarding flow for new users:
- Welcome screen with product highlights
- Feature showcase with animated cards
- Step-by-step setup wizard
- Provider configuration guidance
Options (options/)
Settings dashboard with multiple sections:
- AI Settings: Configure LLM providers (API keys, models, base URLs)
- LLM Hub: Manage chat-specific provider settings
- MCP Settings: View and manage MCP server connections
- Connect MCP: Add managed or custom MCP servers
Glow Content (glow.content/)
Content script that creates a visual indicator (pulsing orange glow) around the browser viewport when an AI agent is actively working on a tab.
Development
Prerequisites
- Bun installed
- Chrome or Chromium-based browser
- BrowserOS Server running locally (for full functionality)
Setup
# Copy environment file
cp .env.example .env.development
# Install dependencies
bun install
# Start development server
bun run dev
# Build for production
bun run build
# Create distributable zip
bun run zip
Loading the Extension
- Run
bun run devto start the development server - Open Chrome and navigate to
chrome://extensions - Enable "Developer mode"
- Click "Load unpacked" and select the
dist/directory
Environment Variables
Create a .env.development file for local development:
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project
SENTRY_AUTH_TOKEN=your-token
GraphQL Schema
Codegen requires a GraphQL schema. By default it uses the bundled schema/schema.graphql, so no extra setup is needed. If you have access to the original API source, you can set the following environment variable:
GRAPHQL_SCHEMA_PATH=/path/to/api-repo/.../schema.graphql
Development Tooling
Bun
Bun is the exclusive runtime and package manager:
- All scripts use
bun run <script>instead of npm - Package installation via
bun install - Environment files automatically loaded (no dotenv needed)
- Enforced via
enginesfield inpackage.json
Biome
Unified linter and formatter configured in biome.json:
- Formatting: 2-space indentation, single quotes, no semicolons
- Linting: Recommended rules plus custom rules for unused imports/variables
- CSS Support: Tailwind directives parsing enabled
- Import Organization: Automatic import sorting via assist actions
Scripts
| Script | Description |
|---|---|
bun run dev |
Start development mode with hot reload |
bun run build |
Build production extension |
bun run zip |
Create distributable zip file |
bun run lint |
Run Biome linter |
bun run lint:fix |
Auto-fix linting issues |
bun run typecheck |
Run TypeScript type checking |
bun run codegen |
Generate GraphQL types |
bun run clean:cache |
Clear build caches |