adk_computer_use/contracts/
session.rs

1//! Session lifecycle, event, follow-up, and deletion contracts.
2
3use serde::{Deserialize, Serialize};
4use serde_json::Value;
5use std::collections::BTreeMap;
6
7/// Stable supervisor event used for ADK/runtime trace correlation.
8#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
9#[serde(rename_all = "camelCase")]
10pub struct SessionEvent {
11    /// Schema version of the event envelope.
12    pub schema_version: u32,
13    /// Unique event identifier.
14    pub event_id: String,
15    /// Monotonic sequence within the session.
16    pub sequence: u64,
17    /// The session the event belongs to.
18    pub session_id: String,
19    /// The action the event relates to, when applicable.
20    #[serde(skip_serializing_if = "Option::is_none")]
21    pub action_id: Option<String>,
22    /// The event type (e.g. `action.started`, `action.committed`).
23    #[serde(rename = "type")]
24    pub event_type: String,
25    /// RFC 3339 timestamp of the event.
26    pub at: String,
27    /// The principal associated with the event, when applicable.
28    #[serde(skip_serializing_if = "Option::is_none")]
29    pub principal_id: Option<String>,
30    /// Event-specific payload.
31    pub payload: Value,
32}
33
34/// Principal-owned, monotonic steering instruction consumed by an ADK graph.
35#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
36#[serde(rename_all = "camelCase")]
37pub struct SessionFollowUp {
38    /// Unique follow-up identifier.
39    pub follow_up_id: String,
40    /// Monotonic sequence within the session.
41    pub sequence: u64,
42    /// The session the follow-up belongs to.
43    pub session_id: String,
44    /// The principal that owns the follow-up.
45    pub principal_id: String,
46    /// The steering instruction text.
47    pub instruction: String,
48    /// RFC 3339 creation timestamp.
49    pub created_at: String,
50}
51
52/// A page of follow-ups plus the cursor for the next page.
53#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
54pub struct SessionFollowUpPage {
55    /// The follow-ups in this page.
56    #[serde(rename = "follow_ups")]
57    pub follow_ups: Vec<SessionFollowUp>,
58    /// The sequence to resume from on the next request.
59    #[serde(rename = "next_sequence")]
60    pub next_sequence: u64,
61}
62
63/// A runtime session and its current lifecycle state.
64#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
65#[serde(rename_all = "camelCase")]
66pub struct RuntimeSession {
67    /// Unique session identifier.
68    pub session_id: String,
69    /// The principal that owns the session.
70    pub principal_id: String,
71    /// Optional execution group for multi-agent coordination.
72    #[serde(skip_serializing_if = "Option::is_none")]
73    pub execution_group_id: Option<String>,
74    /// The session objective, when set.
75    #[serde(skip_serializing_if = "Option::is_none")]
76    pub objective: Option<String>,
77    /// Session state (e.g. `active`, `completed`).
78    pub state: String,
79    /// Monotonic session revision.
80    pub revision: u64,
81    /// RFC 3339 creation timestamp.
82    pub created_at: String,
83    /// RFC 3339 update timestamp.
84    pub updated_at: String,
85    /// Reason the session is waiting, when applicable.
86    #[serde(skip_serializing_if = "Option::is_none")]
87    pub waiting_reason: Option<String>,
88    /// Whether the session was recovered after a crash.
89    #[serde(skip_serializing_if = "Option::is_none")]
90    pub recovered: Option<bool>,
91    /// Completion evidence, when the session is complete.
92    #[serde(skip_serializing_if = "Option::is_none")]
93    pub completion: Option<SessionCompletionEvidence>,
94}
95
96/// Evidence describing how a session reached completion.
97#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
98#[serde(rename_all = "camelCase")]
99pub struct SessionCompletionEvidence {
100    /// Human-readable completion summary.
101    pub summary: String,
102    /// Postcondition evidence collected at completion.
103    pub postconditions: Vec<PostconditionEvidence>,
104    /// The last app identifier observed, when known.
105    #[serde(skip_serializing_if = "Option::is_none")]
106    pub last_app_id: Option<String>,
107    /// The last window identifier observed, when known.
108    #[serde(skip_serializing_if = "Option::is_none")]
109    pub last_window_id: Option<Value>,
110    /// Per-tool action counts.
111    pub action_counts: BTreeMap<String, u64>,
112    /// Reason for completion, when applicable.
113    #[serde(skip_serializing_if = "Option::is_none")]
114    pub reason: Option<String>,
115    /// RFC 3339 completion timestamp.
116    pub completed_at: String,
117}
118
119/// A single postcondition and whether it was satisfied.
120#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
121#[serde(rename_all = "camelCase")]
122pub struct PostconditionEvidence {
123    /// Human-readable description of the postcondition.
124    pub description: String,
125    /// Whether the postcondition was satisfied.
126    pub satisfied: bool,
127    /// Digest of the evidence backing the check, when present.
128    #[serde(skip_serializing_if = "Option::is_none")]
129    pub evidence_hash: Option<String>,
130}
131
132/// Principal-bound result of deleting one terminal runtime session's durable data.
133#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
134#[serde(rename_all = "camelCase")]
135pub struct SessionDeletionResult {
136    /// The session that was targeted.
137    pub session_id: String,
138    /// Whether the session was deleted.
139    pub deleted: bool,
140    /// Number of events deleted.
141    pub deleted_events: u64,
142    /// Number of receipts deleted.
143    pub deleted_receipts: u64,
144    /// Number of evidence frames deleted.
145    pub deleted_evidence_frames: u64,
146    /// Number of approval grants revoked.
147    pub revoked_grants: u64,
148    /// Number of events retained for compliance.
149    pub retained_events: u64,
150    /// Retention marker identifier, when events were retained.
151    #[serde(skip_serializing_if = "Option::is_none")]
152    pub retention_marker_id: Option<String>,
153}
adk_computer_use/contracts/session.rs

adk_computer_use/contracts/
session.rs
