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
| Goal | Entry point |
|---|---|
| Drive an owned or attached browser | BrowserSession and SessionOptions |
| Collect stable evidence | extraction and web_ir |
| Compile/execute semantic tasks | task_protocol and task_compiler |
| Run typed workflows | browser::session::WorkflowDefinition |
| Share standalone/embedded browser UI state | browser_workspace |
| Assess scoped historical knowledge | KnowledgeStore |
| Implement/select a backend | browser_backend and browser::BackendFactory |
| Expose MCP or canonical requests | mcp and protocol |
| Present terminal frames | presentation 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().awaitNormal 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-compareenables PNG comparison helpers for explicit screenshot checks.fuzzingenables 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::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::BrowserSessionAPI. 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.