Skip to main content

Crate glass_browser

Crate glass_browser 

Source
Expand description

Local, revision-safe browser intelligence for Chrome and Chromium.

glass-browser provides an owned/attached browser BrowserSession, structured semantic observation, guarded actions, stable Web IR, Task Protocol compilation/execution, workflows, advisory knowledge, policy, MCP, daemon, TUI, backend, surface, presentation, and reliability contracts.

Glass does not bundle a browser, host a browser service, or infer an autonomous plan. Callers select operations; Glass validates current evidence, policy, capabilities, revisions, unique targeting, and bounded postconditions. CDP is the production backend. WebDriver BiDi remains an experimental bounded adapter.

The docs.rs page documents the Rust library API; installed command behavior is specified in the CLI reference.

§Choose an entry point

GoalEntry point
Drive an owned or attached browserBrowserSession and SessionOptions
Collect stable evidenceextraction and web_ir
Compile/execute semantic taskstask_protocol and task_compiler
Run typed workflowsbrowser::session::WorkflowDefinition
Share standalone/embedded browser UI statebrowser_workspace
Assess scoped historical knowledgeKnowledgeStore
Implement/select a backendbrowser_backend and browser::BackendFactory
Expose MCP or canonical requestsmcp and protocol
Present terminal framespresentation and terminal_graphics

§Browser lifecycle

Start, navigate, observe, and explicitly close an owned session:

use glass_browser::{BrowserSession, SessionOptions};

let options = SessionOptions::builder().incognito(true).build()?;
let session = BrowserSession::start(&options).await?;
let page = session.navigate("https://example.com").await?;
let observation = session.observe().await?;
println!("{} revision={}", page.url, observation.accessibility.revision);
session.close().await?;

close sends Browser.close before process fallback so owned profile state can flush. Attach mode does not own or close the external Chrome process. SessionOptions::validate rejects incompatible attach/launch settings.

§Structured observation and guarded action

Compact observation is the default low-cost context. Semantic observation exposes typed page, region, target, record, route, and revision state:

use glass_browser::browser::session::SemanticObservationLevel;
use glass_browser::{BrowserSession, SessionOptions};

let session = BrowserSession::start(&SessionOptions::builder().build()?).await?;
let semantic = session
    .semantic_observe(SemanticObservationLevel::Interactive)
    .await?;
println!("regions={}", semantic.regions.len());

let current = session.observe().await?;
let outcome = session
    .click_with_revision(
        "role=button[name=Save]",
        current.accessibility.revision,
    )
    .await?;
println!("status={:?}", outcome.status);
session.close().await

Normal observation does not request a screenshot, full DOM, or form values. Those evidence paths are explicit and policy-sensitive. A locator must resolve exactly one actionable current target. A stale expected revision fails before input.

§Evidence, Web IR, and tasks

ExtractionRequest selects source-labelled evidence and hard budgets. BrowserSession::extract_web_ir reconciles it into stable GlassWebIrV1. Offline callers can validate, diff, and classify continuity without starting Chrome.

GlassTask::from_json validates a strict authored semantic task. compile_task compiles it against Web IR without browser access or side effects. Plans and receipts contain input names but never authored input values or live browser references. Live execution re-extracts evidence, binds every semantic key to exactly one current revisioned target, applies confirmation/lease rules, and verifies postconditions. The offline JSON example uses the application’s direct serde_json dependency; typed session APIs do not require callers to serialize intermediate contracts.

use glass_browser::{compile_task, GlassTask, GlassWebIrV1};

fn compile(task_json: &str, ir_json: &str)
    -> Result<String, Box<dyn std::error::Error>>
{
    let task = GlassTask::from_json(task_json)?;
    let ir: GlassWebIrV1 = serde_json::from_str(ir_json)?;
    ir.validate()?;
    Ok(compile_task(&task, &ir)?.to_canonical_json()?)
}

Historical knowledge is advisory. It may explain or rank current evidence, but cannot supply an executable reference or authorize mutation.

§Cargo features

  • visual-compare enables PNG comparison helpers for explicit screenshot checks.
  • fuzzing enables test-only fuzz hooks and is not for normal applications.

docs.rs builds all features. The default library remains browser-focused.

§Failure and privacy rules

Unknown variants/fields, oversized input, stale revisions, ambiguous targets, unsafe paths, unsupported capabilities, and incompatible backend responses fail explicitly. An indeterminate mutation result means Chrome may have accepted input; reconcile current state instead of retrying blindly.

Treat DOM, screenshots, PDFs, cookies, storage, evaluated values, profiles, and diagnostics as sensitive. MCP stdout is protocol-only. Structured audit and execution receipts omit typed values, raw selectors, raw CDP errors, and browser handles.

