session.proto RawHistoryFolder
1// Session lifecycle and control messages (protocol.Hello and friends).
2syntax = "proto3";
3
4package vev.wire.v1;
5
6import "common.proto";
7
8option go_package = "github.com/bnema/vev/internal/protocol/wire";
9
10// Hello opens a session attachment. version must stay field 1.
11message Hello {
12 uint32 version = 1;
13 // Closed intent taxonomy: 0 = ephemeral, 1 = new, 2 = attach, 3 = resume.
14 uint32 intent = 2;
15 bytes client_id = 3; // exactly 16 bytes
16 uint64 resume_token = 4;
17 string name = 5;
18 uint32 cols = 6;
19 uint32 rows = 7;
20 uint32 pixel_width = 8;
21 uint32 pixel_height = 9;
22 string term_env = 10;
23 string cwd = 11;
24 reserved 12;
25 reserved "true_color";
26 uint32 max_output_in_flight = 13;
27 repeated string env = 14;
28 reserved 15;
29 reserved "remote_target";
30 uint32 environment_policy = 16; // 0 = client-owned, 1 = daemon-owned
31 ExactTarget exact_target = 17; // optional pointer
32 string preferred_tab_id = 18;
33 uint32 navigation_capabilities = 19;
34 bool remote = 20;
35 bool kitty_direct_graphics = 21;
36 SessionAttachTarget session_target = 22; // optional pointer
37 bool kitty_keyboard = 23;
38 // Terminal window focus when the attachment opens: 0 = unknown,
39 // 1 = focused, 2 = unfocused. Later changes travel as TerminalFocus.
40 uint32 terminal_focus = 24;
41 // PID of a local client process, for bar scripts. 0 when unknown or remote.
42 uint32 client_pid = 25;
43 // Color output capability the client claims. Required: a missing message
44 // or an UNSPECIFIED mode is a decode error.
45 ColorCapabilities color = 26;
46}
47
48// Welcome answers an accepted attach.
49message Welcome {
50 string session_id = 1;
51 string session_name = 2;
52 bool ephemeral = 3;
53 uint64 resume_token = 4;
54 uint32 capabilities = 5;
55 CommittedRouteIdentity committed_identity = 6; // optional pointer
56}
57
58// ErrorMsg is a bounded daemon error.
59message ErrorMsg {
60 uint32 code = 1;
61 string text = 2;
62}
63
64// CommittedRouteIdentity is the identity committed after an accepted attach.
65message CommittedRouteIdentity {
66 ExactTarget target = 1;
67 bool ephemeral = 2;
68}
69
70// AttachTarget hands a client to another session, possibly remote.
71message AttachTarget {
72 uint64 request_id = 1;
73 string endpoint = 2;
74 string session = 3;
75 uint32 intent = 4;
76 reserved 5;
77 reserved "remote_target";
78 uint32 environment_policy = 6;
79 ExactTarget exact_target = 7; // optional pointer
80 bool same_peer = 8;
81 string preferred_tab_id = 9;
82 uint64 cause_action_id = 10;
83 SessionAttachTarget session_target = 11; // optional pointer
84}
85
86// SessionInfo is one row of a session listing.
87message SessionInfo {
88 string session_id = 1;
89 string name = 2;
90 // Closed state taxonomy: 0 = up, 1 = down, 2 = broken.
91 uint32 state = 3;
92 bool ephemeral = 4;
93 uint32 tabs = 5;
94 bool attached = 6;
95}
96
97// Sessions is the one-shot listing answer.
98message Sessions {
99 repeated SessionInfo sessions = 1;
100}
101
102// Kill asks the daemon to destroy a session or shut down.
103message Kill {
104 string name = 1;
105 // Closed scope taxonomy: 0 = session, 1 = daemon, 2 = all.
106 uint32 scope = 2;
107 uint64 request_id = 3;
108}
109
110message KillFailure {
111 string class = 1;
112 string name = 2;
113 string text = 3;
114}
115
116message KillResult {
117 uint64 request_id = 1;
118 // Closed outcome taxonomy: 1 = succeeded, 2 = failed, 3 = outcome unknown.
119 uint32 outcome = 2;
120 uint32 code = 3;
121 string text = 4;
122 repeated KillFailure failures = 5;
123}
124
125// Detached reports why an attachment ended.
126message Detached {
127 // Closed reason taxonomy: 0 = detach, 1 = killed, 2 = shutdown, 3 = replaced.
128 uint32 reason = 1;
129}
130
131// Detach asks the daemon to release the attachment. closed reports that the
132// client process is ending (terminal closed or terminated), not a user detach.
133message Detach {
134 bool closed = 1;
135}
136
137// Ping / Pong are empty keepalive markers.
138message Ping {}
139
140message Pong {}
141
142// List asks for the one-shot session listing. Empty marker.
143message List {}
144
145// RouteRef is an opaque client-ledger reference.
146message RouteRef {
147 uint64 key = 1;
148 uint64 generation = 2;
149}
150
151// RouteAttentionTarget binds one displayed reference to an exact lifecycle.
152message RouteAttentionTarget {
153 RouteRef ref = 1;
154 ExactTarget target = 2;
155 string source_key = 3;
156}
157
158// RouteAttentionSubscription is the bounded client-owned attention mapping.
159message RouteAttentionSubscription {
160 repeated RouteAttentionTarget targets = 1;
161}
162
163// RecentRouteEntry is one route's identity plus display view.
164message RecentRouteEntry {
165 uint64 key = 1;
166 uint64 generation = 2;
167 ExactTarget target = 3;
168 string name = 4;
169 string host_label = 5;
170 // Closed kind taxonomy: 1 = local, 2 = remote.
171 uint32 kind = 6;
172 bool ephemeral = 7;
173 bool attention = 8;
174 // Closed reachability taxonomy: 0 = unknown, 1 = reachable, 2 = unavailable.
175 uint32 reachability = 9;
176 // Client-assigned attention onset order; zero without attention.
177 uint64 attention_seq = 10;
178 // True once this client attached to the route; the status-bar history
179 // shows visited routes plus ringing ones.
180 bool visited = 11;
181}
182
183// RouteHost is one creation destination other than the serving daemon.
184message RouteHost {
185 uint64 key = 1;
186 uint64 generation = 2;
187 string label = 3;
188 // Closed kind taxonomy: 1 = local, 2 = remote.
189 uint32 kind = 4;
190}
191
192// RecentRouteSnapshot is an immutable bounded route publication.
193message RecentRouteSnapshot {
194 uint64 generation = 1;
195 RouteRef active = 2;
196 RecentRouteEntry active_entry = 3;
197 RouteRef previous = 4;
198 RouteRef home = 5;
199 repeated RecentRouteEntry entries = 6;
200 repeated RouteHost hosts = 7;
201}
202
203// RouteNavigationAction asks the client to resolve one ledger entry.
204message RouteNavigationAction {
205 uint64 cause_action_id = 1;
206 uint64 snapshot_generation = 2;
207 uint64 key = 3;
208 uint64 generation = 4;
209}
210
211// RouteCreateSessionAction asks the client to create a named session.
212message RouteCreateSessionAction {
213 uint64 cause_action_id = 1;
214 uint64 request_id = 2;
215 uint64 snapshot_generation = 3;
216 uint64 key = 4;
217 uint64 generation = 5;
218 string session_name = 6;
219}
220
221// RouteNavigationFailure is the bounded rejection taxonomy shared by both
222// directions: the same semantic payload appears in both envelopes.
223message RouteNavigationFailure {
224 uint64 key = 1;
225 uint64 generation = 2;
226 // Closed code taxonomy: 1 = stale, 2 = no such route, 3 = unavailable,
227 // 4 = target changed, 5 = origin unavailable.
228 uint32 code = 3;
229}
230
231// SessionCreationFailure reports a correlated pre-commit create failure.
232message SessionCreationFailure {
233 uint64 request_id = 1;
234 uint32 code = 2; // same taxonomy as RouteNavigationFailure.code
235}
236
237// RoutePosition is mutable per-client route state.
238message RoutePosition {
239 ExactTarget target = 1;
240 string active_tab_id = 2;
241}
242
243// RouteRetired invalidates one subscribed exact lifecycle.
244message RouteRetired {
245 RouteRef ref = 1;
246 ExactTarget target = 2;
247}
248
249// SamePeerSwitchRequest confirms a daemon-offered endpoint-empty target.
250message SamePeerSwitchRequest {
251 uint64 request_id = 1;
252 ExactTarget target = 2;
253 string preferred_tab_id = 3;
254}
255
256// SamePeerSwitchFailure leaves the source attachment unchanged.
257message SamePeerSwitchFailure {
258 uint64 request_id = 1;
259 // Closed code taxonomy: 1 = stale target, 2 = unavailable.
260 uint32 code = 2;
261}
262
263// SuspendAttachment requests an acknowledged passive publication barrier.
264message SuspendAttachment {
265 uint64 request_id = 1;
266}
267
268// AttachmentSuspended is sent only after authority revocation and output drain.
269message AttachmentSuspended {
270 uint64 request_id = 1;
271 ExactTarget target = 2;
272}
273
274// ActivateAttachment targets only the suspended attachment's retained lifecycle.
275message ActivateAttachment {
276 uint64 request_id = 1;
277 ExactTarget target = 2;
278 uint32 cols = 3;
279 uint32 rows = 4;
280 uint32 pixel_width = 5;
281 uint32 pixel_height = 6;
282}
283
284// AttachmentActivated follows a full Output and changed RoutePosition on a
285// fresh epoch. The identity and epoch/state/publication fence must match that
286// Output before input resumes.
287message AttachmentActivated {
288 uint64 request_id = 1;
289 CommittedRouteIdentity identity = 2;
290 uint64 epoch = 3;
291 uint64 state = 4;
292 uint64 view_publication = 5;
293}