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