§Module map

  • browser — Chrome lifecycle, CDP client, DOM/accessibility parsing, policy, profiles, actions, observations, workflows, and knowledge.
  • browser_backend — semantic backend capabilities, requests, responses, errors, and mandatory dispatcher.
  • capabilities — versioned discovery and negotiation manifest.
  • cli — Clap argument definitions and command dispatch.
  • connection — independent layout, transport, graphics, shell, multiplexer, presentation-policy, and observatory contracts.
  • daemon — local Unix-socket lifecycle, isolated MCP children, leases, logs, and interrupted-run recovery.
  • extensions — bounded manifests, permissions, registry, sandbox, and guarded action boundary.
  • extraction — strict bounded evidence requests and source-labelled facts.
  • mcp — JSON-RPC/MCP stdio server, prompts, resources, and tools.
  • presentation — browser-neutral frame metadata, geometry, mailbox, ownership, and metrics.
  • protocol — canonical versioned request/response operations.
  • reliability / reliability_runner — scenarios, replay evidence, scorecards, gates, and bounded browser execution.
  • results — agent-facing response projections and local diagnostic artifacts.
  • surfaces — nested surface evidence, coverage, provenance, and grants.
  • task_protocol / task_compiler — strict authored tasks and deterministic execution plans.
  • terminal_graphics — Herdr, Kitty, ANSI, and semantic render adapters.
  • tui — standalone Ratatui reducer, responsive layouts, semantic selection, and bounded Herdr/Kitty/ANSI live presentation.
  • web_ir — stable reconciliation, validation, diff, and continuity.
  • workspace — identity, ownership, lifecycle, attachments, and persistence.

§Guides and examples

Re-exports§

