Concept
Sessions preserve provider conversations across shells.
A send/query command records session id, vendor, target id, conversation URL, deadline, and evidence. Later commands can poll, watch, reattach, or diagnose that session.
Capability registry
Before dispatching a command, the Web-AI layer consults a declarative capability registry. The registry maps each vendor and model alias to its supported features: code mode, image output, deep research, context packages, follow-ups, and more. When a requested capability is not declared for the target provider, the command fails closed immediately rather than discovering the gap mid-execution. This design keeps the failure surface narrow and predictable across provider UI changes.
Session store
Sessions are persisted as JSON under BROWSER_AGENT_HOME/web-ai-sessions.json. Each entry records the session id, vendor, CDP target id, conversation URL, model selection evidence, creation timestamp, deadline, completion status, structured warnings, and artifact descriptors. The store supports concurrent reads and atomic writes so that parallel poll/watch commands do not corrupt session state.
Interstitial detector
Provider pages sometimes show interstitial screens (rate limits, plan upgrade prompts, Cloudflare challenges, or consent dialogs) before the expected composer or response DOM appears. The interstitial detector runs as a pre-check before send and poll actions, scanning for known interstitial signatures. When one is detected, the command reports the interstitial type in its error envelope with a retryHint rather than misinterpreting the interstitial DOM as a valid provider response.
Freshness gate
Long-running sessions can go stale when the underlying provider tab navigates away, the browser restarts, or the conversation URL drifts. The freshness gate checks that the stored CDP target id still resolves to a live page on the expected provider domain before allowing poll, watch, or reattach to proceed. Stale sessions surface a session.stale error code with recovery candidates from sessions doctor.
Diagnostics stage taxonomy
Error envelopes carry a stage field that localizes where in the pipeline the failure occurred. The taxonomy covers: composer (prompt input surface), send (submit action), poll (response wait), artifact (zip/image retrieval), session (store/target resolution), interstitial (blocking overlay), capability (registry lookup), and policy (safety/trace enforcement). Each stage maps to a bounded set of error codes and retry hints so that agents can make reliable retry/abort decisions.
Provider lifecycle adapter
Each supported vendor (ChatGPT, Gemini, Grok) has a lifecycle adapter module that encapsulates the provider-specific DOM contract: how to detect the composer, submit a prompt, identify response completion, extract answer text, and handle provider-specific quirks like ChatGPT archive dialogs or Gemini deep-think tool activation. The adapter pattern isolates provider drift to a single module per vendor, keeping the session orchestrator and command surface stable.
Common commands
agbrowse web-ai sessions list --json
agbrowse web-ai sessions show <sessionId>
agbrowse web-ai poll --session <sessionId>
agbrowse web-ai watch --session <sessionId>Ambiguity rule
When multiple active provider sessions exist, commands fail closed and include candidates. Pass --session to choose the exact target.