개념
세션은 provider conversation을 shell 종료 이후에도 이어 줍니다.
send/query는 session id, vendor, target id, conversation URL, deadline, evidence를 기록합니다. 이후 poll, watch, reattach, doctor가 이 정보를 사용합니다.
Capability registry
명령 dispatch 전에 Web-AI 계층은 선언적 capability registry를 참조합니다. Registry는 각 vendor와 model alias를 지원 기능(code mode, image output, deep research, context package, follow-up 등)에 매핑합니다. 대상 provider에 선언되지 않은 기능이 요청되면 실행 중 발견이 아닌 즉각적인 fail closed로 처리됩니다. 이 설계는 provider UI 변경에도 실패 범위를 좁고 예측 가능하게 유지합니다.
Session store
세션은 BROWSER_AGENT_HOME/web-ai-sessions.json에 JSON으로 저장됩니다. 각 항목은 session id, vendor, CDP target id, conversation URL, model selection evidence, 생성 timestamp, deadline, 완료 상태, structured warning, artifact descriptor를 기록합니다. 병렬 poll/watch 명령이 session 상태를 손상시키지 않도록 concurrent read와 atomic write를 지원합니다.
Interstitial detector
Provider 페이지는 예상된 composer나 response DOM 전에 interstitial 화면(rate limit, plan upgrade prompt, Cloudflare challenge, 동의 대화상자)을 보여줄 수 있습니다. Interstitial detector는 send와 poll action 전에 pre-check로 실행되어 알려진 interstitial 시그니처를 검색합니다. 감지되면 interstitial DOM을 유효한 provider 응답으로 잘못 해석하지 않고, error envelope에 interstitial 유형과 retryHint를 보고합니다.
Freshness gate
장기 실행 세션은 underlying provider tab이 다른 곳으로 이동하거나, 브라우저가 재시작되거나, conversation URL이 drift하면 stale해질 수 있습니다. Freshness gate는 poll, watch, reattach 진행 전에 저장된 CDP target id가 예상 provider 도메인의 live 페이지로 resolve되는지 확인합니다. Stale 세션은 session.stale error code와 sessions doctor의 recovery candidate를 표시합니다.
진단 stage 분류
Error envelope의 stage 필드는 파이프라인에서 실패가 발생한 위치를 특정합니다. 분류: composer (prompt 입력), send (제출), poll (응답 대기), artifact (zip/image 회수), session (store/target 해석), interstitial (blocking overlay), capability (registry 조회), policy (safety/trace 적용). 각 stage는 제한된 error code와 retry hint 집합에 매핑되어 agent가 신뢰 가능한 재시도/중단 결정을 내릴 수 있습니다.
Provider lifecycle adapter
지원 vendor(ChatGPT, Gemini, Grok) 각각에 lifecycle adapter 모듈이 있습니다. Adapter는 provider별 DOM 계약을 캡슐화합니다: composer 감지, prompt 제출, response 완료 식별, answer text 추출, ChatGPT archive dialog이나 Gemini deep-think tool 활성화 같은 provider 고유 동작 처리. 이 패턴은 provider drift를 vendor당 단일 모듈로 격리해 session orchestrator와 command surface를 안정적으로 유지합니다.
주요 명령
agbrowse web-ai sessions list --json
agbrowse web-ai sessions show <sessionId>
agbrowse web-ai poll --session <sessionId>
agbrowse web-ai watch --session <sessionId>모호성 규칙
active provider session이 여러 개면 명령은 fail closed하고 후보를 보여줍니다. 정확한 대상은 --session으로 지정합니다.