glass-browser 0.3.2

Local browser intelligence runtime with semantic memory, verified workflows, multi-surface understanding, CLI, TUI, MCP, and Rust APIs
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
//! MCP resource definitions.
//!
//! Static reference documents (contracts, guides) exposed through the MCP
//! `resources/list` and `resources/read` methods.

use serde_json::Value;

use crate::browser::session::BrowserResult;

struct ResourceDef {
    uri: &'static str,
    name: &'static str,
    description: &'static str,
    mime_type: &'static str,
    content: &'static str,
}

/// Return all MCP resources (static reference documents) as a JSON value
/// for the `resources/list` response.
pub fn list_resources() -> BrowserResult<Value> {
    let resources: Vec<Value> = RESOURCES
        .iter()
        .map(|r| {
            serde_json::json!({
                "uri": r.uri,
                "name": r.name,
                "description": r.description,
                "mimeType": r.mime_type,
            })
        })
        .collect();
    Ok(serde_json::json!({ "resources": resources }))
}

/// Return a specific MCP resource by URI with its markdown content, for
/// the `resources/read` response.
pub fn read_resource(uri: &str) -> BrowserResult<Value> {
    let resource =
        RESOURCES
            .iter()
            .find(|r| r.uri == uri)
            .ok_or_else(|| -> Box<dyn std::error::Error> {
                format!("resource not found: {uri}").into()
            })?;
    Ok(serde_json::json!({
        "contents": [{
            "uri": resource.uri,
            "mimeType": resource.mime_type,
            "text": resource.content,
        }]
    }))
}

// ── Resource content ────────────────────────────────────────────

const RESOURCE_LOCATORS: &str = r#"# Glass Locator Grammar

## Explicit forms

Every Glass target string must use an explicit prefix:

| Prefix | Syntax | Example |
|--------|--------|---------|
| `ref=` | Revisioned backend-node reference | `ref=r12:b456` |
| `name=` | Accessible name (case-sensitive, exact match) | `name=Submit` |
| `role=...;name=...` | ARIA role + accessible name | `role=button;name=Save` |
| `text=` | Visible text content (exact match) | `text=Click here` |
| `css=` | CSS selector (must resolve uniquely) | `css=button.save` |
| `ordinal=` | Zero-based position in last `observe` interactive list | `ordinal=3` |

## Fallback chains

Multiple strategies separated by ` | ` (pipe surrounded by spaces):

```
name=Save | css=button.save | css=[type='submit']
```

Rules:
- Max 8 segments, max 1024 bytes per segment.
- Evaluated left to right, short-circuit on first `Unique`.
- Only `NotFound` advances to the next segment.
- `Ambiguous` and `StaleReference` stop the chain immediately.
- Single locator strings without ` | ` behave identically to today.

## Resolution outcomes

- `Unique` — exactly one element matched; action proceeds.
- `Ambiguous` — multiple elements matched; up to 8 bounded candidate
  summaries returned. Agent must refine, not guess.
- `NotFound` — zero matches.
- `StaleReference` — revision prefix does not match current snapshot.
"#;

const RESOURCE_ERRORS: &str = r#"# Glass Typed Errors

## Revision-safe action contract

All targeted mutations accept an optional `expectedRevision`, including
`navigate`, `click`, `clickExpectPopup`, `doubleClick`, `type`, `clear`,
`check`, `uncheck`, `select`, `scroll`, keyboard actions, drag, upload, and
`fillForm`. Successful revision-aware actions return `status`,
`previousRevision`, `currentRevision`, and bounded `verification` metadata.
When the revision no longer matches, the action fails before mutation with
`kind: "stale_revision"`, `phase: "preflight"`, `recovery: "observe"`, and
`recoveryStrategy: "report"`.

The `verify` tool accepts bounded predicates for URL, title, visibility, text,
popup, dialog, download, revision, and Boolean `all`/`any`/`not` composition.
The `batch` tool supports `fixed`, `chain`, and `unguarded` revision modes.