pub use browser::AccessibilityDiffSummary;
pub use browser::ActionContractError;
pub use browser::ActionFailureKind;
pub use browser::ActionKind;
pub use browser::ActionOutcome;
pub use browser::ActionStatus;
pub use browser::ActionVerificationEvidence;
pub use browser::BackendFactory;
pub use browser::BackendStartup;
pub use browser::BidiBackendConfig;
pub use browser::BidiBrowserBackend;
pub use browser::BrowserResult;
pub use browser::BrowserSession;
pub use browser::KnowledgeAssessment;
pub use browser::KnowledgeAssessmentSignal;
pub use browser::KnowledgeAssessmentStatus;
pub use browser::KnowledgeBackendCapability;
pub use browser::KnowledgeBackendKind;
pub use browser::KnowledgeBackendProvenance;
pub use browser::KnowledgeConfidence;
pub use browser::KnowledgeCurrentValidation;
pub use browser::KnowledgeCurrentValidationStatus;
pub use browser::KnowledgeEmbeddingProvider;
pub use browser::KnowledgeEvidenceQuality;
pub use browser::KnowledgeGraph;
pub use browser::KnowledgeGraphEdge;
pub use browser::KnowledgeGraphNode;
pub use browser::KnowledgeGraphNodeKind;
pub use browser::KnowledgeGraphTraversal;
pub use browser::KnowledgeInvalidation;
pub use browser::KnowledgeLearningPolicy;
pub use browser::KnowledgeLearningRequest;
pub use browser::KnowledgeLearningResult;
pub use browser::KnowledgeLifecycleEvent;
pub use browser::KnowledgeLookupContext;
pub use browser::KnowledgeLookupOptions;
pub use browser::KnowledgeMemoryInfluence;
pub use browser::KnowledgeObservationMode;
pub use browser::KnowledgeObservationReport;
pub use browser::KnowledgePortability;
pub use browser::KnowledgeProfileScope;
pub use browser::KnowledgePurgeResult;
pub use browser::KnowledgeRecord;
pub use browser::KnowledgeRecordBuildOptions;
pub use browser::KnowledgeRecordKind;
pub use browser::KnowledgeRejectionReason;
pub use browser::KnowledgeRetrievalCandidate;
pub use browser::KnowledgeRetrievalExplanation;
pub use browser::KnowledgeRetrievalQuery;
pub use browser::KnowledgeRetrievalReport;
pub use browser::KnowledgeRetrievalSignal;
pub use browser::KnowledgeRetrievalSignalKind;
pub use browser::KnowledgeScope;
pub use browser::KnowledgeScopeSelector;
pub use browser::KnowledgeSignalKind;
pub use browser::KnowledgeSource;
pub use browser::KnowledgeStore;
pub use browser::KnowledgeStoreChange;
pub use browser::KnowledgeStoreError;
pub use browser::KnowledgeStoreLimits;
pub use browser::KnowledgeStoreSnapshot;
pub use browser::KnowledgeStoreStats;
pub use browser::KnowledgeSurfaceCoverage;
pub use browser::KnowledgeSurfaceKind;
pub use browser::KnowledgeSurfaceProvenance;
pub use browser::KnowledgeUnderstandingLevel;
pub use browser::KnowledgeValidationError;
pub use browser::KnowledgeVerifiedWorkflowEvidence;
pub use browser::MAX_KNOWLEDGE_RECORDS;
pub use browser::NavigationOutcome;
pub use browser::PageInfo;
pub use browser::ProofBackend;
pub use browser::SessionOptions;
pub use browser::SessionOptionsBuilder;
pub use browser::StartedBackend;
pub use browser::TaskExecutionReceipt;
pub use browser::TaskExecutionResult;
pub use browser::TaskPostconditionReceipt;
pub use browser::TaskStepResult;
pub use browser::WorkflowBudgets;
pub use browser::WorkflowCheckpoint;
pub use browser::WorkflowCheckpointPage;
pub use browser::WorkflowCheckpointStep;
pub use browser::WorkflowDefinition;
pub use browser::WorkflowInput;
pub use browser::WorkflowOutput;
pub use browser::WorkflowOutputDeclaration;
pub use browser::WorkflowOutputSource;
pub use browser::WorkflowResumeError;
pub use browser::WorkflowResumePlan;
pub use browser::WorkflowRunResult;
pub use browser::WorkflowRunStatus;
pub use browser::WorkflowStep;
pub use browser::WorkflowStepRecord;
pub use browser::WorkflowStepState;
pub use browser::WorkflowTerminalProof;
pub use browser::WorkflowTrace;
pub use browser::WorkflowTraceEvent;
pub use browser::WorkflowTransactionClass;
pub use browser::WorkflowValidationError;
pub use browser::WorkflowValueType;
pub use task_protocol::GlassTask;
pub use task_protocol::TASK_PROTOCOL_SCHEMA_VERSION;
pub use task_protocol::TaskAmbiguityPolicy;
pub use task_protocol::TaskKind;
pub use task_protocol::TaskLimits;
pub use task_protocol::TaskPostcondition;
pub use task_protocol::TaskPostconditionKind;
pub use task_protocol::TaskProtocolError;
pub use task_protocol::TaskRevisionPolicy;
pub use task_protocol::TaskRiskClass;
pub use task_protocol::TaskScope;
pub use task_compiler::TASK_COMPILER_VERSION;
pub use task_compiler::TASK_PLAN_SCHEMA_VERSION;
pub use task_compiler::TaskCompilationError;
pub use task_compiler::TaskCompilationOptions;
pub use task_compiler::TaskEntityBindingKey;
pub use task_compiler::TaskEntityEvidenceRequirement;
pub use task_compiler::TaskEvidenceRequirements;
pub use task_compiler::TaskExecutionPlan;
pub use task_compiler::TaskPlanOperation;
pub use task_compiler::TaskPlanPrecondition;
pub use task_compiler::TaskPlanStep;
pub use task_compiler::TaskRuntimeCapability;
pub use task_compiler::compile_task;
pub use task_compiler::compile_task_with_knowledge;
pub use task_compiler::compile_task_with_options;
pub use protocol::GLASS_PROTOCOL_VERSION;
pub use protocol::TASK_COMPILE_OPERATION;
pub use protocol::TASK_VALIDATE_OPERATION;
pub use protocol::TaskCompilePayload;
pub use protocol::TaskCompileResult;
pub use protocol::TaskValidationPayload;
pub use protocol::TaskValidationResult;
pub use protocol::WEB_IR_CONTINUITY_OPERATION;
pub use protocol::WEB_IR_DIFF_OPERATION;
pub use protocol::WEB_IR_INSPECT_OPERATION;
pub use protocol::WEB_IR_VALIDATE_OPERATION;
pub use protocol::WebIrCompactEntity;
pub use protocol::WebIrContinuityPayload;
pub use protocol::WebIrContinuityResult;
pub use protocol::WebIrDiffPayload;
pub use protocol::WebIrDiffResult;
pub use protocol::WebIrInspectionResult;
pub use protocol::WebIrPayload;
pub use protocol::WebIrValidationResult;
pub use protocol::compile_task_request;
pub use protocol::compile_task_result;
pub use protocol::validate_task_result;
pub use protocol::web_ir_continuity_result;
pub use protocol::web_ir_diff_result;
pub use protocol::web_ir_inspect_result;
pub use protocol::web_ir_validate_result;
pub use results::DetailAvailability;
pub use results::ExperienceResult;
pub use results::OperationResult;
pub use results::RESULT_SCHEMA_VERSION;
pub use results::ResponseMode;
pub use results::ResultArtifact;
pub use results::ResultStore;
pub use results::ResultStoreError;
pub use extraction::EXTRACTION_CONTRACT_SCHEMA_VERSION;
pub use extraction::EvidenceCoverage;
pub use extraction::EvidenceFact;
pub use extraction::EvidenceQuality;
pub use extraction::EvidenceRelationshipHint;
pub use extraction::EvidenceSource;
pub use extraction::ExtractionBudgets;
pub use extraction::ExtractionContractError;
pub use extraction::ExtractionEvidence;
pub use extraction::ExtractionEvidenceLimits;
pub use extraction::ExtractionRequest;
pub use extraction::ExtractionScope;
pub use extraction::MAX_EXTRACTION_DEPTH;
pub use extraction::MAX_EXTRACTION_DURATION_MS;
pub use extraction::MAX_EXTRACTION_NODES;
pub use extraction::MAX_EXTRACTION_OUTPUT_BYTES;
pub use extraction::MAX_EXTRACTION_TEXT_BYTES;
pub use extraction::extract_page_context;
pub use web_ir::GlassWebIrDiff;
pub use web_ir::GlassWebIrV1;
pub use web_ir::RelationshipHintDiagnosticStatus;
pub use web_ir::WEB_IR_SCHEMA_VERSION;
pub use web_ir::WebIrAction;
pub use web_ir::WebIrChangeKind;
pub use web_ir::WebIrDocument;
pub use web_ir::WebIrEntity;
pub use web_ir::WebIrEntityChange;
pub use web_ir::WebIrEntityContinuity;
pub use web_ir::WebIrEntityContinuityStatus;
pub use web_ir::WebIrEntityDetails;
pub use web_ir::WebIrEntityKind;
pub use web_ir::WebIrEntityState;
pub use web_ir::WebIrFixtureExpectation;
pub use web_ir::WebIrRelationship;
pub use web_ir::WebIrRelationshipChange;
pub use web_ir::WebIrRelationshipHintDiagnostic;
pub use web_ir::WebIrRelationshipKind;
pub use web_ir::WebIrScopeKind;
pub use web_ir::WebIrSensitivity;
pub use web_ir::WebIrValidationError;
pub use web_ir::reconcile_evidence;

