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
//! Versioned, process-local extension ABI. Only C layouts, borrowed spans and opaque handles
//! cross this boundary. Extensions must not link another copy of the renderer or host runtime.
use std::ffi::c_void;
pub const ABI_VERSION: u32 = 1;
pub const TERMINAL_EXTENSION: u32 = 1;
/// Generic request/reply/event extension. Names and release versions belong to
/// the extension author; no per-extension kind or core registration is needed.
pub const SERVICE_EXTENSION: u32 = 2;
/// Compatibility alias for extensions built before services became extensible.
pub const UPDATER_EXTENSION: u32 = SERVICE_EXTENSION;
pub const MAX_EXTENSION_NAME: usize = 64;
pub const MAX_EXTENSIONS: usize = 32;
pub const MAX_FRAME_TEXT: usize = 16 * 1024 * 1024;
pub const MAX_FRAME_HIGHLIGHTS: usize = 4096;
pub const MAX_FRAME_CELLS: usize = 512 * 256;
#[repr(C)]
#[derive(Clone, Copy)]
pub struct Bytes {
pub data: *const u8,
pub len: usize,
}
impl Bytes {
pub const fn new(value: &[u8]) -> Self {
Self {
data: value.as_ptr(),
len: value.len(),
}
}
}
/// The descriptor and its function table remain valid until process exit. A consumer checks
/// the header before reading the table. The release version matches the importing
/// Go package's requirement, independently of the core version for generic services.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct Extension {
pub abi_version: u32,
pub descriptor_size: u32,
pub kind: u32,
pub api_size: u32,
pub name: Bytes,
pub version: Bytes,
pub api: *const c_void,
}
// SAFETY: Published descriptors only refer to immutable static bytes and function tables.
unsafe impl Sync for Extension {}
/// Ownership of the callback context transfers to `create`, including its error path. The
/// extension calls release exactly once after its final worker can no longer call wake.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct Wake {
pub context: *mut c_void,
pub wake: unsafe extern "C" fn(*mut c_void),
pub release: unsafe extern "C" fn(*mut c_void),
}
#[repr(C)]
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct Rgba {
pub r: f32,
pub g: f32,
pub b: f32,
pub a: f32,
}
#[repr(C)]
#[derive(Clone, Copy, Default)]
pub struct Highlight {
pub start: u32,
pub end: u32,
// 1 foreground, 2 background, 4 bold, 8 italic, 16 underline,
// 32 double underline, 64 wavy underline, 128 strikethrough.
pub flags: u32,
pub foreground: Rgba,
pub background: Rgba,
}
#[repr(C)]
#[derive(Clone, Copy)]
pub struct Graphic {
pub column: u16,
pub row: u16,
pub character: u32,
pub has_foreground: u32,
pub foreground: Rgba,
}
/// One immutable visible frame. Every span is borrowed only during the frame callback. The
/// receiver copies it once per revision; unchanged reads return without allocating or copying.
#[repr(C)]
pub struct TerminalFrame {
pub revision: u64,
pub cols: u16,
pub rows: u16,
pub foreground: Rgba,
pub background: Rgba,
pub content: Bytes,
pub title: Bytes,
pub working_directory: Bytes,
pub selected_text: Bytes,
pub has_selection: u32,
pub highlights: *const Highlight,
pub highlights_len: usize,
pub graphics: *const Graphic,
pub graphics_len: usize,
// top, right, bottom, left concatenated; a negative alpha represents an absent color.
pub edges: *const Rgba,
pub edges_len: usize,
pub total_rows: u64,
pub offset_rows: u64,
pub viewport_rows: u64,
pub has_cursor: u32,
pub cursor_column: u16,
pub cursor_row: u16,
pub cursor_style: u32,
pub cursor_blinking: u32,
pub cursor_color: Rgba,
pub cursor_start: u32,
pub cursor_end: u32,
pub has_cursor_range: u32,
// 0 starting, 1 running, 2 exited, 3 failed.
pub status: u32,
pub process_id: u32,
pub exit_code: u32,
pub signal: Bytes,
pub error: Bytes,
pub agent: Bytes,
pub agent_status: u32,
pub agent_process_id: u32,
}
pub type FrameCallback = unsafe extern "C" fn(*mut c_void, *const TerminalFrame);
pub type Reply = unsafe extern "C" fn(*mut c_void, Bytes);
/// Commands carry bounded JSON configuration/input metadata; raw PTY input and paste use raw
/// UTF-8/byte spans. Visible frames use the typed batched interface above, never per-cell calls.
pub const INPUT: u32 = 1;
pub const PASTE: u32 = 2;
pub const KEY: u32 = 3;
pub const RESIZE: u32 = 4;
pub const SCROLL: u32 = 5;
pub const SELECTION: u32 = 6;
pub const SELECT_ALL: u32 = 7;
pub const THEME: u32 = 8;
#[repr(C)]
#[derive(Clone, Copy)]
pub struct TerminalApi {
pub create: unsafe extern "C" fn(Bytes, Wake, *mut c_void, Reply) -> *mut c_void,
pub destroy: unsafe extern "C" fn(*mut c_void),
pub command: unsafe extern "C" fn(*mut c_void, u32, Bytes) -> i32,
pub frame: unsafe extern "C" fn(*mut c_void, u64, *mut c_void, FrameCallback) -> i32,
}
/// A service owns this context until its last callback, including rejection paths. Kind 0 is
/// one successful JSON reply, kind 1 a UTF-8 error, and kind 2 a JSON session event. Payloads
/// are bounded to 64 KiB and borrowed only during emit. Events may follow the start reply until
/// stop; release is called exactly once, after the final callback on any worker thread.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct ServiceSink {
pub context: *mut c_void,
pub emit: unsafe extern "C" fn(*mut c_void, u32, Bytes),
pub release: unsafe extern "C" fn(*mut c_void),
}
/// Calls enqueue work and return immediately. Request IDs identify sessions started with
/// "start"; subsequent commands carry that ID in their JSON. Shutdown cancels sessions without
/// waiting for network or main-thread work. Copy any borrowed input retained after returning.
/// One-shot operations can reply and release their sink without opening a session.
/// Invoke runs on the frontend UI worker; shutdown may run on the native main thread
/// concurrently with a final invoke. Extensions must serialize their own state without
/// blocking the main thread.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct ServiceApi {
pub invoke: unsafe extern "C" fn(u32, Bytes, Bytes, ServiceSink),
pub shutdown: unsafe extern "C" fn(),
}