## Targeting errors (`TargetError`)

Targeting failures serialize `kind` and `failureKind`, with optional bounded
`reason`, `candidates`, `recovery`, and `diagnostics` fields:

| `kind` | `failureKind` | Meaning |
|--------|---------------|---------|
| `not_found` | `target_not_found` | Zero elements matched; re-observe |
| `ambiguous` | `ambiguous_target` | Multiple matches; refine the locator |
| `stale_reference` | `stale_revision` | Revision changed; re-observe |
| `not_actionable` | `verification_failed` | The matched element failed actionability checks |

`reason` is a bounded actionability enum such as `disabled`,
`hit_test_blocked`, or `outside_viewport`; it is not a top-level error kind.

## Policy errors (`PolicyErrorContract`)

Every policy failure is a versioned object with these fields:
`schemaVersion`, `policyVersion`, `kind`, optional `operation`, `ruleId`,
`phase`, `reason`, optional `remediation`, and `overridePossible`.
`kind` is one of:

| `kind` | `phase` | Meaning |
|--------|---------|---------|
| `denied` | `preflight` | Capability denied by the active policy |
| `confirmation_required` | `preflight` | One confirmation token is required |
| `invalid_configuration` | `configuration` | Policy configuration is invalid |

`operation` uses the stable snake-case capability name, for example
`read_sensitive_extraction`. A confirmation-required result is not approved
implicitly by an MCP request; configure a one-use token with
`--policy-confirm-once` or change the fixed server policy before retrying.
`overridePossible` indicates whether changing policy or supplying a token can
resolve the failure.

## Wait timeout (`WaitTimeout`)

A timeout serializes `condition`, `deadlineMs`, bounded `lastState`, `reason`,
and an optional bounded `observedPage`. It does not use a generic
`recoverable` flag; callers should use the condition and last state to choose
whether to retry.

## General rules

- Typed errors expose stable machine-readable fields before free-text details.
- Recovery metadata is bounded and must not be treated as permission to retry.
- Error payloads never contain raw page content, evaluated source, or secrets.

"#;

const RESOURCE_LIMITS: &str = r#"# Glass Observation Budgets & Limits

## Compact observe (`observe`)

| Budget | Limit |
|--------|-------|
| Interactive controls | 32 (`COMPACT_AX_MAX_INTERACTIVE`) |
| Accessibility nodes | 128 |
| Visible text | 16 KiB UTF-8 |
| AX label text total | 4 KiB UTF-8 |
| Role name | 64 bytes each |
| Topology events | 64 |
| Targets in list | 32 |
| Frames in list | 128 |

## `controls_truncated: true`

When the page has more than 32 interactive controls, Glass ranks them by
deterministic role priority and stable document order, then returns the top
32. The `omittedCount` field reports how many were excluded. Use
`ranking=document-order` in the library API when comparing against legacy
traversal order.

When `includeFormValues` is enabled, at most 16 known form controls are read;
values are capped at 256 bytes, select labels at 128 bytes, and sensitive
fields are redacted unless `read_sensitive_form_values` is explicitly allowed.

Structured extraction accepts at most 32 fields. Field names are limited to
128 bytes and paths to 512 bytes. `maxItems` is 1..256 (default 64), and
`maxBytes` is 1..256 KiB (default 64 KiB). `startIndex` and continuation
`nextIndex` are bounded to 256. Continuation route IDs are limited to 128
bytes and route URLs to 2 KiB.

Structured extraction of secret-like fields requires the dedicated
`read_sensitive_extraction` capability; form-value permissions do not grant it.

`preflight` performs a read-only resolution and hit test without pointer
events, focus, or scrolling. `clickAt` is the policy-gated exact-coordinate
escape hatch for canvas and map surfaces.

## `incomplete` reasons

