glass_browser/lib.rs
1//! Local, revision-safe browser intelligence for Chrome and Chromium.
2//!
3//! `glass-browser` provides an owned/attached browser [`BrowserSession`],
4//! structured semantic observation, guarded actions, stable Web IR, Task
5//! Protocol compilation/execution, workflows, advisory knowledge, policy,
6//! MCP, daemon, TUI, backend, surface, presentation, and reliability contracts.
7//!
8//! Glass does not bundle a browser, host a browser service, or infer an
9//! autonomous plan. Callers select operations; Glass validates current
10//! evidence, policy, capabilities, revisions, unique targeting, and bounded
11//! postconditions. CDP is the production backend. WebDriver BiDi remains an
12//! experimental bounded adapter.
13//!
14//! The docs.rs page documents the Rust library API; installed command behavior
15//! is specified in the [CLI reference](https://github.com/wanazhar/glass/blob/main/docs/cli.md).
16//!
17//! # Choose an entry point
18//!
19//! | Goal | Entry point |
20//! |---|---|
21//! | Drive an owned or attached browser | [`BrowserSession`] and [`SessionOptions`] |
22//! | Collect stable evidence | [`extraction`] and [`web_ir`] |
23//! | Compile/execute semantic tasks | [`task_protocol`] and [`task_compiler`] |
24//! | Run typed workflows | [`browser::session::WorkflowDefinition`] |
25//! | Share standalone/embedded browser UI state | [`browser_workspace`] |
26//! | Assess scoped historical knowledge | [`KnowledgeStore`] |
27//! | Implement/select a backend | [`browser_backend`] and [`browser::BackendFactory`] |
28//! | Expose MCP or canonical requests | [`mcp`] and [`protocol`] |
29//! | Present terminal frames | [`presentation`] and [`terminal_graphics`] |
30//!
31//! # Browser lifecycle
32//!
33//! Start, navigate, observe, and explicitly close an owned session:
34//!
35//! ```rust,no_run
36//! use glass_browser::{BrowserSession, SessionOptions};
37//!
38//! # async fn run() -> glass_browser::BrowserResult<()> {
39//! let options = SessionOptions::builder().incognito(true).build()?;
40//! let session = BrowserSession::start(&options).await?;
41//! let page = session.navigate("https://example.com").await?;
42//! let observation = session.observe().await?;
43//! println!("{} revision={}", page.url, observation.accessibility.revision);
44//! session.close().await?;
45//! # Ok(())
46//! # }
47//! ```
48//!
49//! `close` sends `Browser.close` before process fallback so owned profile state
50//! can flush. Attach mode does not own or close the external Chrome process.
51//! [`SessionOptions::validate`] rejects incompatible attach/launch settings.
52//!
53//! # Structured observation and guarded action
54//!
55//! Compact observation is the default low-cost context. Semantic observation
56//! exposes typed page, region, target, record, route, and revision state:
57//!
58//! ```rust,no_run
59//! use glass_browser::browser::session::SemanticObservationLevel;
60//! use glass_browser::{BrowserSession, SessionOptions};
61//!
62//! # async fn run() -> glass_browser::BrowserResult<()> {
63//! let session = BrowserSession::start(&SessionOptions::builder().build()?).await?;
64//! let semantic = session
65//! .semantic_observe(SemanticObservationLevel::Interactive)
66//! .await?;
67//! println!("regions={}", semantic.regions.len());
68//!
69//! let current = session.observe().await?;
70//! let outcome = session
71//! .click_with_revision(
72//! "role=button[name=Save]",
73//! current.accessibility.revision,
74//! )
75//! .await?;
76//! println!("status={:?}", outcome.status);
77//! session.close().await
78//! # }
79//! ```
80//!
81//! Normal observation does not request a screenshot, full DOM, or form values.
82//! Those evidence paths are explicit and policy-sensitive. A locator must
83//! resolve exactly one actionable current target. A stale expected revision
84//! fails before input.
85//!
86//! # Evidence, Web IR, and tasks
87//!
88//! [`ExtractionRequest`] selects source-labelled evidence and hard budgets.
89//! [`BrowserSession::extract_web_ir`] reconciles it into stable
90//! [`GlassWebIrV1`]. Offline callers can validate, diff, and classify
91//! continuity without starting Chrome.
92//!
93//! [`GlassTask::from_json`] validates a strict authored semantic task.
94//! [`compile_task`] compiles it against Web IR without browser access or side
95//! effects. Plans and receipts contain input names but never authored input
96//! values or live browser references. Live execution re-extracts evidence,
97//! binds every semantic key to exactly one current revisioned target, applies
98//! confirmation/lease rules, and verifies postconditions.
99//! The offline JSON example uses the application's direct `serde_json`
100//! dependency; typed session APIs do not require callers to serialize
101//! intermediate contracts.
102//!
103//! ```rust,no_run
104//! use glass_browser::{compile_task, GlassTask, GlassWebIrV1};
105//!
106//! fn compile(task_json: &str, ir_json: &str)
107//! -> Result<String, Box<dyn std::error::Error>>
108//! {
109//! let task = GlassTask::from_json(task_json)?;
110//! let ir: GlassWebIrV1 = serde_json::from_str(ir_json)?;
111//! ir.validate()?;
112//! Ok(compile_task(&task, &ir)?.to_canonical_json()?)
113//! }
114//! ```
115//!
116//! Historical knowledge is advisory. It may explain or rank current evidence,
117//! but cannot supply an executable reference or authorize mutation.
118//!
119//! # Cargo features
120//!
121//! - `visual-compare` enables PNG comparison helpers for explicit screenshot
122//! checks.
123//! - `fuzzing` enables test-only fuzz hooks and is not for normal applications.
124//!
125//! docs.rs builds all features. The default library remains browser-focused.
126//!
127//! # Failure and privacy rules
128//!
129//! Unknown variants/fields, oversized input, stale revisions, ambiguous
130//! targets, unsafe paths, unsupported capabilities, and incompatible backend
131//! responses fail explicitly. An `indeterminate` mutation result means Chrome
132//! may have accepted input; reconcile current state instead of retrying
133//! blindly.
134//!
135//! Treat DOM, screenshots, PDFs, cookies, storage, evaluated values, profiles,
136//! and diagnostics as sensitive. MCP stdout is protocol-only. Structured
137//! audit and execution receipts omit typed values, raw selectors, raw CDP
138//! errors, and browser handles.
139//!
140//! # Module map
141//!
142//! - [`browser`] — Chrome lifecycle, CDP client, DOM/accessibility parsing,
143//! policy, profiles, actions, observations, workflows, and knowledge.
144//! - [`browser_backend`] — semantic backend capabilities, requests, responses,
145//! errors, and mandatory dispatcher.
146//! - [`capabilities`] — versioned discovery and negotiation manifest.
147//! - [`cli`] — Clap argument definitions and command dispatch.
148//! - [`connection`] — independent layout, transport, graphics, shell,
149//! multiplexer, presentation-policy, and observatory contracts.
150//! - [`daemon`] — local Unix-socket lifecycle, isolated MCP children, leases,
151//! logs, and interrupted-run recovery.
152//! - [`extensions`] — bounded manifests, permissions, registry, sandbox, and
153//! guarded action boundary.
154//! - [`extraction`] — strict bounded evidence requests and source-labelled facts.
155//! - [`mcp`] — JSON-RPC/MCP stdio server, prompts, resources, and tools.
156//! - [`presentation`] — browser-neutral frame metadata, geometry, mailbox,
157//! ownership, and metrics.
158//! - [`protocol`] — canonical versioned request/response operations.
159//! - [`reliability`] / [`reliability_runner`] — scenarios, replay evidence,
160//! scorecards, gates, and bounded browser execution.
161//! - [`results`] — agent-facing response projections and local diagnostic
162//! artifacts.
163//! - [`surfaces`] — nested surface evidence, coverage, provenance, and grants.
164//! - [`task_protocol`] / [`task_compiler`] — strict authored tasks and
165//! deterministic execution plans.
166//! - [`terminal_graphics`] — Herdr, Kitty, ANSI, and semantic render adapters.
167//! - [`tui`] — standalone Ratatui reducer, responsive layouts, semantic
168//! selection, and bounded Herdr/Kitty/ANSI live presentation.
169//! - [`web_ir`] — stable reconciliation, validation, diff, and continuity.
170//! - [`workspace`] — identity, ownership, lifecycle, attachments, and
171//! persistence.
172//!
173//! # Guides and examples
174//!
175//! - [Rust SDK](https://github.com/wanazhar/glass/blob/main/docs/rust-sdk.md)
176//! - [Runnable examples](https://github.com/wanazhar/glass/blob/main/docs/examples.md)
177//! - [Complete feature reference](https://github.com/wanazhar/glass/blob/main/docs/features.md)
178//! - [MCP tool catalog](https://github.com/wanazhar/glass/blob/main/docs/mcp-tools.md)
179//! - [Security policy](https://github.com/wanazhar/glass/blob/main/SECURITY.md)
180
181/// Browser control modules and the reusable [`browser::BrowserSession`] API.
182pub mod browser;
183/// Transport-neutral backend capability contract.
184pub mod browser_backend;
185/// Canonical human-facing browser state, actions, focus, and recovery model.
186pub mod browser_workspace;
187/// Versioned Glass protocol and capability negotiation.
188pub mod capabilities;
189/// Command-line argument definitions and dispatch helpers.
190pub mod cli;
191/// Independent connection-environment and presentation-policy contracts.
192pub mod connection;
193/// Local Unix-socket daemon lifecycle and MCP bridge.
194pub mod daemon;
195/// Validated extension metadata and permission boundaries.
196pub mod extensions;
197/// Experimental bounded browser-evidence extraction contracts.
198pub mod extraction;
199/// MCP stdio server, prompts, resources, and tool dispatch.
200pub mod mcp;
201/// Browser-neutral terminal frame presentation contracts.
202pub mod presentation;
203/// Transport-neutral versioned request and response envelopes.
204pub mod protocol;
205/// Versioned browser-free reliability scenario contracts.
206pub mod reliability;
207/// Bounded browser execution for reliability scenarios and replay evidence.
208pub mod reliability_runner;
209/// Bounded agent-facing response projections and local result artifacts.
210pub mod results;
211/// Bounded, evidenced browser surface contracts.
212pub mod surfaces;
213/// Browser-free deterministic Task Protocol execution-plan compiler.
214pub mod task_compiler;
215/// Strict, bounded authored Task Protocol v1 inputs.
216pub mod task_protocol;
217/// Bounded terminal graphics adapters.
218pub mod terminal_graphics;
219/// Ratatui terminal interface.
220pub mod tui;
221mod update;
222/// Stable Glass Web IR v1 reconciliation and validation.
223pub mod web_ir;
224/// Bounded workspace identity and lifecycle contracts.
225pub mod workspace;
226
227// Keep the most common embedding types on the crate root. Lower-level and
228// capability-specific APIs remain organized under `glass_browser::browser`.
229pub use browser::{
230 AccessibilityDiffSummary, ActionContractError, ActionFailureKind, ActionKind, ActionOutcome,
231 ActionStatus, ActionVerificationEvidence, BackendFactory, BackendStartup, BidiBackendConfig,
232 BidiBrowserBackend, BrowserResult, BrowserSession, KnowledgeAssessment,
233 KnowledgeAssessmentSignal, KnowledgeAssessmentStatus, KnowledgeBackendCapability,
234 KnowledgeBackendKind, KnowledgeBackendProvenance, KnowledgeConfidence,
235 KnowledgeCurrentValidation, KnowledgeCurrentValidationStatus, KnowledgeEmbeddingProvider,
236 KnowledgeEvidenceQuality, KnowledgeGraph, KnowledgeGraphEdge, KnowledgeGraphNode,
237 KnowledgeGraphNodeKind, KnowledgeGraphTraversal, KnowledgeInvalidation,
238 KnowledgeLearningPolicy, KnowledgeLearningRequest, KnowledgeLearningResult,
239 KnowledgeLifecycleEvent, KnowledgeLookupContext, KnowledgeLookupOptions,
240 KnowledgeMemoryInfluence, KnowledgeObservationMode, KnowledgeObservationReport,
241 KnowledgePortability, KnowledgeProfileScope, KnowledgePurgeResult, KnowledgeRecord,
242 KnowledgeRecordBuildOptions, KnowledgeRecordKind, KnowledgeRejectionReason,
243 KnowledgeRetrievalCandidate, KnowledgeRetrievalExplanation, KnowledgeRetrievalQuery,
244 KnowledgeRetrievalReport, KnowledgeRetrievalSignal, KnowledgeRetrievalSignalKind,
245 KnowledgeScope, KnowledgeScopeSelector, KnowledgeSignalKind, KnowledgeSource, KnowledgeStore,
246 KnowledgeStoreChange, KnowledgeStoreError, KnowledgeStoreLimits, KnowledgeStoreSnapshot,
247 KnowledgeStoreStats, KnowledgeSurfaceCoverage, KnowledgeSurfaceKind,
248 KnowledgeSurfaceProvenance, KnowledgeUnderstandingLevel, KnowledgeValidationError,
249 KnowledgeVerifiedWorkflowEvidence, MAX_KNOWLEDGE_RECORDS, NavigationOutcome, PageInfo,
250 ProofBackend, SessionOptions, SessionOptionsBuilder, StartedBackend, TaskExecutionReceipt,
251 TaskExecutionResult, TaskPostconditionReceipt, TaskStepResult, WorkflowBudgets,
252 WorkflowCheckpoint, WorkflowCheckpointPage, WorkflowCheckpointStep, WorkflowDefinition,
253 WorkflowInput, WorkflowOutput, WorkflowOutputDeclaration, WorkflowOutputSource,
254 WorkflowResumeError, WorkflowResumePlan, WorkflowRunResult, WorkflowRunStatus, WorkflowStep,
255 WorkflowStepRecord, WorkflowStepState, WorkflowTerminalProof, WorkflowTrace,
256 WorkflowTraceEvent, WorkflowTransactionClass, WorkflowValidationError, WorkflowValueType,
257};
258
259pub use task_protocol::{
260 GlassTask, TASK_PROTOCOL_SCHEMA_VERSION, TaskAmbiguityPolicy, TaskKind, TaskLimits,
261 TaskPostcondition, TaskPostconditionKind, TaskProtocolError, TaskRevisionPolicy, TaskRiskClass,
262 TaskScope,
263};
264
265pub use task_compiler::{
266 TASK_COMPILER_VERSION, TASK_PLAN_SCHEMA_VERSION, TaskCompilationError, TaskCompilationOptions,
267 TaskEntityBindingKey, TaskEntityEvidenceRequirement, TaskEvidenceRequirements,
268 TaskExecutionPlan, TaskPlanOperation, TaskPlanPrecondition, TaskPlanStep,
269 TaskRuntimeCapability, compile_task, compile_task_with_knowledge, compile_task_with_options,
270};
271
272pub use protocol::{
273 GLASS_PROTOCOL_VERSION, TASK_COMPILE_OPERATION, TASK_VALIDATE_OPERATION, TaskCompilePayload,
274 TaskCompileResult, TaskValidationPayload, TaskValidationResult, WEB_IR_CONTINUITY_OPERATION,
275 WEB_IR_DIFF_OPERATION, WEB_IR_INSPECT_OPERATION, WEB_IR_VALIDATE_OPERATION, WebIrCompactEntity,
276 WebIrContinuityPayload, WebIrContinuityResult, WebIrDiffPayload, WebIrDiffResult,
277 WebIrInspectionResult, WebIrPayload, WebIrValidationResult, compile_task_request,
278 compile_task_result, validate_task_result, web_ir_continuity_result, web_ir_diff_result,
279 web_ir_inspect_result, web_ir_validate_result,
280};
281pub use results::{
282 DetailAvailability, ExperienceResult, OperationResult, RESULT_SCHEMA_VERSION, ResponseMode,
283 ResultArtifact, ResultStore, ResultStoreError,
284};
285
286/// Re-export the bounded extraction contract for embedding callers.
287pub use extraction::{
288 EXTRACTION_CONTRACT_SCHEMA_VERSION, EvidenceCoverage, EvidenceFact, EvidenceQuality,
289 EvidenceRelationshipHint, EvidenceSource, ExtractionBudgets, ExtractionContractError,
290 ExtractionEvidence, ExtractionEvidenceLimits, ExtractionRequest, ExtractionScope,
291 MAX_EXTRACTION_DEPTH, MAX_EXTRACTION_DURATION_MS, MAX_EXTRACTION_NODES,
292 MAX_EXTRACTION_OUTPUT_BYTES, MAX_EXTRACTION_TEXT_BYTES, extract_page_context,
293};
294
295/// Re-export the stable Glass Web IR v1 contract for embedding callers.
296pub use web_ir::{
297 GlassWebIrDiff, GlassWebIrV1, RelationshipHintDiagnosticStatus, WEB_IR_SCHEMA_VERSION,
298 WebIrAction, WebIrChangeKind, WebIrDocument, WebIrEntity, WebIrEntityChange,
299 WebIrEntityContinuity, WebIrEntityContinuityStatus, WebIrEntityDetails, WebIrEntityKind,
300 WebIrEntityState, WebIrFixtureExpectation, WebIrRelationship, WebIrRelationshipChange,
301 WebIrRelationshipHintDiagnostic, WebIrRelationshipKind, WebIrScopeKind, WebIrSensitivity,
302 WebIrValidationError, reconcile_evidence,
303};