Skip to main content

glass_dev/
browser.rs

1//! Resident browser and workflow ownership for the Glass development workspace.
2
3use crate::development::{DevelopmentError, DevelopmentResult};
4use crate::development::{RemoteFrame, RemoteInput, RemoteView};
5use glass_browser::browser::policy::{BrowserPolicy, PolicyPreset};
6use glass_browser::browser::session::{
7    BrowserSession, SemanticObservationLevel, SessionOptions, VerificationPredicate,
8    WorkflowCheckpoint, WorkflowDefinition, WorkflowRunResult,
9};
10use glass_browser::extraction::ExtractionRequest;
11use glass_browser::protocol::WebIrInspectionResult;
12use serde::{Deserialize, Serialize};
13use serde_json::Value;
14use std::collections::BTreeMap;
15use std::path::{Path, PathBuf};
16use std::sync::mpsc::{self, SyncSender};
17use std::time::Duration;
18
19const COMMAND_QUEUE: usize = 32;
20const COMMAND_TIMEOUT: Duration = Duration::from_secs(180);
21
22/// Options used to create or attach the resident development browser session.
23#[derive(Debug, Clone, Serialize, Deserialize)]
24#[serde(default, rename_all = "camelCase")]
25pub struct BrowserStartConfig {
26    /// Chrome DevTools port.
27    pub port: u16,
28    /// Attach to an existing browser rather than launching one.
29    pub attach: bool,
30    /// Use an isolated incognito context.
31    pub incognito: bool,
32    /// Show the browser window.
33    pub headed: bool,
34    /// Named profile passed to the browser session.
35    pub profile: String,
36    /// Optional explicit Chrome executable path.
37    pub chrome_path: Option<PathBuf>,
38}
39
40impl Default for BrowserStartConfig {
41    fn default() -> Self {
42        Self {
43            port: default_port(),
44            attach: false,
45            incognito: true,
46            headed: false,
47            profile: default_profile(),
48            chrome_path: None,
49        }
50    }
51}
52
53fn default_port() -> u16 {
54    9222
55}
56
57fn default_profile() -> String {
58    "default".into()
59}
60
61/// Serializable state of the resident browser worker.
62#[derive(Debug, Clone, Serialize)]
63#[serde(rename_all = "camelCase")]
64pub struct BrowserRuntimeState {
65    /// Policy preset governing browser capabilities and host access.
66    pub policy_preset: PolicyPreset,
67    /// Whether a browser session is connected.
68    pub connected: bool,
69    /// PID when this service owns the browser process.
70    pub browser_process_id: Option<u32>,
71    /// Latest observation revision known to the worker.
72    pub browser_revision: Option<u64>,
73    /// Current workflow lifecycle state.
74    pub workflow_state: String,
75    /// Identifier of the active workflow, if any.
76    pub active_workflow: Option<String>,
77}
78
79enum BrowserCommand {
80    Start(BrowserStartConfig),
81    Reconnect,
82    Stop,
83    State,
84    Observe,
85    Snapshot,
86    Semantic(SemanticObservationLevel),
87    WebIr,
88    Diff,
89    Targets,
90    SelectTarget(String),
91    Navigate {
92        url: String,
93        expected_revision: u64,
94        timeout: Duration,
95    },
96    Back(u64),
97    Forward(u64),
98    Reload(u64),
99    StopLoading(u64),
100    Highlight {
101        target: String,
102        expected_revision: u64,
103    },
104    Click {
105        target: String,
106        expected_revision: u64,
107    },
108    Type {
109        text: String,
110        target: Option<String>,
111        expected_revision: u64,
112    },
113    Scroll {
114        dx: f64,
115        dy: f64,
116        expected_revision: u64,
117    },
118    Screenshot,
119    RunWorkflow {
120        definition: Value,
121        inputs: BTreeMap<String, Value>,
122    },
123    PauseWorkflow,
124    ResumeWorkflow {
125        definition: Value,
126        inputs: BTreeMap<String, Value>,
127        checkpoint: Value,
128    },
129    ListWorkflows,
130    CancelWorkflow,
131    VerifyWorkflow,
132    VerifyPredicate {
133        predicate: VerificationPredicate,
134        timeout: Duration,
135    },
136    RemoteViewOpen,
137    RemoteViewStatus,
138    RemoteViewRevoke,
139}
140
141type Reply = SyncSender<DevelopmentResult<Value>>;
142
143/// Cloneable command handle for the one authoritative browser worker.
144#[derive(Clone)]
145pub struct BrowserService {
146    commands: SyncSender<(BrowserCommand, Reply)>,
147}
148
149impl BrowserService {
150    /// Create a resident browser worker with the development policy.
151    pub fn new(root: impl AsRef<Path>) -> DevelopmentResult<Self> {
152        Self::new_with_policy(root, PolicyPreset::Development)
153    }
154
155    /// Create a resident browser worker with an explicit authorization preset.
156    pub fn new_with_policy(
157        root: impl AsRef<Path>,
158        policy_preset: PolicyPreset,
159    ) -> DevelopmentResult<Self> {
160        let root = root.as_ref().to_path_buf();
161        let (commands, receiver) = mpsc::sync_channel::<(BrowserCommand, Reply)>(COMMAND_QUEUE);
162        std::thread::Builder::new()
163            .name("glass-browser-workspace".into())
164            .spawn(move || {
165                let runtime = tokio::runtime::Builder::new_current_thread()
166                    .enable_all()
167                    .build();
168                let Ok(runtime) = runtime else {
169                    return;
170                };
171                let mut worker = BrowserWorker::new(root, policy_preset);
172                while let Ok((command, reply)) = receiver.recv() {
173                    let result = runtime.block_on(worker.execute(command));
174                    let _ = reply.send(result);
175                }
176                runtime.block_on(worker.shutdown());
177            })
178            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
179        Ok(Self { commands })
180    }
181
182    fn call(&self, command: BrowserCommand) -> DevelopmentResult<Value> {
183        let (reply, receiver) = mpsc::sync_channel(1);
184        self.commands
185            .send((command, reply))
186            .map_err(|_| DevelopmentError::Process("resident browser worker stopped".into()))?;
187        receiver.recv_timeout(COMMAND_TIMEOUT).map_err(|error| {
188            DevelopmentError::Process(format!("resident browser command timed out: {error}"))
189        })?
190    }
191
192    /// Start a browser session; fails if one is already connected.
193    pub fn start(&self, config: BrowserStartConfig) -> DevelopmentResult<Value> {
194        self.call(BrowserCommand::Start(config))
195    }
196
197    /// Stop the session and revoke any remote view.
198    pub fn stop(&self) -> DevelopmentResult<Value> {
199        self.call(BrowserCommand::Stop)
200    }
201
202    /// Restart using the most recent start configuration.
203    pub fn reconnect(&self) -> DevelopmentResult<Value> {
204        self.call(BrowserCommand::Reconnect)
205    }
206
207    /// Return connection, workflow, and latest revision state.
208    pub fn state(&self) -> DevelopmentResult<Value> {
209        self.call(BrowserCommand::State)
210    }
211
212    /// Capture a fresh observation and advance the worker's known revision.
213    pub fn observe(&self) -> DevelopmentResult<Value> {
214        self.call(BrowserCommand::Observe)
215    }
216
217    /// Capture the session's current snapshot without forcing a fresh observe.
218    pub fn snapshot(&self) -> DevelopmentResult<Value> {
219        self.call(BrowserCommand::Snapshot)
220    }
221
222    /// Capture semantic observations at the requested level.
223    pub fn semantic(&self, level: SemanticObservationLevel) -> DevelopmentResult<Value> {
224        self.call(BrowserCommand::Semantic(level))
225    }
226
227    /// Extract the current page into a bounded Web IR inspection summary.
228    pub fn web_ir(&self) -> DevelopmentResult<Value> {
229        self.call(BrowserCommand::WebIr)
230    }
231
232    /// Return the observation delta since the session's previous revision.
233    pub fn diff(&self) -> DevelopmentResult<Value> {
234        self.call(BrowserCommand::Diff)
235    }
236
237    /// List browser targets.
238    pub fn targets(&self) -> DevelopmentResult<Value> {
239        self.call(BrowserCommand::Targets)
240    }
241
242    /// Select a target and return a fresh observation for it.
243    pub fn select_target(&self, target: String) -> DevelopmentResult<Value> {
244        self.call(BrowserCommand::SelectTarget(target))
245    }
246
247    /// Navigate if `expected_revision` still matches; `timeout` bounds navigation.
248    pub fn navigate(
249        &self,
250        url: String,
251        expected_revision: u64,
252        timeout: Duration,
253    ) -> DevelopmentResult<Value> {
254        self.call(BrowserCommand::Navigate {
255            url,
256            expected_revision,
257            timeout,
258        })
259    }
260    /// Go back if the supplied observation revision is current.
261    pub fn back(&self, expected_revision: u64) -> DevelopmentResult<Value> {
262        self.call(BrowserCommand::Back(expected_revision))
263    }
264    /// Go forward if the supplied observation revision is current.
265    pub fn forward(&self, expected_revision: u64) -> DevelopmentResult<Value> {
266        self.call(BrowserCommand::Forward(expected_revision))
267    }
268    /// Reload if the supplied observation revision is current.
269    pub fn reload(&self, expected_revision: u64) -> DevelopmentResult<Value> {
270        self.call(BrowserCommand::Reload(expected_revision))
271    }
272    /// Stop loading if the supplied observation revision is current.
273    pub fn stop_loading(&self, expected_revision: u64) -> DevelopmentResult<Value> {
274        self.call(BrowserCommand::StopLoading(expected_revision))
275    }
276    /// Highlight a target if the supplied observation revision is current.
277    pub fn highlight(&self, target: String, expected_revision: u64) -> DevelopmentResult<Value> {
278        self.call(BrowserCommand::Highlight {
279            target,
280            expected_revision,
281        })
282    }
283    /// Click a target if the supplied observation revision is current.
284    pub fn click(&self, target: String, expected_revision: u64) -> DevelopmentResult<Value> {
285        self.call(BrowserCommand::Click {
286            target,
287            expected_revision,
288        })
289    }
290    /// Type text into the selected or explicit target at the current revision.
291    pub fn type_text(
292        &self,
293        text: String,
294        target: Option<String>,
295        expected_revision: u64,
296    ) -> DevelopmentResult<Value> {
297        self.call(BrowserCommand::Type {
298            text,
299            target,
300            expected_revision,
301        })
302    }
303    /// Scroll by the requested delta at the current observation revision.
304    pub fn scroll(&self, dx: f64, dy: f64, expected_revision: u64) -> DevelopmentResult<Value> {
305        self.call(BrowserCommand::Scroll {
306            dx,
307            dy,
308            expected_revision,
309        })
310    }
311    /// Capture a screenshot of the connected browser.
312    pub fn screenshot(&self) -> DevelopmentResult<Value> {
313        self.call(BrowserCommand::Screenshot)
314    }
315
316    /// Start a workflow from its JSON definition and named inputs.
317    pub fn run_workflow(
318        &self,
319        definition: Value,
320        inputs: BTreeMap<String, Value>,
321    ) -> DevelopmentResult<Value> {
322        self.call(BrowserCommand::RunWorkflow { definition, inputs })
323    }
324
325    /// Pause the active workflow and retain its checkpoint.
326    pub fn pause_workflow(&self) -> DevelopmentResult<Value> {
327        self.call(BrowserCommand::PauseWorkflow)
328    }
329
330    /// Resume a workflow from a caller-provided checkpoint.
331    pub fn resume_workflow(
332        &self,
333        definition: Value,
334        inputs: BTreeMap<String, Value>,
335        checkpoint: Value,
336    ) -> DevelopmentResult<Value> {
337        self.call(BrowserCommand::ResumeWorkflow {
338            definition,
339            inputs,
340            checkpoint,
341        })
342    }
343
344    /// List workflow definitions known to the connected session.
345    pub fn list_workflows(&self) -> DevelopmentResult<Value> {
346        self.call(BrowserCommand::ListWorkflows)
347    }
348
349    /// Cancel the active workflow.
350    pub fn cancel_workflow(&self) -> DevelopmentResult<Value> {
351        self.call(BrowserCommand::CancelWorkflow)
352    }
353
354    /// Verify the active workflow's completion conditions.
355    pub fn verify_workflow(&self) -> DevelopmentResult<Value> {
356        self.call(BrowserCommand::VerifyWorkflow)
357    }
358
359    /// Evaluate a causal verification predicate against the live page.
360    pub fn verify_predicate(
361        &self,
362        predicate: VerificationPredicate,
363        timeout: Duration,
364    ) -> DevelopmentResult<Value> {
365        self.call(BrowserCommand::VerifyPredicate { predicate, timeout })
366    }
367
368    /// Open a remote-view capability for the connected browser.
369    pub fn open_remote_view(&self) -> DevelopmentResult<Value> {
370        self.call(BrowserCommand::RemoteViewOpen)
371    }
372
373    /// Return remote-view status and current capability state.
374    pub fn remote_view_status(&self) -> DevelopmentResult<Value> {
375        self.call(BrowserCommand::RemoteViewStatus)
376    }
377
378    /// Revoke the remote-view capability.
379    pub fn revoke_remote_view(&self) -> DevelopmentResult<Value> {
380        self.call(BrowserCommand::RemoteViewRevoke)
381    }
382}
383struct BrowserWorker {
384    root: PathBuf,
385    policy_preset: PolicyPreset,
386    session: Option<BrowserSession>,
387    revision: Option<u64>,
388    workflow_state: String,
389    active_workflow: Option<String>,
390    last_workflow: Option<(WorkflowDefinition, WorkflowRunResult)>,
391    last_config: Option<BrowserStartConfig>,
392    remote_view: Option<RemoteView>,
393}
394
395impl BrowserWorker {
396    fn new(root: PathBuf, policy_preset: PolicyPreset) -> Self {
397        Self {
398            root,
399            policy_preset,
400            session: None,
401            revision: None,
402            workflow_state: "idle".into(),
403            active_workflow: None,
404            last_workflow: None,
405            last_config: None,
406            remote_view: None,
407        }
408    }
409
410    fn state(&self) -> BrowserRuntimeState {
411        BrowserRuntimeState {
412            policy_preset: self.policy_preset,
413            connected: self.session.is_some(),
414            browser_process_id: self
415                .session
416                .as_ref()
417                .and_then(BrowserSession::owned_chrome_pid),
418            browser_revision: self.revision,
419            workflow_state: self.workflow_state.clone(),
420            active_workflow: self.active_workflow.clone(),
421        }
422    }
423
424    fn session(&self) -> DevelopmentResult<&BrowserSession> {
425        self.session.as_ref().ok_or_else(|| {
426            DevelopmentError::Conflict(
427                "browser is not connected; call glass.browser.start first".into(),
428            )
429        })
430    }
431
432    async fn shutdown(&mut self) {
433        if let Some(view) = self.remote_view.take() {
434            view.revoke().await;
435        }
436        if let Some(session) = self.session.take() {
437            let _ = session.close().await;
438        }
439        self.revision = None;
440        self.workflow_state = "idle".into();
441        self.active_workflow = None;
442        self.last_workflow = None;
443    }
444
445    async fn start_session(&mut self, config: BrowserStartConfig) -> DevelopmentResult<Value> {
446        if self.session.is_some() {
447            return Err(DevelopmentError::Conflict(
448                "browser workspace already has a connected session".into(),
449            ));
450        }
451        let policy = BrowserPolicy::from_preset(self.policy_preset, &self.root)
452            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
453        let mut builder = SessionOptions::builder()
454            .port(config.port)
455            .attach(config.attach)
456            .incognito(config.incognito)
457            .headed(config.headed)
458            .profile(config.profile.clone())
459            .policy(policy);
460        if let Some(path) = config.chrome_path.clone() {
461            builder = builder.chrome_path(path);
462        }
463        let options = builder
464            .build()
465            .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
466        let session = BrowserSession::start(&options)
467            .await
468            .map_err(|error| DevelopmentError::Process(error.to_string()))?;
469        self.revision = Some(1);
470        self.session = Some(session);
471        self.last_config = Some(config);
472        serde_json::to_value(self.state()).map_err(Into::into)
473    }
474
475    async fn execute(&mut self, command: BrowserCommand) -> DevelopmentResult<Value> {
476        self.apply_remote_inputs().await?;
477        match command {
478            BrowserCommand::Start(config) => self.start_session(config).await,
479            BrowserCommand::Reconnect => {
480                let config = self.last_config.clone().ok_or_else(|| {
481                    DevelopmentError::Conflict(
482                        "browser has no prior connection configuration to reconnect".into(),
483                    )
484                })?;
485                self.shutdown().await;
486                self.start_session(config).await
487            }
488            BrowserCommand::Stop => {
489                self.shutdown().await;
490                serde_json::to_value(self.state()).map_err(Into::into)
491            }
492            BrowserCommand::State => serde_json::to_value(self.state()).map_err(Into::into),
493            BrowserCommand::Observe => {
494                let context = self
495                    .session()?
496                    .observe_fresh()
497                    .await
498                    .map_err(browser_error)?;
499                self.revision = Some(context.consistency.end_revision);
500                serde_json::to_value(context).map_err(Into::into)
501            }
502            BrowserCommand::Snapshot => {
503                let snapshot = self.session()?.snapshot().await.map_err(browser_error)?;
504                serde_json::to_value(snapshot).map_err(Into::into)
505            }
506            BrowserCommand::Semantic(level) => {
507                let observation = self
508                    .session()?
509                    .semantic_observe(level)
510                    .await
511                    .map_err(browser_error)?;
512                serde_json::to_value(observation).map_err(Into::into)
513            }
514            BrowserCommand::WebIr => {
515                let ir = self
516                    .session()?
517                    .extract_web_ir(&ExtractionRequest::default_document())
518                    .await
519                    .map_err(browser_error)?;
520                self.revision = Some(ir.revision);
521                serde_json::to_value(WebIrInspectionResult::from_ir(&ir)).map_err(Into::into)
522            }
523            BrowserCommand::Diff => {
524                let delta = self
525                    .session()?
526                    .observe_delta()
527                    .await
528                    .map_err(browser_error)?;
529                self.revision = Some(delta.to_revision);
530                serde_json::to_value(delta).map_err(Into::into)
531            }
532            BrowserCommand::Targets => {
533                let targets = self
534                    .session()?
535                    .list_targets()
536                    .await
537                    .map_err(browser_error)?;
538                serde_json::to_value(targets).map_err(Into::into)
539            }
540            BrowserCommand::SelectTarget(target) => {
541                let selected = self
542                    .session()?
543                    .select_target(&target)
544                    .await
545                    .map_err(browser_error)?;
546                let observation = self
547                    .session()?
548                    .observe_fresh()
549                    .await
550                    .map_err(browser_error)?;
551                self.revision = Some(observation.consistency.end_revision);
552                Ok(serde_json::json!({"target":selected,"observation":observation}))
553            }
554            BrowserCommand::Navigate {
555                url,
556                expected_revision,
557                timeout,
558            } => {
559                let outcome = self
560                    .session()?
561                    .navigate_with_revision(&url, timeout, expected_revision)
562                    .await
563                    .map_err(browser_error)?;
564                let value = serde_json::to_value(outcome)?;
565                self.revision = value.get("currentRevision").and_then(Value::as_u64);
566                Ok(value)
567            }
568            BrowserCommand::Back(expected_revision) => {
569                let outcome = self
570                    .session()?
571                    .go_back_with_revision(expected_revision)
572                    .await
573                    .map_err(browser_error)?;
574                self.revision = Some(outcome.current_revision);
575                serde_json::to_value(outcome).map_err(Into::into)
576            }
577            BrowserCommand::Forward(expected_revision) => {
578                let outcome = self
579                    .session()?
580                    .go_forward_with_revision(expected_revision)
581                    .await
582                    .map_err(browser_error)?;
583                self.revision = Some(outcome.current_revision);
584                serde_json::to_value(outcome).map_err(Into::into)
585            }
586            BrowserCommand::Reload(expected_revision) => {
587                let outcome = self
588                    .session()?
589                    .reload_with_revision(expected_revision)
590                    .await
591                    .map_err(browser_error)?;
592                self.revision = Some(outcome.current_revision);
593                serde_json::to_value(outcome).map_err(Into::into)
594            }
595            BrowserCommand::StopLoading(expected_revision) => {
596                let outcome = self
597                    .session()?
598                    .stop_loading_with_revision(expected_revision)
599                    .await
600                    .map_err(browser_error)?;
601                self.revision = Some(outcome.current_revision);
602                serde_json::to_value(outcome).map_err(Into::into)
603            }
604            BrowserCommand::Highlight {
605                target,
606                expected_revision,
607            } => {
608                self.session()?
609                    .highlight_target_with_revision(&target, expected_revision)
610                    .await
611                    .map_err(browser_error)?;
612                Ok(serde_json::json!({"highlighted":target,"browserRevision":expected_revision}))
613            }
614            BrowserCommand::Click {
615                target,
616                expected_revision,
617            } => {
618                let outcome = self
619                    .session()?
620                    .click_with_revision(&target, expected_revision)
621                    .await
622                    .map_err(browser_error)?;
623                self.revision = Some(outcome.current_revision);
624                serde_json::to_value(outcome).map_err(Into::into)
625            }
626            BrowserCommand::Type {
627                text,
628                target,
629                expected_revision,
630            } => {
631                let outcome = self
632                    .session()?
633                    .type_text_with_expected_revision(
634                        &text,
635                        target.as_deref(),
636                        Some(expected_revision),
637                    )
638                    .await
639                    .map_err(browser_error)?;
640                self.revision = Some(outcome.current_revision);
641                serde_json::to_value(outcome).map_err(Into::into)
642            }
643            BrowserCommand::Scroll {
644                dx,
645                dy,
646                expected_revision,
647            } => {
648                let outcome = self
649                    .session()?
650                    .scroll_with_revision(dx, dy, Some(expected_revision))
651                    .await
652                    .map_err(browser_error)?;
653                self.revision = Some(outcome.current_revision);
654                serde_json::to_value(outcome).map_err(Into::into)
655            }
656            BrowserCommand::Screenshot => {
657                let png = self
658                    .session()?
659                    .screenshot_png()
660                    .await
661                    .map_err(browser_error)?;
662                Ok(serde_json::json!({
663                    "mimeType":"image/png",
664                    "bytes":png.len(),
665                    "base64":base64::Engine::encode(&base64::engine::general_purpose::STANDARD, png)
666                }))
667            }
668            BrowserCommand::RunWorkflow { definition, inputs } => {
669                let workflow = WorkflowDefinition::from_value(definition)
670                    .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
671                self.workflow_state = "running".into();
672                self.active_workflow = Some(workflow.name.clone());
673                let result = self.session()?.run_workflow(&workflow, &inputs).await;
674                self.workflow_state = if result.is_ok() {
675                    "completed"
676                } else {
677                    "failed"
678                }
679                .into();
680                let result = result.map_err(browser_error)?;
681                self.revision = Some(result.final_revision);
682                self.last_workflow = Some((workflow, result.clone()));
683                serde_json::to_value(result).map_err(Into::into)
684            }
685            BrowserCommand::PauseWorkflow => {
686                let (workflow, result) = self.last_workflow.as_ref().ok_or_else(|| {
687                    DevelopmentError::Conflict(
688                        "no workflow result is available to checkpoint".into(),
689                    )
690                })?;
691                let checkpoint = self
692                    .session()?
693                    .export_workflow_checkpoint(workflow, result)
694                    .await
695                    .map_err(browser_error)?;
696                self.workflow_state = "paused".into();
697                serde_json::to_value(checkpoint).map_err(Into::into)
698            }
699            BrowserCommand::ResumeWorkflow {
700                definition,
701                inputs,
702                checkpoint,
703            } => {
704                let workflow = WorkflowDefinition::from_value(definition)
705                    .map_err(|error| DevelopmentError::InvalidInput(error.to_string()))?;
706                let checkpoint: WorkflowCheckpoint = serde_json::from_value(checkpoint)?;
707                self.workflow_state = "running".into();
708                self.active_workflow = Some(workflow.name.clone());
709                let result = self
710                    .session()?
711                    .resume_workflow(&workflow, &inputs, &checkpoint)
712                    .await;
713                self.workflow_state = if result.is_ok() {
714                    "completed"
715                } else {
716                    "failed"
717                }
718                .into();
719                let result = result.map_err(browser_error)?;
720                self.revision = Some(result.final_revision);
721                self.last_workflow = Some((workflow, result.clone()));
722                serde_json::to_value(result).map_err(Into::into)
723            }
724            BrowserCommand::ListWorkflows => Ok(serde_json::json!({
725                "state":self.workflow_state,
726                "active":self.active_workflow,
727                "last":self.last_workflow.as_ref().map(|(definition, result)| serde_json::json!({
728                    "name":definition.name,
729                    "version":definition.workflow_version,
730                    "result":result
731                }))
732            })),
733            BrowserCommand::CancelWorkflow => {
734                if self.workflow_state == "running" {
735                    return Err(DevelopmentError::Conflict(
736                        "workflow cancellation cannot preempt an in-flight synchronous browser command"
737                            .into(),
738                    ));
739                }
740                let previous = self.workflow_state.clone();
741                self.workflow_state = "cancelled".into();
742                self.active_workflow = None;
743                Ok(serde_json::json!({"cancelled":true,"previousState":previous}))
744            }
745            BrowserCommand::VerifyPredicate { predicate, timeout } => {
746                let outcome = self
747                    .session()?
748                    .verify(predicate, timeout)
749                    .await
750                    .map_err(browser_error)?;
751                serde_json::to_value(outcome).map_err(Into::into)
752            }
753            BrowserCommand::VerifyWorkflow => {
754                let (definition, result) = self.last_workflow.as_ref().ok_or_else(|| {
755                    DevelopmentError::Conflict("no workflow result is available to verify".into())
756                })?;
757                Ok(serde_json::json!({
758                    "verified":self.workflow_state == "completed",
759                    "name":definition.name,
760                    "version":definition.workflow_version,
761                    "finalRevision":result.final_revision,
762                    "result":result
763                }))
764            }
765            BrowserCommand::RemoteViewOpen => {
766                if self.remote_view.is_some() {
767                    return Err(DevelopmentError::Conflict("Remote View is already open".into()));
768                }
769                self.session()?;
770                let view = RemoteView::bind().await?;
771                let response = serde_json::json!({
772                    "active":true,
773                    "localUrl":view.local_url(),
774                    "sshForwardHint":view.ssh_forward_hint(),
775                    "loopbackOnly":true,
776                });
777                self.remote_view = Some(view);
778                self.publish_remote_frame().await?;
779                Ok(response)
780            }
781            BrowserCommand::RemoteViewStatus => Ok(self.remote_view.as_ref().map_or_else(
782                || serde_json::json!({"active":false,"loopbackOnly":true}),
783                |view| serde_json::json!({"active":true,"localUrl":view.local_url(),"sshForwardHint":view.ssh_forward_hint(),"loopbackOnly":true}),
784            )),
785            BrowserCommand::RemoteViewRevoke => {
786                if let Some(view) = self.remote_view.take() {
787                    view.revoke().await;
788                    Ok(serde_json::json!({"revoked":true}))
789                } else {
790                    Ok(serde_json::json!({"revoked":false}))
791                }
792            }
793        }
794    }
795
796    async fn publish_remote_frame(&self) -> DevelopmentResult<()> {
797        let (Some(view), Some(session), Some(revision)) = (
798            self.remote_view.as_ref(),
799            self.session.as_ref(),
800            self.revision,
801        ) else {
802            return Ok(());
803        };
804        let png = session.screenshot_png().await.map_err(browser_error)?;
805        let published = view.publish(RemoteFrame {
806            browser_revision: revision,
807            mime_type: "image/png".into(),
808            data: base64::Engine::encode(&base64::engine::general_purpose::STANDARD, png),
809        });
810        if !published {
811            return Err(DevelopmentError::Process(
812                "Remote View rejected the bounded frame".into(),
813            ));
814        }
815        Ok(())
816    }
817
818    async fn apply_remote_inputs(&mut self) -> DevelopmentResult<()> {
819        let mut inputs = Vec::new();
820        if let Some(view) = self.remote_view.as_mut() {
821            while let Ok(input) = view.try_recv_input() {
822                inputs.push(input);
823                if inputs.len() == 64 {
824                    break;
825                }
826            }
827        }
828        for input in inputs {
829            let session = self.session()?;
830            let revision = input.expected_revision();
831            let current_revision = match input {
832                RemoteInput::Click { x, y, .. } => {
833                    let (width, height) = session.viewport_size().await.map_err(browser_error)?;
834                    session
835                        .click_at_with_revision(x * width, y * height, Some(revision))
836                        .await
837                        .map_err(browser_error)?
838                        .revision
839                }
840                RemoteInput::Scroll { dx, dy, .. } => {
841                    session
842                        .scroll_with_revision(dx, dy, Some(revision))
843                        .await
844                        .map_err(browser_error)?
845                        .current_revision
846                }
847                RemoteInput::Key { key, .. } => {
848                    session
849                        .key_press_with_revision(&key, Some(revision))
850                        .await
851                        .map_err(browser_error)?
852                        .current_revision
853                }
854                RemoteInput::Text { text, .. } => {
855                    session
856                        .type_text_with_expected_revision(&text, None, Some(revision))
857                        .await
858                        .map_err(browser_error)?
859                        .current_revision
860                }
861            };
862            self.revision = Some(current_revision);
863        }
864        if self.remote_view.is_some() {
865            self.publish_remote_frame().await?;
866        }
867        Ok(())
868    }
869}
870
871fn browser_error(error: Box<dyn std::error::Error>) -> DevelopmentError {
872    DevelopmentError::Process(error.to_string())
873}
874
875#[cfg(test)]
876mod tests {
877    use super::*;
878    use std::io::{Read, Write};
879    use std::net::{TcpListener, TcpStream};
880    use std::sync::Arc;
881    use std::sync::atomic::{AtomicBool, Ordering};
882
883    #[test]
884    fn disconnected_service_reports_authoritative_state() {
885        let service = BrowserService::new(std::env::temp_dir()).unwrap();
886        let state = service.state().unwrap();
887        assert_eq!(state["connected"], false);
888        assert_eq!(state["workflowState"], "idle");
889        let error = service.observe().unwrap_err();
890        assert!(error.to_string().contains("glass.browser.start"));
891        assert_eq!(service.remote_view_status().unwrap()["active"], false);
892        let web_ir_error = service.web_ir().unwrap_err();
893        assert!(web_ir_error.to_string().contains("glass.browser.start"));
894        assert!(
895            service
896                .open_remote_view()
897                .unwrap_err()
898                .to_string()
899                .contains("browser")
900        );
901        assert_eq!(service.revoke_remote_view().unwrap()["revoked"], false);
902    }
903
904    #[test]
905    fn explicit_browser_policy_is_exposed_before_startup() {
906        let service =
907            BrowserService::new_with_policy(std::env::temp_dir(), PolicyPreset::Hardened).unwrap();
908        let state = service.state().unwrap();
909        assert_eq!(state["policyPreset"], "hardened");
910        assert_eq!(state["connected"], false);
911    }
912
913    #[test]
914    fn resident_browser_executes_revision_safe_fixture_flow() {
915        if std::env::var("GLASS_E2E").as_deref() != Ok("1") {
916            return;
917        }
918        let chrome_path =
919            std::env::var("GLASS_CHROME_PATH").expect("GLASS_E2E=1 requires GLASS_CHROME_PATH");
920        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
921        listener.set_nonblocking(true).unwrap();
922        let address = listener.local_addr().unwrap();
923        let running = Arc::new(AtomicBool::new(true));
924        let server_running = Arc::clone(&running);
925        let server = std::thread::spawn(move || {
926            let html = br#"<!doctype html><title>Resident Glass</title><label>Name<input id="name"></label><button id="save" onclick="document.querySelector('p').textContent='Saved '+document.querySelector('#name').value">Save</button><p></p>"#;
927            while server_running.load(Ordering::Relaxed) {
928                match listener.accept() {
929                    Ok((mut stream, _)) => {
930                        let mut request = [0; 4096];
931                        let _ = stream.read(&mut request);
932                        let header = format!(
933                            "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
934                            html.len()
935                        );
936                        let _ = stream.write_all(header.as_bytes());
937                        let _ = stream.write_all(html);
938                    }
939                    Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
940                        std::thread::sleep(Duration::from_millis(5));
941                    }
942                    Err(_) => break,
943                }
944            }
945        });
946        let port_probe = TcpListener::bind("127.0.0.1:0").unwrap();
947        let browser_port = port_probe.local_addr().unwrap().port();
948        drop(port_probe);
949
950        let service = BrowserService::new(std::env::temp_dir()).unwrap();
951        let started = service
952            .start(BrowserStartConfig {
953                port: browser_port,
954                chrome_path: Some(chrome_path.into()),
955                ..BrowserStartConfig::default()
956            })
957            .unwrap();
958        let browser_pid = started["browserProcessId"].as_u64().unwrap() as u32;
959        let initial = service.observe().unwrap();
960        let initial_revision = initial["consistency"]["end_revision"]
961            .as_u64()
962            .or_else(|| initial["consistency"]["endRevision"].as_u64())
963            .unwrap();
964        service
965            .navigate(
966                format!("http://{address}/fixture.html"),
967                initial_revision,
968                Duration::from_secs(30),
969            )
970            .unwrap();
971        assert!(
972            service
973                .navigate(
974                    format!("http://{address}/stale"),
975                    initial_revision,
976                    Duration::from_secs(30),
977                )
978                .unwrap_err()
979                .to_string()
980                .contains("revision")
981        );
982        let observed = service.observe().unwrap();
983        assert_eq!(observed["page"]["title"], "Resident Glass");
984        assert!(
985            service
986                .snapshot()
987                .unwrap()
988                .as_object()
989                .is_some_and(|snapshot| !snapshot.is_empty())
990        );
991        assert_eq!(
992            service
993                .semantic(SemanticObservationLevel::Structured)
994                .unwrap()["page"]["title"],
995            "Resident Glass"
996        );
997        let web_ir = service.web_ir().unwrap();
998        assert!(web_ir["revision"].as_u64().is_some());
999        assert!(web_ir["entityCount"].as_u64().unwrap_or_default() > 0);
1000        assert!(web_ir["actionableEntities"].is_array());
1001        assert!(service.diff().unwrap()["toRevision"].as_u64().is_some());
1002        let revision = observed["consistency"]["end_revision"]
1003            .as_u64()
1004            .or_else(|| observed["consistency"]["endRevision"].as_u64())
1005            .unwrap();
1006        let typed = service
1007            .type_text("Ada".into(), Some("Name".into()), revision)
1008            .unwrap();
1009        let revision = typed["currentRevision"].as_u64().unwrap();
1010        service.click("Save".into(), revision).unwrap();
1011        assert!(
1012            service.observe().unwrap()["text"]
1013                .as_str()
1014                .unwrap()
1015                .contains("Saved Ada")
1016        );
1017        let remote = service.open_remote_view().unwrap();
1018        assert_eq!(remote["active"], true);
1019        assert!(
1020            remote["localUrl"]
1021                .as_str()
1022                .unwrap()
1023                .starts_with("http://127.0.0.1:")
1024        );
1025        assert_eq!(service.remote_view_status().unwrap()["active"], true);
1026        assert_eq!(service.revoke_remote_view().unwrap()["revoked"], true);
1027        let observed = service.observe().unwrap();
1028        let revision = observed["consistency"]["end_revision"]
1029            .as_u64()
1030            .or_else(|| observed["consistency"]["endRevision"].as_u64())
1031            .unwrap();
1032        assert_eq!(service.reload(revision).unwrap()["action"], "reload");
1033        service.stop().unwrap();
1034        #[cfg(unix)]
1035        assert!(unsafe { libc::kill(browser_pid as i32, 0) } == -1);
1036        let port_closed = (0..100).any(|_| {
1037            if TcpStream::connect(("127.0.0.1", browser_port)).is_err() {
1038                true
1039            } else {
1040                std::thread::sleep(Duration::from_millis(10));
1041                false
1042            }
1043        });
1044        assert!(port_closed, "owned browser endpoint survived resident stop");
1045        running.store(false, Ordering::Relaxed);
1046        server.join().unwrap();
1047    }
1048}