| Reason | Meaning |
|--------|---------|
| `ShadowBoundary` | Open/closed shadow DOM detected; controls inside shadows may be missing |
| `ControlsTruncated` | Exceeded 32-control budget |
| `TextTruncated` | Visible text exceeded 16 KiB |
| `MutationRace` | Page mutated during collection; snapshot is inconsistent |

## Other limits

| Resource | Limit |
|----------|-------|
| Candidate summaries in `Ambiguous` | 8 |
| Candidate label text each | 160 bytes |
| Locator fallback chain segments | 8 |
| Locator segment bytes | 1024 |
| Dialog wait timeout | 500 ms |
| Download timeout | 30 s |
| Diagnostic duration | 30 s |
| Wait timeout default | 10 s |
"#;

const RESOURCE_ACTIONS: &str = r#"# Glass Action Contract

Every action result has a session-local `executionId`, a page `revision`, and
bounded verification evidence. Revisioned actions reject stale observations
before dispatch. Failures carry a typed `kind`, `phase`, `recoveryStrategy`,
and bounded recovery hint.

Use `verify` for explicit postconditions. Its predicates are finite and
deadline-bound; arbitrary JavaScript is not accepted. Use batch `mode: fixed`
to reuse one revision, `mode: chain` to carry revisions forward, or
`mode: unguarded` for compatibility behavior.
"#;

const RESOURCE_TOPOLOGY: &str = r#"# Glass Target & Frame Topology

## Target lifecycle

- `createTarget(url)` creates a new page target. It is not automatically
  selected.
- `selectTarget(id)` switches the active target. All subsequent operations
  (observe, click, type, etc.) run against this target.
- `closeTarget(id)` closes a target. Glass never auto-selects a replacement
  — the session is left without an active target until `selectTarget` is
  called.
- `listTargets()` returns up to 32 bounded page targets with ID, URL, and
  title.

## Frame selection

- `selectFrame(id)` sets the frame execution context within the active
  target.
- `listFrames()` returns up to 128 frames with parent linkage.
- Without explicit frame selection, operations run in the top-level frame.

## Popup management

- `click` on an opener element, then `listTargets` to discover the newly
  opened page, then `selectTarget` to work with it.
- Glass never silently selects a new popup or tab.
- Topology events (in `observe.topology`) report target creation and
  closure with `kind` + `id`.

## Attach mode

- `--attach` connects to an existing Chrome instance via CDP port.
- In attach mode, Glass does not own the browser lifecycle (does not
  close Chrome on exit).
- Attach mode reports `attachMode: true` in session metadata.
"#;

const RESOURCE_EXPERIENCE: &str = r#"# Glass Experience Layer

CLI, MCP, daemon, and Rust callers share capability-oriented operations:

- `workspace/*` identifies lifecycle, profile ownership, and scoped resource references.
- `memory/*` is advisory only; fresh Web IR, revision, policy, and capability evidence remain authoritative.
- `surfaces/*` reports understanding, coverage, and provenance; opaque and coordinate-only surfaces cannot compile semantic actions.
- `backend/*` reports declared capabilities and portability. Omitted capabilities fail closed.
- `replay/*` validates, compares, and attaches bounded redacted evidence without browser side effects.

Experience responses always expose a schema version, interface provenance, and
typed `resourceRefs` (when a workspace resource is known). A resource reference
is scoped to a workspace/profile and ephemeral generation; it is not an
executable locator or a mutation grant.

One daemon actor lease serializes workspace mutation. `observe`, `inspect`,
`extract`, `resolve`, `verify`, and replay operations are read-only and do not
acquire that lease. Mutation requires the current lease token and revision;
expiry or scope mismatch fails closed.

Replay diff/attach validates exact scenario and recording hashes, redacted event
shape, and bounded input size. Attach means attaching evidence metadata only;
it never starts Chrome, connects to an external browser, or grants takeover.

Every result is bounded and carries provenance, policy, portability, verification, and
workflow timeline fields when available. Partial backend or surface gates are reported
honestly and are never promoted to real-browser parity.
"#;

