scepticagent-architecture

Communication flow

Side Panel (app.js)
  │  chrome.runtime.connect("agent") — one port per request
  ▼
Service Worker (background.js)
  │  fetch() to provider API
  ▼
AI Provider (Anthropic / OpenAI / Gemini)

Two parallel port connections fire on page open via Promise.all:

streamViaPort("analyze") — full analysis with agent loop
quickHighlightPage() — fast highlight scan

Port message types

Message	Meaning
`{ type: "status", message }`	Progress label shown in UI
`{ type: "tool_call", name, label }`	Tool being invoked
`{ type: "text_delta", text }`	Streamed text chunk
`{ type: "highlight_item", highlight, index }`	One highlight, emitted in real-time
`{ type: "highlights_result", summary, categorySummaries }`	Final highlights metadata
`{ type: "done" }`	Stream complete
`{ type: "error", message }`	Error — stops streaming

Agent loop (Claude only)

runAgentLoop / runHighlightsAgentLoop — up to 12 iterations (4 for highlights). Stop reasons:

end_turn → break
pause_turn → continue (server-side web_search still running)
tool_use → run fetch_url, re-submit with results

Tools: web_search_20250305 (server-side, Anthropic-hosted), fetch_url (client-side, fetchUrl() in background.js).

Streaming parser

parseAgentStream(response, port, onTextDelta?) reads the Anthropic SSE stream. Optional onTextDelta callback intercepts text chunks — used by highlights to extract JSON objects in real-time via extractCompleteHighlights().

Real-time highlight extraction

extractCompleteHighlights(buffer, fromPos) — brace-depth character scanner that finds complete {"phrase":...} JSON objects in a mid-stream buffer without waiting for the full response. Returns { highlights, nextPos }.

Provider routing

getProviderConfig() reads provider, ${p}Key, ${p}Model from chrome.storage.local.

"anthropic" → full agent loop with tools
"openai" → runOpenAIStream — SSE streaming, no tools
"gemini" → runGeminiStream + geminiProxyFetch — non-streaming, proxied through content script

Gemini CORS proxy

Service workers send Origin: chrome-extension://[id] which Google's API rejects. Fix: geminiProxyFetch() sends the request to the content script via chrome.tabs.sendMessage. The content script fetches from the page's http/https origin, which Google accepts. Use Content-Type: text/plain + key as URL query param to avoid CORS preflight (simple request).

Settings storage keys

Key	Description
`provider`	`"anthropic"` / `"openai"` / `"gemini"`
`anthropicKey` / `openaiKey` / `geminiKey`	API keys
`anthropicModel` / `openaiModel` / `geminiModel`	Selected model
`apiKey`	Legacy Anthropic key (still read for backwards compat)

Adding a new provider — checklist

Add const XXX_API_BASE constant in background.js
Add to getProviderConfig() key/model maps
Implement runXxxStream(port, apiKey, model, systemText, messages, signal)
Branch in handleAnalyze, handleChat, handleHighlights
Add provider tab to options/index.html and logic to options/app.js
Add API domain to host_permissions in manifest.json
Update CLAUDE.md and README.md

Adding a new highlight category — checklist

Add to LABELS object and add .ra-hl-{category} CSS rule in content.js
Add to CAT_META in sidepanel/app.js
Add .scan-pill.{cat}, .hl-dot.{cat}, .hl-item-dot.{cat}, .summary-bullet-{cat} in sidepanel/style.css
Add scan pill and legend entry in sidepanel/index.html
Add category description in buildHighlightsPrompt() in background.js
Update CLAUDE.md and README.md

Known limitations

Gemini: no streaming (generateContent only), no tool use, no real URLs in source_url
OpenAI: no tool use, single-turn only
Highlights agent loop: Claude only — non-Claude providers use handleHighlightsSimple
Page content: truncated to 8000–10000 chars before sending to AI