1use serde::{Deserialize, Serialize};
8use serde_json::Value;
9use std::collections::BTreeMap;
10
11pub const GLASS_PROTOCOL_VERSION: u32 = 1;
13const MAX_ID_BYTES: usize = 128;
14const MAX_OPERATION_BYTES: usize = 96;
15const MAX_ERROR_CODE_BYTES: usize = 64;
16const MAX_MESSAGE_BYTES: usize = 512;
17const MAX_ERROR_DETAILS_BYTES: usize = 16 * 1024;
18const MAX_DEADLINE_MS: u64 = 15 * 60 * 1_000;
19
20pub const WEB_IR_VALIDATE_OPERATION: &str = "webIr.validate";
22pub const WEB_IR_INSPECT_OPERATION: &str = "webIr.inspect";
24pub const WEB_IR_DIFF_OPERATION: &str = "webIr.diff";
26pub const WEB_IR_CONTINUITY_OPERATION: &str = "webIr.continuity";
28pub const TASK_COMPILE_OPERATION: &str = "task.compile";
30pub const TASK_VALIDATE_OPERATION: &str = "task.validate";
32pub const TASK_EXECUTE_OPERATION: &str = "task.execute";
34
35pub const EXPERIENCE_INSPECT_OPERATION: &str = "experience.inspect";
38pub const EXPERIENCE_EXTRACT_OPERATION: &str = "experience.extract";
39pub const EXPERIENCE_RESOLVE_OPERATION: &str = "experience.resolve";
40pub const EXPERIENCE_ACT_OPERATION: &str = "experience.act";
41pub const EXPERIENCE_VERIFY_OPERATION: &str = "experience.verify";
42pub const EXPERIENCE_CAPTURE_OPERATION: &str = "experience.capture";
43pub const EXPERIENCE_REPLAY_OPERATION: &str = "experience.replay";
44pub const EXPERIENCE_DIFF_OPERATION: &str = "experience.diff";
45pub const EXPERIENCE_ATTACH_OPERATION: &str = "experience.attach";
46
47#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
49#[serde(rename_all = "camelCase", deny_unknown_fields)]
50pub struct TaskCompilePayload {
51 pub task: crate::task_protocol::GlassTask,
52 pub ir: crate::web_ir::GlassWebIrV1,
53}
54
55impl TaskCompilePayload {
56 pub fn validate(&self) -> Result<(), ProtocolError> {
58 self.task
59 .validate()
60 .map_err(|error| ProtocolError::TaskCompilation(error.into()))?;
61 self.ir.validate().map_err(ProtocolError::WebIrValidation)
62 }
63}
64
65#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
67#[serde(rename_all = "camelCase", deny_unknown_fields)]
68pub struct TaskExecutionPayload {
69 pub task: crate::task_protocol::GlassTask,
70 pub expected_revision: u64,
71 #[serde(default)]
72 pub confirmed: bool,
73}
74
75impl TaskExecutionPayload {
76 pub fn validate(&self) -> Result<(), ProtocolError> {
78 self.task.validate().map_err(ProtocolError::TaskValidation)
79 }
80}
81
82#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
84#[serde(rename_all = "camelCase", deny_unknown_fields)]
85pub struct TaskValidationPayload {
86 pub task: crate::task_protocol::GlassTask,
87}
88
89impl TaskValidationPayload {
90 pub fn validate(&self) -> Result<(), ProtocolError> {
92 self.task.validate().map_err(ProtocolError::TaskValidation)
93 }
94}
95
96#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
98#[serde(rename_all = "camelCase", deny_unknown_fields)]
99pub struct WebIrPayload {
100 pub ir: crate::web_ir::GlassWebIrV1,
101}
102
103impl WebIrPayload {
104 pub fn validate(&self) -> Result<(), ProtocolError> {
106 self.ir.validate().map_err(ProtocolError::WebIrValidation)
107 }
108}
109
110#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
112#[serde(rename_all = "camelCase", deny_unknown_fields)]
113pub struct WebIrDiffPayload {
114 pub before: crate::web_ir::GlassWebIrV1,
115 pub after: crate::web_ir::GlassWebIrV1,
116}
117
118impl WebIrDiffPayload {
119 pub fn validate(&self) -> Result<(), ProtocolError> {
121 self.before
122 .validate()
123 .map_err(ProtocolError::WebIrValidation)?;
124 self.after
125 .validate()
126 .map_err(ProtocolError::WebIrValidation)?;
127 self.before
128 .validate_revision_transition(&self.after)
129 .map_err(ProtocolError::WebIrValidation)?;
130 Ok(())
131 }
132}
133
134#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
136#[serde(rename_all = "camelCase", deny_unknown_fields)]
137pub struct WebIrContinuityPayload {
138 pub before: crate::web_ir::GlassWebIrV1,
139 pub after: crate::web_ir::GlassWebIrV1,
140 pub entity_id: String,
141}
142
143impl WebIrContinuityPayload {
144 pub fn validate(&self) -> Result<(), ProtocolError> {
146 self.before
147 .validate()
148 .map_err(ProtocolError::WebIrValidation)?;
149 self.after
150 .validate()
151 .map_err(ProtocolError::WebIrValidation)?;
152 self.before
153 .validate_revision_transition(&self.after)
154 .map_err(ProtocolError::WebIrValidation)?;
155 validate_identifier(&self.entity_id, "entityId")
156 }
157}
158
159#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
161#[serde(rename_all = "camelCase", deny_unknown_fields)]
162pub struct TaskCompileResult {
163 pub plan: crate::task_compiler::TaskExecutionPlan,
164}
165
166#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
168#[serde(rename_all = "camelCase", deny_unknown_fields)]
169pub struct TaskValidationResult {
170 pub valid: bool,
171 pub schema_version: u32,
172 pub task: crate::task_protocol::TaskKind,
173}
174
175#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
177#[serde(rename_all = "camelCase", deny_unknown_fields)]
178pub struct WebIrValidationResult {
179 pub valid: bool,
180 pub schema_version: u32,
181 pub revision: u64,
182}
183
184impl WebIrValidationResult {
185 pub fn from_ir(ir: &crate::web_ir::GlassWebIrV1) -> Self {
187 Self {
188 valid: true,
189 schema_version: ir.schema_version,
190 revision: ir.revision,
191 }
192 }
193}
194
195#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
197#[serde(rename_all = "camelCase", deny_unknown_fields)]
198pub struct WebIrInspectionResult {
199 pub schema_version: u32,
200 pub revision: u64,
201 pub entity_count: usize,
202 pub relationship_count: usize,
203 pub coverage: crate::extraction::EvidenceCoverage,
204 pub truncated: bool,
205 pub opaque_regions: u32,
206 pub diagnostic_count: usize,
207 pub relationship_hint_diagnostic_count: usize,
208 #[serde(default)]
209 pub entity_kind_counts: BTreeMap<String, usize>,
210 #[serde(default)]
211 pub actionable_entities: Vec<WebIrCompactEntity>,
212}
213
214#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
215#[serde(rename_all = "camelCase", deny_unknown_fields)]
216pub struct WebIrCompactEntity {
217 pub id: String,
218 pub kind: crate::web_ir::WebIrEntityKind,
219 #[serde(default, skip_serializing_if = "Option::is_none")]
220 pub role: Option<String>,
221 #[serde(default, skip_serializing_if = "Option::is_none")]
222 pub name: Option<String>,
223 pub sensitivity: crate::web_ir::WebIrSensitivity,
224 pub supported_actions: Vec<crate::web_ir::WebIrAction>,
225}
226
227impl WebIrInspectionResult {
228 pub fn from_ir(ir: &crate::web_ir::GlassWebIrV1) -> Self {
230 let mut entity_kind_counts = BTreeMap::new();
231 for entity in &ir.entities {
232 let kind = serde_json::to_value(entity.kind)
233 .ok()
234 .and_then(|value| value.as_str().map(str::to_owned))
235 .unwrap_or_else(|| "unknown".into());
236 *entity_kind_counts.entry(kind).or_default() += 1;
237 }
238 let actionable_entities = ir
239 .entities
240 .iter()
241 .filter_map(|entity| {
242 let details = ir.entity_details.get(&entity.id)?;
243 (!details.supported_actions.is_empty()).then(|| WebIrCompactEntity {
244 id: entity.id.clone(),
245 kind: entity.kind,
246 role: entity.role.clone(),
247 name: entity.name.clone(),
248 sensitivity: details.sensitivity,
249 supported_actions: details.supported_actions.clone(),
250 })
251 })
252 .take(16)
253 .collect();
254 Self {
255 schema_version: ir.schema_version,
256 revision: ir.revision,
257 entity_count: ir.entities.len(),
258 relationship_count: ir.relationships.len(),
259 coverage: ir.coverage.clone(),
260 truncated: ir.limits.truncated,
261 opaque_regions: ir.coverage.opaque_regions,
262 diagnostic_count: ir.diagnostics.len(),
263 relationship_hint_diagnostic_count: ir.relationship_hint_diagnostics.len(),
264 entity_kind_counts,
265 actionable_entities,
266 }
267 }
268}
269
270#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
272#[serde(rename_all = "camelCase", deny_unknown_fields)]
273pub struct WebIrDiffResult {
274 pub schema_version: u32,
275 pub from_revision: u64,
276 pub to_revision: u64,
277 pub entity_added_count: usize,
278 pub entity_removed_count: usize,
279 pub entity_changed_count: usize,
280 pub relationship_added_count: usize,
281 pub relationship_removed_count: usize,
282 pub coverage_changed: bool,
283 pub limits_changed: bool,
284 pub diagnostics_changed: bool,
285 pub relationship_hint_diagnostics_changed: bool,
286}
287
288impl WebIrDiffResult {
289 pub fn from_diff(diff: &crate::web_ir::GlassWebIrDiff) -> Self {
291 Self {
292 schema_version: diff.schema_version,
293 from_revision: diff.from_revision,
294 to_revision: diff.to_revision,
295 entity_added_count: diff
296 .entity_changes
297 .iter()
298 .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Added)
299 .count(),
300 entity_removed_count: diff
301 .entity_changes
302 .iter()
303 .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Removed)
304 .count(),
305 entity_changed_count: diff
306 .entity_changes
307 .iter()
308 .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Changed)
309 .count(),
310 relationship_added_count: diff
311 .relationship_changes
312 .iter()
313 .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Added)
314 .count(),
315 relationship_removed_count: diff
316 .relationship_changes
317 .iter()
318 .filter(|change| change.kind == crate::web_ir::WebIrChangeKind::Removed)
319 .count(),
320 coverage_changed: diff.coverage_changed,
321 limits_changed: diff.limits_changed,
322 diagnostics_changed: diff.diagnostics_changed,
323 relationship_hint_diagnostics_changed: diff.relationship_hint_diagnostics_changed,
324 }
325 }
326}
327
328#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
330#[serde(rename_all = "camelCase", deny_unknown_fields)]
331pub struct WebIrContinuityResult {
332 pub requested_id: String,
333 pub status: crate::web_ir::WebIrEntityContinuityStatus,
334 #[serde(skip_serializing_if = "Option::is_none")]
335 pub current_id: Option<String>,
336 pub reason: String,
337}
338
339impl From<crate::web_ir::WebIrEntityContinuity> for WebIrContinuityResult {
340 fn from(continuity: crate::web_ir::WebIrEntityContinuity) -> Self {
341 Self {
342 requested_id: continuity.requested_id,
343 status: continuity.status,
344 current_id: continuity.current_id,
345 reason: continuity.reason,
346 }
347 }
348}
349
350impl TaskCompileResult {
351 pub fn validate(&self) -> Result<(), ProtocolError> {
353 self.plan.validate().map_err(ProtocolError::TaskCompilation)
354 }
355}
356
357#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
359#[serde(rename_all = "camelCase", deny_unknown_fields)]
360pub struct MutationLeaseRef {
361 pub session_id: String,
362 pub token: String,
363}
364
365#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
367#[serde(rename_all = "camelCase", deny_unknown_fields)]
368pub struct GlassRequest {
369 pub protocol_version: u32,
370 pub request_id: String,
371 #[serde(skip_serializing_if = "Option::is_none")]
372 pub correlation_id: Option<String>,
373 #[serde(skip_serializing_if = "Option::is_none")]
374 pub session_id: Option<String>,
375 #[serde(skip_serializing_if = "Option::is_none")]
376 pub mutation_lease: Option<MutationLeaseRef>,
377 pub operation: String,
378 pub payload: Value,
379 #[serde(skip_serializing_if = "Option::is_none")]
380 pub deadline_ms: Option<u64>,
381}
382
383impl GlassRequest {
384 pub fn validate(&self) -> Result<(), ProtocolError> {
386 if self.protocol_version != GLASS_PROTOCOL_VERSION {
387 return Err(ProtocolError::UnsupportedVersion(self.protocol_version));
388 }
389 validate_identifier(&self.request_id, "requestId")?;
390 if let Some(correlation_id) = &self.correlation_id {
391 validate_identifier(correlation_id, "correlationId")?;
392 }
393 if let Some(session_id) = &self.session_id {
394 validate_identifier(session_id, "sessionId")?;
395 }
396 if let Some(lease) = &self.mutation_lease {
397 validate_identifier(&lease.session_id, "mutationLease.sessionId")?;
398 validate_identifier(&lease.token, "mutationLease.token")?;
399 }
400 if let (Some(session_id), Some(lease)) = (&self.session_id, &self.mutation_lease)
401 && session_id != &lease.session_id
402 {
403 return Err(ProtocolError::InvalidField(
404 "sessionId must match mutationLease.sessionId".into(),
405 ));
406 }
407 if self.operation.is_empty() || self.operation.len() > MAX_OPERATION_BYTES {
408 return Err(ProtocolError::InvalidField(
409 "operation must be a bounded non-empty string".into(),
410 ));
411 }
412 if self.operation.chars().any(char::is_whitespace) {
413 return Err(ProtocolError::InvalidField(
414 "operation must not contain whitespace".into(),
415 ));
416 }
417 if let Some(deadline_ms) = self.deadline_ms
418 && !(1..=MAX_DEADLINE_MS).contains(&deadline_ms)
419 {
420 return Err(ProtocolError::InvalidField(format!(
421 "deadlineMs must be 1..={MAX_DEADLINE_MS}"
422 )));
423 }
424 Ok(())
425 }
426
427 pub fn decode_task_compile(&self) -> Result<TaskCompilePayload, ProtocolError> {
429 self.validate()?;
430 if self.operation != TASK_COMPILE_OPERATION {
431 return Err(ProtocolError::InvalidField(format!(
432 "expected operation {TASK_COMPILE_OPERATION}"
433 )));
434 }
435 let payload: TaskCompilePayload =
436 serde_json::from_value(self.payload.clone()).map_err(|error| {
437 ProtocolError::InvalidField(format!("task.compile payload: {error}"))
438 })?;
439 payload.validate()?;
440 Ok(payload)
441 }
442
443 pub fn decode_task_execute(&self) -> Result<TaskExecutionPayload, ProtocolError> {
445 self.validate()?;
446 if self.operation != TASK_EXECUTE_OPERATION {
447 return Err(ProtocolError::InvalidField(format!(
448 "expected operation {TASK_EXECUTE_OPERATION}"
449 )));
450 }
451 let mut value = self.payload.clone();
452 if let Value::Object(fields) = &mut value {
453 fields.remove("responseMode");
454 }
455 let payload: TaskExecutionPayload = serde_json::from_value(value).map_err(|error| {
456 ProtocolError::InvalidField(format!("task.execute payload: {error}"))
457 })?;
458 payload.validate()?;
459 Ok(payload)
460 }
461
462 pub fn decode_task_validate(&self) -> Result<TaskValidationPayload, ProtocolError> {
464 self.validate()?;
465 if self.operation != TASK_VALIDATE_OPERATION {
466 return Err(ProtocolError::InvalidField(format!(
467 "expected operation {TASK_VALIDATE_OPERATION}"
468 )));
469 }
470 let payload: TaskValidationPayload =
471 serde_json::from_value(self.payload.clone()).map_err(|error| {
472 ProtocolError::InvalidField(format!("task.validate payload: {error}"))
473 })?;
474 payload.validate()?;
475 Ok(payload)
476 }
477
478 pub fn decode_web_ir_validate(&self) -> Result<WebIrPayload, ProtocolError> {
480 self.decode_web_ir(WEB_IR_VALIDATE_OPERATION)
481 }
482
483 pub fn decode_web_ir_inspect(&self) -> Result<WebIrPayload, ProtocolError> {
485 self.decode_web_ir(WEB_IR_INSPECT_OPERATION)
486 }
487
488 fn decode_web_ir(&self, operation: &str) -> Result<WebIrPayload, ProtocolError> {
489 self.validate()?;
490 if self.operation != operation {
491 return Err(ProtocolError::InvalidField(format!(
492 "expected operation {operation}"
493 )));
494 }
495 let payload: WebIrPayload =
496 serde_json::from_value(self.payload.clone()).map_err(|error| {
497 ProtocolError::InvalidField(format!("{operation} payload: {error}"))
498 })?;
499 payload.validate()?;
500 Ok(payload)
501 }
502
503 pub fn decode_web_ir_diff(&self) -> Result<WebIrDiffPayload, ProtocolError> {
505 self.validate()?;
506 if self.operation != WEB_IR_DIFF_OPERATION {
507 return Err(ProtocolError::InvalidField(format!(
508 "expected operation {WEB_IR_DIFF_OPERATION}"
509 )));
510 }
511 let payload: WebIrDiffPayload = serde_json::from_value(self.payload.clone())
512 .map_err(|error| ProtocolError::InvalidField(format!("webIr.diff payload: {error}")))?;
513 payload.validate()?;
514 Ok(payload)
515 }
516
517 pub fn decode_web_ir_continuity(&self) -> Result<WebIrContinuityPayload, ProtocolError> {
519 self.validate()?;
520 if self.operation != WEB_IR_CONTINUITY_OPERATION {
521 return Err(ProtocolError::InvalidField(format!(
522 "expected operation {WEB_IR_CONTINUITY_OPERATION}"
523 )));
524 }
525 let payload: WebIrContinuityPayload = serde_json::from_value(self.payload.clone())
526 .map_err(|error| {
527 ProtocolError::InvalidField(format!("webIr.continuity payload: {error}"))
528 })?;
529 payload.validate()?;
530 Ok(payload)
531 }
532
533 pub fn decode_experience_result(
535 &self,
536 ) -> Result<crate::results::ExperienceResult, ProtocolError> {
537 self.validate()?;
538 let result: crate::results::ExperienceResult = serde_json::from_value(self.payload.clone())
539 .map_err(|error| {
540 ProtocolError::InvalidField(format!("experience result payload: {error}"))
541 })?;
542 result
543 .validate()
544 .map_err(|error| ProtocolError::InvalidField(error.to_string()))?;
545 Ok(result)
546 }
547}
548
549pub fn compile_task_request(
551 request: &GlassRequest,
552) -> Result<crate::task_compiler::TaskExecutionPlan, ProtocolError> {
553 let payload = request.decode_task_compile()?;
554 crate::task_compiler::compile_task(&payload.task, &payload.ir)
555 .map_err(ProtocolError::TaskCompilation)
556}
557
558pub fn compile_task_result(request: &GlassRequest) -> Result<TaskCompileResult, ProtocolError> {
560 Ok(TaskCompileResult {
561 plan: compile_task_request(request)?,
562 })
563}
564
565pub fn validate_task_result(request: &GlassRequest) -> Result<TaskValidationResult, ProtocolError> {
567 let payload = request.decode_task_validate()?;
568 Ok(TaskValidationResult {
569 valid: true,
570 schema_version: payload.task.schema_version,
571 task: payload.task.task,
572 })
573}
574
575pub fn web_ir_validate_result(
577 request: &GlassRequest,
578) -> Result<WebIrValidationResult, ProtocolError> {
579 let payload = request.decode_web_ir_validate()?;
580 Ok(WebIrValidationResult::from_ir(&payload.ir))
581}
582
583pub fn web_ir_inspect_result(
585 request: &GlassRequest,
586) -> Result<WebIrInspectionResult, ProtocolError> {
587 let payload = request.decode_web_ir_inspect()?;
588 Ok(WebIrInspectionResult::from_ir(&payload.ir))
589}
590
591pub fn web_ir_diff_result(request: &GlassRequest) -> Result<WebIrDiffResult, ProtocolError> {
593 let payload = request.decode_web_ir_diff()?;
594 let diff = payload
595 .before
596 .diff(&payload.after)
597 .map_err(ProtocolError::WebIrValidation)?;
598 Ok(WebIrDiffResult::from_diff(&diff))
599}
600
601pub fn web_ir_continuity_result(
603 request: &GlassRequest,
604) -> Result<WebIrContinuityResult, ProtocolError> {
605 let payload = request.decode_web_ir_continuity()?;
606 let continuity = payload
607 .before
608 .classify_entity_continuity(&payload.after, &payload.entity_id)
609 .map_err(ProtocolError::WebIrValidation)?;
610 Ok(WebIrContinuityResult::from(continuity))
611}
612
613#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
615#[serde(rename_all = "camelCase")]
616pub struct GlassResponse {
617 pub protocol_version: u32,
618 pub request_id: String,
619 #[serde(skip_serializing_if = "Option::is_none")]
620 pub correlation_id: Option<String>,
621 pub ok: bool,
622 #[serde(skip_serializing_if = "Option::is_none")]
623 pub result: Option<Value>,
624 #[serde(skip_serializing_if = "Option::is_none")]
625 pub error: Option<GlassError>,
626}
627
628impl GlassResponse {
629 pub fn validate(&self) -> Result<(), ProtocolError> {
631 if self.protocol_version != GLASS_PROTOCOL_VERSION {
632 return Err(ProtocolError::UnsupportedVersion(self.protocol_version));
633 }
634 validate_identifier(&self.request_id, "requestId")?;
635 if let Some(correlation_id) = &self.correlation_id {
636 validate_identifier(correlation_id, "correlationId")?;
637 }
638 if let Some(error) = &self.error {
639 error.validate()?;
640 }
641 match (self.ok, self.result.is_some(), self.error.is_some()) {
642 (true, true, false) | (false, false, true) => Ok(()),
643 _ => Err(ProtocolError::InvalidField(
644 "ok responses require result and error responses require error".into(),
645 )),
646 }
647 }
648
649 pub fn decode_task_compile_result(&self) -> Result<TaskCompileResult, ProtocolError> {
651 self.validate()?;
652 if !self.ok {
653 return Err(ProtocolError::InvalidField(
654 "task.compile result requires a successful response".into(),
655 ));
656 }
657 let value = self
658 .result
659 .clone()
660 .ok_or_else(|| ProtocolError::InvalidField("task.compile result is missing".into()))?;
661 let result: TaskCompileResult = serde_json::from_value(value).map_err(|error| {
662 ProtocolError::InvalidField(format!("task.compile result: {error}"))
663 })?;
664 result.validate()?;
665 Ok(result)
666 }
667
668 pub fn decode_task_validation_result(&self) -> Result<TaskValidationResult, ProtocolError> {
670 self.validate()?;
671 if !self.ok {
672 return Err(ProtocolError::InvalidField(
673 "task.validate result requires a successful response".into(),
674 ));
675 }
676 let value = self
677 .result
678 .clone()
679 .ok_or_else(|| ProtocolError::InvalidField("task.validate result is missing".into()))?;
680 serde_json::from_value(value)
681 .map_err(|error| ProtocolError::InvalidField(format!("task.validate result: {error}")))
682 }
683
684 pub fn decode_web_ir_validation_result(&self) -> Result<WebIrValidationResult, ProtocolError> {
686 self.decode_web_ir_result("webIr.validate")
687 }
688
689 pub fn decode_web_ir_inspection_result(&self) -> Result<WebIrInspectionResult, ProtocolError> {
691 self.decode_web_ir_result("webIr.inspect")
692 }
693
694 fn decode_web_ir_result<T>(&self, operation: &str) -> Result<T, ProtocolError>
695 where
696 T: for<'de> Deserialize<'de>,
697 {
698 self.validate()?;
699 if !self.ok {
700 return Err(ProtocolError::InvalidField(format!(
701 "{operation} result requires a successful response"
702 )));
703 }
704 let value = self
705 .result
706 .clone()
707 .ok_or_else(|| ProtocolError::InvalidField(format!("{operation} result is missing")))?;
708 serde_json::from_value(value)
709 .map_err(|error| ProtocolError::InvalidField(format!("{operation} result: {error}")))
710 }
711
712 pub fn decode_web_ir_diff_result(&self) -> Result<WebIrDiffResult, ProtocolError> {
714 self.validate()?;
715 if !self.ok {
716 return Err(ProtocolError::InvalidField(
717 "webIr.diff result requires a successful response".into(),
718 ));
719 }
720 let value = self
721 .result
722 .clone()
723 .ok_or_else(|| ProtocolError::InvalidField("webIr.diff result is missing".into()))?;
724 serde_json::from_value(value)
725 .map_err(|error| ProtocolError::InvalidField(format!("webIr.diff result: {error}")))
726 }
727
728 pub fn decode_web_ir_continuity_result(&self) -> Result<WebIrContinuityResult, ProtocolError> {
730 self.validate()?;
731 if !self.ok {
732 return Err(ProtocolError::InvalidField(
733 "webIr.continuity result requires a successful response".into(),
734 ));
735 }
736 let value = self.result.clone().ok_or_else(|| {
737 ProtocolError::InvalidField("webIr.continuity result is missing".into())
738 })?;
739 serde_json::from_value(value).map_err(|error| {
740 ProtocolError::InvalidField(format!("webIr.continuity result: {error}"))
741 })
742 }
743}
744
745#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
747#[serde(rename_all = "camelCase")]
748pub enum ErrorPhase {
749 #[default]
750 Preflight,
751 Dispatch,
752 PostDispatch,
753 Verification,
754 Reconciliation,
755}
756
757#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
759#[serde(rename_all = "camelCase")]
760pub enum RetryClassification {
761 SafeImmediate,
762 #[default]
763 SafeAfterReobserve,
764 SafeAfterReconcile,
765 UnsafeUntilReconciled,
766 RequiresUserDecision,
767 NotRetryable,
768 Unknown,
769}
770
771#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
773#[serde(rename_all = "camelCase")]
774pub struct RetryGuidance {
775 pub classification: RetryClassification,
776 pub recommended_operation: String,
777}
778
779impl Default for RetryGuidance {
780 fn default() -> Self {
781 Self {
782 classification: RetryClassification::SafeAfterReobserve,
783 recommended_operation: "inspect_page".into(),
784 }
785 }
786}
787
788#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
790#[serde(rename_all = "camelCase")]
791pub struct GlassError {
792 pub code: String,
793 #[serde(default)]
794 pub phase: ErrorPhase,
795 pub message: String,
796 #[serde(default)]
797 pub mutation_possible: bool,
798 #[serde(default)]
799 pub retry: RetryGuidance,
800 #[serde(default, skip_serializing_if = "Option::is_none")]
802 pub retryable: Option<bool>,
803 #[serde(skip_serializing_if = "Option::is_none")]
804 pub details: Option<Value>,
805}
806
807impl GlassError {
808 pub fn validate(&self) -> Result<(), ProtocolError> {
810 if self.code.is_empty() || self.code.len() > MAX_ERROR_CODE_BYTES {
811 return Err(ProtocolError::InvalidField(
812 "error code must be a bounded non-empty string".into(),
813 ));
814 }
815 if self.message.is_empty() || self.message.len() > MAX_MESSAGE_BYTES {
816 return Err(ProtocolError::InvalidField(
817 "error message must be a bounded non-empty string".into(),
818 ));
819 }
820 validate_identifier(
821 &self.retry.recommended_operation,
822 "retry.recommendedOperation",
823 )?;
824 if let Some(details) = &self.details {
825 let detail_bytes = serde_json::to_vec(details).map_err(|error| {
826 ProtocolError::InvalidField(format!("error details are not serializable: {error}"))
827 })?;
828 if detail_bytes.len() > MAX_ERROR_DETAILS_BYTES {
829 return Err(ProtocolError::InvalidField(format!(
830 "error details must be at most {MAX_ERROR_DETAILS_BYTES} bytes"
831 )));
832 }
833 }
834 Ok(())
835 }
836}
837
838#[derive(Debug, Clone, PartialEq, Eq)]
840pub enum ProtocolError {
841 UnsupportedVersion(u32),
842 InvalidField(String),
843 TaskValidation(crate::task_protocol::TaskProtocolError),
844 TaskCompilation(crate::task_compiler::TaskCompilationError),
845 WebIrValidation(crate::web_ir::WebIrValidationError),
846}
847
848impl std::fmt::Display for ProtocolError {
849 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
850 match self {
851 Self::UnsupportedVersion(version) => {
852 write!(formatter, "unsupported Glass protocol version {version}")
853 }
854 Self::InvalidField(detail) => formatter.write_str(detail),
855 Self::TaskValidation(error) => error.fmt(formatter),
856 Self::TaskCompilation(error) => error.fmt(formatter),
857 Self::WebIrValidation(error) => error.fmt(formatter),
858 }
859 }
860}
861
862impl std::error::Error for ProtocolError {}
863
864fn validate_identifier(value: &str, field: &str) -> Result<(), ProtocolError> {
865 if value.is_empty() || value.len() > MAX_ID_BYTES || value.chars().any(char::is_whitespace) {
866 return Err(ProtocolError::InvalidField(format!(
867 "{field} must be a bounded non-whitespace identifier"
868 )));
869 }
870 Ok(())
871}
872
873#[cfg(test)]
874mod tests {
875 use super::*;
876
877 fn request() -> GlassRequest {
878 GlassRequest {
879 protocol_version: GLASS_PROTOCOL_VERSION,
880 request_id: "request-1".into(),
881 correlation_id: Some("run-1".into()),
882 session_id: Some("session-1".into()),
883 mutation_lease: Some(MutationLeaseRef {
884 session_id: "session-1".into(),
885 token: "lease-1".into(),
886 }),
887 operation: "browser.observe".into(),
888 payload: serde_json::json!({"level": "interactive"}),
889 deadline_ms: Some(5_000),
890 }
891 }
892
893 fn web_ir_fixture(revision: u64, name: &str) -> crate::web_ir::GlassWebIrV1 {
894 serde_json::from_value(serde_json::json!({
895 "schemaVersion": 1,
896 "revision": revision,
897 "document": {"revision": revision},
898 "entities": [
899 {
900 "id": "page",
901 "kind": "page",
902 "quality": "confirmed",
903 "evidenceSources": []
904 },
905 {
906 "id": "field-1",
907 "kind": "field",
908 "role": "textbox",
909 "name": name,
910 "quality": "strong",
911 "evidenceSources": ["dom"]
912 }
913 ],
914 "relationships": [
915 {"from": "page", "to": "field-1", "kind": "contains"}
916 ],
917 "coverage": {
918 "structural": "strong",
919 "semantic": "strong",
920 "interactiveEntitiesObserved": 1,
921 "opaqueRegions": 0,
922 "reasons": []
923 },
924 "limits": {
925 "truncated": false,
926 "omittedFacts": 0,
927 "textBytes": 0,
928 "missingSources": []
929 }
930 }))
931 .unwrap()
932 }
933
934 #[test]
935 fn request_round_trips_and_validates() {
936 let request = request();
937 request.validate().unwrap();
938 let value = serde_json::to_value(&request).unwrap();
939 assert_eq!(value["protocolVersion"], 1);
940 assert_eq!(value["mutationLease"]["sessionId"], "session-1");
941 let decoded: GlassRequest = serde_json::from_value(value).unwrap();
942 assert_eq!(decoded, request);
943 }
944
945 #[test]
946 fn response_requires_exactly_one_outcome() {
947 let response = GlassResponse {
948 protocol_version: GLASS_PROTOCOL_VERSION,
949 request_id: "request-1".into(),
950 correlation_id: None,
951 ok: false,
952 result: None,
953 error: Some(GlassError {
954 code: "target.stale".into(),
955 phase: ErrorPhase::Preflight,
956 message: "a mutation lease is required".into(),
957 mutation_possible: false,
958 retry: RetryGuidance {
959 classification: RetryClassification::SafeAfterReobserve,
960 recommended_operation: "inspect_page".into(),
961 },
962 retryable: Some(true),
963 details: None,
964 }),
965 };
966 response.validate().unwrap();
967 let mut invalid = response.clone();
968 invalid.ok = true;
969 assert!(invalid.validate().is_err());
970 }
971
972 #[test]
973 fn response_validation_rejects_unbounded_error_diagnostics() {
974 let response = GlassResponse {
975 protocol_version: GLASS_PROTOCOL_VERSION,
976 request_id: "request-1".into(),
977 correlation_id: None,
978 ok: false,
979 result: None,
980 error: Some(GlassError {
981 code: "invalid".into(),
982 phase: ErrorPhase::Preflight,
983 message: "request rejected".into(),
984 mutation_possible: false,
985 retry: RetryGuidance::default(),
986 retryable: None,
987 details: Some(serde_json::json!({
988 "diagnostic": "x".repeat(MAX_ERROR_DETAILS_BYTES)
989 })),
990 }),
991 };
992 let error = response.validate().unwrap_err();
993 assert!(error.to_string().contains("error details must be at most"));
994 }
995
996 #[test]
997 fn web_ir_revision_operations_round_trip_with_bounded_results() {
998 let before = web_ir_fixture(7, "Email");
999 let after = web_ir_fixture(8, "Email address");
1000 let diff_request = GlassRequest {
1001 protocol_version: GLASS_PROTOCOL_VERSION,
1002 request_id: "diff-1".into(),
1003 correlation_id: None,
1004 session_id: None,
1005 mutation_lease: None,
1006 operation: WEB_IR_DIFF_OPERATION.into(),
1007 payload: serde_json::to_value(WebIrDiffPayload {
1008 before: before.clone(),
1009 after: after.clone(),
1010 })
1011 .unwrap(),
1012 deadline_ms: None,
1013 };
1014 let diff = web_ir_diff_result(&diff_request).unwrap();
1015 assert_eq!(diff.from_revision, 7);
1016 assert_eq!(diff.to_revision, 8);
1017 assert_eq!(diff.entity_changed_count, 1);
1018 assert_eq!(diff_request.decode_web_ir_diff().unwrap().before, before);
1019
1020 let continuity_request = GlassRequest {
1021 protocol_version: GLASS_PROTOCOL_VERSION,
1022 request_id: "continuity-1".into(),
1023 correlation_id: None,
1024 session_id: None,
1025 mutation_lease: None,
1026 operation: WEB_IR_CONTINUITY_OPERATION.into(),
1027 payload: serde_json::to_value(WebIrContinuityPayload {
1028 before,
1029 after,
1030 entity_id: "field-1".into(),
1031 })
1032 .unwrap(),
1033 deadline_ms: None,
1034 };
1035 let continuity = web_ir_continuity_result(&continuity_request).unwrap();
1036 assert_eq!(
1037 continuity.status,
1038 crate::web_ir::WebIrEntityContinuityStatus::Changed
1039 );
1040 let response = GlassResponse {
1041 protocol_version: GLASS_PROTOCOL_VERSION,
1042 request_id: continuity_request.request_id.clone(),
1043 correlation_id: None,
1044 ok: true,
1045 result: Some(serde_json::to_value(&continuity).unwrap()),
1046 error: None,
1047 };
1048 assert_eq!(
1049 response.decode_web_ir_continuity_result().unwrap(),
1050 continuity
1051 );
1052 }
1053
1054 #[test]
1055 fn web_ir_inspect_and_validate_operations_round_trip() {
1056 let draft = web_ir_fixture(7, "Email");
1057 let validate_request = GlassRequest {
1058 protocol_version: GLASS_PROTOCOL_VERSION,
1059 request_id: "validate-1".into(),
1060 correlation_id: None,
1061 session_id: None,
1062 mutation_lease: None,
1063 operation: WEB_IR_VALIDATE_OPERATION.into(),
1064 payload: serde_json::json!({"ir": draft.clone()}),
1065 deadline_ms: None,
1066 };
1067 let validation = web_ir_validate_result(&validate_request).unwrap();
1068 assert!(validation.valid);
1069 assert_eq!(validate_request.decode_web_ir_validate().unwrap().ir, draft);
1070 let validation_response = GlassResponse {
1071 protocol_version: GLASS_PROTOCOL_VERSION,
1072 request_id: "validate-1".into(),
1073 correlation_id: None,
1074 ok: true,
1075 result: Some(serde_json::to_value(&validation).unwrap()),
1076 error: None,
1077 };
1078 assert_eq!(
1079 validation_response
1080 .decode_web_ir_validation_result()
1081 .unwrap(),
1082 validation
1083 );
1084
1085 let inspect_request = GlassRequest {
1086 operation: WEB_IR_INSPECT_OPERATION.into(),
1087 request_id: "inspect-1".into(),
1088 payload: serde_json::json!({"ir": draft}),
1089 ..validate_request
1090 };
1091 let inspection = web_ir_inspect_result(&inspect_request).unwrap();
1092 let inspection_response = GlassResponse {
1093 protocol_version: GLASS_PROTOCOL_VERSION,
1094 request_id: "inspect-1".into(),
1095 correlation_id: None,
1096 ok: true,
1097 result: Some(serde_json::to_value(&inspection).unwrap()),
1098 error: None,
1099 };
1100 assert_eq!(
1101 inspection_response
1102 .decode_web_ir_inspection_result()
1103 .unwrap(),
1104 inspection
1105 );
1106 }
1107
1108 #[test]
1109 fn bounds_and_unknown_fields_fail_closed() {
1110 let mut request = request();
1111 request.operation = "bad operation".into();
1112 assert!(request.validate().is_err());
1113 let unknown = serde_json::json!({
1114 "protocolVersion": 1,
1115 "requestId": "request-1",
1116 "operation": "browser.observe",
1117 "payload": {},
1118 "future": true
1119 });
1120 assert!(serde_json::from_value::<GlassRequest>(unknown).is_err());
1121 }
1122
1123 #[test]
1124 fn task_validate_boundary_decodes_without_compiling() {
1125 let task = serde_json::json!({
1126 "schemaVersion": 1,
1127 "task": "region.extract",
1128 "scope": {"regionName": "Checkout"},
1129 "limits": {"maxActions": 4, "timeoutMs": 2000, "maxItems": 16},
1130 "risk": "readOnly"
1131 });
1132 let request = GlassRequest {
1133 protocol_version: GLASS_PROTOCOL_VERSION,
1134 request_id: "validate-task-1".into(),
1135 correlation_id: None,
1136 session_id: None,
1137 mutation_lease: None,
1138 operation: TASK_VALIDATE_OPERATION.into(),
1139 payload: serde_json::json!({"task": task}),
1140 deadline_ms: None,
1141 };
1142 let result = validate_task_result(&request).unwrap();
1143 assert_eq!(
1144 result,
1145 TaskValidationResult {
1146 valid: true,
1147 schema_version: 1,
1148 task: crate::task_protocol::TaskKind::RegionExtract,
1149 }
1150 );
1151 let response = GlassResponse {
1152 protocol_version: GLASS_PROTOCOL_VERSION,
1153 request_id: request.request_id.clone(),
1154 correlation_id: None,
1155 ok: true,
1156 result: Some(serde_json::to_value(&result).unwrap()),
1157 error: None,
1158 };
1159 assert_eq!(response.decode_task_validation_result().unwrap(), result);
1160 assert_eq!(
1161 request.decode_task_validate().unwrap().task.task,
1162 crate::task_protocol::TaskKind::RegionExtract
1163 );
1164 }
1165
1166 #[test]
1167 fn task_execute_boundary_decodes_revision_and_confirmation() {
1168 let request = GlassRequest {
1169 protocol_version: GLASS_PROTOCOL_VERSION,
1170 request_id: "execute-task-1".into(),
1171 correlation_id: None,
1172 session_id: Some("session-1".into()),
1173 mutation_lease: Some(MutationLeaseRef {
1174 session_id: "session-1".into(),
1175 token: "lease-1".into(),
1176 }),
1177 operation: TASK_EXECUTE_OPERATION.into(),
1178 payload: serde_json::json!({
1179 "task": {
1180 "schemaVersion": 1,
1181 "task": "form.submit",
1182 "scope": {"regionName": "Checkout"},
1183 "inputs": {"submit": "Submit"},
1184 "limits": {"maxActions": 4, "timeoutMs": 2000, "maxItems": 16},
1185 "risk": "remoteIrreversible",
1186 "postconditions": [{"kind": "navigationOccurred"}],
1187 },
1188 "expectedRevision": 9,
1189 "confirmed": true
1190 }),
1191 deadline_ms: None,
1192 };
1193 let payload = request.decode_task_execute().unwrap();
1194 assert_eq!(
1195 payload.task.task,
1196 crate::task_protocol::TaskKind::FormSubmit
1197 );
1198 assert_eq!(payload.expected_revision, 9);
1199 assert!(payload.confirmed);
1200 }
1201
1202 #[test]
1203 fn task_compile_boundary_decodes_and_compiles_without_browser_state() {
1204 let task = serde_json::json!({
1205 "schemaVersion": 1,
1206 "task": "region.extract",
1207 "scope": {"regionName": "Checkout", "entityKind": "region"},
1208 "limits": {"maxActions": 8, "timeoutMs": 5000, "maxItems": 32},
1209 "risk": "readOnly"
1210 });
1211 let request = GlassRequest {
1212 protocol_version: GLASS_PROTOCOL_VERSION,
1213 request_id: "compile-1".into(),
1214 correlation_id: None,
1215 session_id: None,
1216 mutation_lease: None,
1217 operation: TASK_COMPILE_OPERATION.into(),
1218 payload: serde_json::json!({
1219 "task": task,
1220 "ir": crate::task_compiler::test_compiler_ir()
1221 }),
1222 deadline_ms: None,
1223 };
1224 let plan = compile_task_request(&request).unwrap();
1225 assert_eq!(plan.task, crate::task_protocol::TaskKind::RegionExtract);
1226 assert_eq!(plan.scope.region_name.as_deref(), Some("Checkout"));
1227 assert_eq!(plan.limits.max_actions, 8);
1228 assert_eq!(
1229 plan.revision,
1230 crate::task_protocol::TaskRevisionPolicy::Exact
1231 );
1232
1233 let mut wrong_operation = request.clone();
1234 wrong_operation.operation = "browser.observe".into();
1235 assert!(wrong_operation.decode_task_compile().is_err());
1236
1237 let mut unknown = request.clone();
1238 unknown.payload["futureField"] = true.into();
1239 assert!(unknown.decode_task_compile().is_err());
1240
1241 let mut invalid = request;
1242 invalid.payload["task"]["task"] = "form.fill".into();
1243 assert!(compile_task_request(&invalid).is_err());
1244 }
1245
1246 #[test]
1247 fn task_compile_result_round_trips_through_success_response() {
1248 let request = GlassRequest {
1249 protocol_version: GLASS_PROTOCOL_VERSION,
1250 request_id: "compile-2".into(),
1251 correlation_id: None,
1252 session_id: None,
1253 mutation_lease: None,
1254 operation: TASK_COMPILE_OPERATION.into(),
1255 payload: serde_json::json!({
1256 "task": {
1257 "schemaVersion": 1,
1258 "task": "field.read",
1259 "scope": {"regionName": "Checkout", "entityKind": "field", "entityName": "Email"},
1260 "inputs": {"field": "Email"},
1261 "limits": {"maxActions": 4, "timeoutMs": 2000, "maxItems": 1},
1262 "risk": "readOnly"
1263 },
1264 "ir": crate::task_compiler::test_compiler_ir()
1265 }),
1266 deadline_ms: None,
1267 };
1268 let result = compile_task_result(&request).unwrap();
1269 let response = GlassResponse {
1270 protocol_version: GLASS_PROTOCOL_VERSION,
1271 request_id: request.request_id.clone(),
1272 correlation_id: None,
1273 ok: true,
1274 result: Some(serde_json::to_value(&result).unwrap()),
1275 error: None,
1276 };
1277 assert_eq!(response.decode_task_compile_result().unwrap(), result);
1278
1279 let mut unknown = response.clone();
1280 unknown.result.as_mut().unwrap()["futureField"] = true.into();
1281 assert!(unknown.decode_task_compile_result().is_err());
1282
1283 let mut failure = response;
1284 failure.ok = false;
1285 failure.result = None;
1286 failure.error = Some(GlassError {
1287 code: "task.invalid".into(),
1288 phase: ErrorPhase::Preflight,
1289 message: "invalid task".into(),
1290 mutation_possible: false,
1291 retry: RetryGuidance::default(),
1292 retryable: None,
1293 details: None,
1294 });
1295 assert!(failure.decode_task_compile_result().is_err());
1296 }
1297
1298 #[test]
1299 fn additive_response_fields_are_tolerated() {
1300 let response: GlassResponse = serde_json::from_value(serde_json::json!({
1301 "protocolVersion": 1,
1302 "requestId": "request-1",
1303 "ok": false,
1304 "error": {
1305 "code": "target.stale",
1306 "message": "stale",
1307 "retryable": true,
1308 "future": "ignored"
1309 },
1310 "future": true
1311 }))
1312 .unwrap();
1313 assert_eq!(
1314 response.error.unwrap().retry.classification,
1315 RetryClassification::SafeAfterReobserve
1316 );
1317 }
1318}