// ── Resource definitions ────────────────────────────────────────

const RESOURCES: &[ResourceDef] = &[
    ResourceDef {
        uri: "glass://contract/actions",
        name: "Action Execution Contract",
        description: "Revision guards, execution identities, verification predicates, and batch modes",
        mime_type: "text/markdown",
        content: RESOURCE_ACTIONS,
    },
    ResourceDef {
        uri: "glass://contract/locators",
        name: "Locator Grammar",
        description: "Locator forms, ambiguity rules, and delimiter syntax for targeting",
        mime_type: "text/markdown",
        content: RESOURCE_LOCATORS,
    },
    ResourceDef {
        uri: "glass://contract/errors",
        name: "Typed Errors & Recovery",
        description: "Typed targeting, policy, and timeout errors with bounded recovery metadata",
        mime_type: "text/markdown",
        content: RESOURCE_ERRORS,
    },
    ResourceDef {
        uri: "glass://contract/experience",
        name: "Experience Layer",
        description: "Shared workspace, memory, surface, backend, replay, policy, and result contracts",
        mime_type: "text/markdown",
        content: RESOURCE_EXPERIENCE,
    },
    ResourceDef {
        uri: "glass://contract/limits",
        name: "Observation Budgets & Limits",
        description: "Observation caps (32 controls, 16 KiB text) and incompleteness reasons",
        mime_type: "text/markdown",
        content: RESOURCE_LIMITS,
    },
    ResourceDef {
        uri: "glass://contract/topology",
        name: "Target & Frame Topology",
        description: "Target and frame selection semantics, attach rules, and popup management",
        mime_type: "text/markdown",
        content: RESOURCE_TOPOLOGY,
    },
];

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn lists_all_resources() {
        let result = list_resources().unwrap();
        let resources = result["resources"].as_array().unwrap();
        assert_eq!(resources.len(), 6);
        let uris: Vec<&str> = resources
            .iter()
            .map(|r| r["uri"].as_str().unwrap())
            .collect();
        assert!(uris.contains(&"glass://contract/actions"));
        assert!(uris.contains(&"glass://contract/locators"));
        assert!(uris.contains(&"glass://contract/errors"));
        assert!(uris.contains(&"glass://contract/limits"));
        assert!(uris.contains(&"glass://contract/topology"));
        assert!(uris.contains(&"glass://contract/experience"));
    }

    #[test]
    fn reads_each_resource_with_correct_mime_type() {
        for uri in &[
            "glass://contract/actions",
            "glass://contract/locators",
            "glass://contract/errors",
            "glass://contract/limits",
            "glass://contract/topology",
        ] {
            let result = read_resource(uri).unwrap();
            let contents = result["contents"].as_array().unwrap();
            assert_eq!(contents.len(), 1);
            assert_eq!(contents[0]["uri"].as_str().unwrap(), *uri);
            assert_eq!(contents[0]["mimeType"].as_str().unwrap(), "text/markdown");
            let text = contents[0]["text"].as_str().unwrap();
            assert!(!text.is_empty());
        }
    }

    #[test]
    fn limits_resource_documents_dedicated_extraction_capability() {
        let resource = read_resource("glass://contract/limits").unwrap();
        let text = resource["contents"][0]["text"].as_str().unwrap();
        assert!(text.contains("read_sensitive_extraction"));
        assert!(text.contains("form-value permissions do not grant it"));
    }

    #[test]
    fn rejects_unknown_resource() {
        assert!(read_resource("glass://nonexistent").is_err());
    }

    #[test]
    fn total_static_payload_under_32kib() {
        let mut total = 0usize;
        for resource in RESOURCES {
            total += resource.uri.len()
                + resource.name.len()
                + resource.description.len()
                + resource.content.len();
        }
        assert!(
            total <= 32 * 1024,
            "total resource payload {} exceeds 32 KiB",
            total
        );
    }
}