Modules§

browser
Browser control modules and the reusable browser::BrowserSession API. Browser lifecycle, transport adapters, policy, profiles, and sessions.
browser_backend
Transport-neutral backend capability contract. Transport-neutral browser capability contracts.
browser_workspace
Canonical human-facing browser state, actions, focus, and recovery model. Canonical human-facing browser workspace shared by both Glass products.
capabilities
Versioned Glass protocol and capability negotiation. Versioned Glass protocol and capability negotiation.
cli
Command-line argument definitions and dispatch helpers. CLI argument parsing and command dispatch.
connection
Independent connection-environment and presentation-policy contracts. Independent connection-environment and presentation-policy contracts.
daemon
Local Unix-socket daemon lifecycle and MCP bridge. Local Unix-socket daemon lifecycle and client bridge.
extensions
Validated extension metadata and permission boundaries. Validated extension metadata and least-privilege permissions.
extraction
Experimental bounded browser-evidence extraction contracts. Stable bounded evidence-extraction contract and browser-observation adapter.
mcp
MCP stdio server, prompts, resources, and tool dispatch. Model Context Protocol (MCP) server.
presentation
Browser-neutral terminal frame presentation contracts. Browser-neutral, bounded contracts for browser frame presentation.
protocol
Transport-neutral versioned request and response envelopes. Transport-neutral Glass request and response envelopes.
reliability
Versioned browser-free reliability scenario contracts. Browser-free reliability scenario contracts.
reliability_runner
Bounded browser execution for reliability scenarios and replay evidence. Bounded browser execution for versioned reliability scenarios.
results
Bounded agent-facing response projections and local result artifacts. Bounded, redacted result contracts and local diagnostic artifacts.
surfaces
Bounded, evidenced browser surface contracts. Stable, bounded, transport-neutral browser surface contracts.
task_compiler
Browser-free deterministic Task Protocol execution-plan compiler. Deterministic compilation from authored tasks and stable Glass Web IR v1.
task_protocol
Strict, bounded authored Task Protocol v1 inputs. Strict, bounded authored tasks for deterministic Web IR compilation.
terminal_graphics
Bounded terminal graphics adapters. Browser-neutral terminal graphics negotiation and bounded frame rendering.
tui
Ratatui terminal interface. Terminal user interface (Ratatui).
web_ir
Stable Glass Web IR v1 reconciliation and validation. Stable, bounded Glass Web IR v1 reconciliation and validation.
workspace
Bounded workspace identity and lifecycle contracts. Bounded, browser-free identity and ownership contracts for Glass workspaces.