Something went wrong. Try again.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443//! The protocol as JSON lines, for a core and a UI in two processes. Each//! message is one JSON object on one line.//!//! A request is `{"id":1,"method":"submit","params":"text"}`, a response is//! `{"id":1,"result":{"kind":"queued"}}` and a notification is//! `{"method":"text_delta","params":"text"}`. A reader ignores a field it//! does not know, so a message can get new fields.
const std = @import("std");
const protocol = @import("protocol.zig");const Request = protocol.ui.Request;const Message = protocol.core.Message;const Result = protocol.core.Response.Result;
const Allocator = std.mem.Allocator;
pub const ReadError = error{ /// The line is not a message of this protocol. Invalid, OutOfMemory,};
/// Writes one request as one line. `attach` and `detach` do not carry their/// sink: the channel that the line travels on takes its place.pub fn writeRequest(writer: *std.Io.Writer, request: Request) std.Io.Writer.Error!void { var json: std.json.Stringify = .{ .writer = writer }; try json.beginObject(); try json.objectField("id"); try json.write(request.id); try json.objectField("method"); try json.write(@tagName(request.method)); switch (request.method) { .attach => |attach| { try json.objectField("params"); try json.write(.{ .version = attach.version }); }, .submit, .select_model => |text| { try json.objectField("params"); try json.write(text); }, .detach, .interrupt, .cycle_model, .cycle_level => {}, } try json.endObject(); try writer.writeByte('\n');}
/// Reads one request from a line without its line break. The caller owns the/// request. `channel` becomes the sink of an `attach` or a `detach`.pub fn readRequest(gpa: Allocator, line: []const u8, channel: protocol.Sink(Message)) ReadError!Request { var arena_state: std.heap.ArenaAllocator = .init(gpa); defer arena_state.deinit(); const arena = arena_state.allocator();
const envelope = try parse(Envelope, arena, line); const id = envelope.id orelse return error.Invalid; const tag = std.meta.stringToEnum(std.meta.Tag(Request.Method), envelope.method orelse return error.Invalid) orelse return error.Invalid; const method: Request.Method = switch (tag) { .attach => .{ .attach = .{ .sink = channel, .version = (try fromValue(struct { version: u32 }, arena, envelope.params)).version, } }, .detach => .{ .detach = channel }, .submit => .{ .submit = try gpa.dupe(u8, try fromValue([]const u8, arena, envelope.params)) }, .select_model => .{ .select_model = try gpa.dupe(u8, try fromValue([]const u8, arena, envelope.params)) }, .interrupt => .interrupt, .cycle_model => .cycle_model, .cycle_level => .cycle_level, }; return .{ .id = id, .method = method };}
/// Writes one response or notification as one line.pub fn writeMessage(writer: *std.Io.Writer, message: Message) std.Io.Writer.Error!void { var json: std.json.Stringify = .{ .writer = writer }; try json.beginObject(); switch (message) { .response => |response| { try json.objectField("id"); try json.write(response.id); try json.objectField("result"); try json.beginObject(); try json.objectField("kind"); try json.write(@tagName(response.result)); switch (response.result) { .attached => |session| inline for (comptime std.meta.fieldNames(protocol.core.Session)) |name| { try json.objectField(name); try json.write(@field(session, name)); }, inline else => |payload| comptime std.debug.assert(@TypeOf(payload) == void), } try json.endObject(); }, inline else => |payload, tag| { try json.objectField("method"); try json.write(@tagName(tag)); if (@TypeOf(payload) != void) { try json.objectField("params"); try json.write(payload); } }, } try json.endObject(); try writer.writeByte('\n');}
/// Reads one response or notification from a line without its line break./// The caller owns the message.pub fn readMessage(gpa: Allocator, line: []const u8) ReadError!Message { var arena_state: std.heap.ArenaAllocator = .init(gpa); defer arena_state.deinit(); const arena = arena_state.allocator();
const envelope = try parse(Envelope, arena, line); const method = envelope.method orelse { const id = envelope.id orelse return error.Invalid; const kind = (try fromValue(struct { kind: []const u8 }, arena, envelope.result)).kind; const tag = std.meta.stringToEnum(std.meta.Tag(Result), kind) orelse return error.Invalid; const result: Result = switch (tag) { .attached => .{ .attached = try own(gpa, protocol.core.Session, try fromValue(protocol.core.Session, arena, envelope.result)) }, inline else => |void_tag| @unionInit(Result, @tagName(void_tag), {}), }; return .{ .response = .{ .id = id, .result = result } }; }; const tag = std.meta.stringToEnum(std.meta.Tag(Message), method) orelse return error.Invalid; switch (tag) { // A response has an id and no method. .response => return error.Invalid, inline else => |known| { const Payload = @FieldType(Message, @tagName(known)); if (Payload == void) { return @unionInit(Message, @tagName(known), {}); } const payload = try fromValue(Payload, arena, envelope.params); return @unionInit(Message, @tagName(known), try own(gpa, Payload, payload)); }, }}
const Envelope = struct { id: ?protocol.RequestId = null, method: ?[]const u8 = null, params: std.json.Value = .null, result: std.json.Value = .null,};
const parse_options: std.json.ParseOptions = .{ .ignore_unknown_fields = true };
fn parse(comptime T: type, arena: Allocator, text: []const u8) ReadError!T { return std.json.parseFromSliceLeaky(T, arena, text, parse_options) catch |err| switch (err) { error.OutOfMemory => error.OutOfMemory, else => error.Invalid, };}
fn fromValue(comptime T: type, arena: Allocator, value: std.json.Value) ReadError!T { return std.json.parseFromValueLeaky(T, arena, value, parse_options) catch |err| switch (err) { error.OutOfMemory => error.OutOfMemory, else => error.Invalid, };}
/// A copy of `value` in which `gpa` owns every slice, so that the `deinit`/// of a message can free each one.fn own(gpa: Allocator, comptime T: type, value: T) Allocator.Error!T { switch (@typeInfo(T)) { .void, .bool, .int, .float, .@"enum" => return value, .optional => |optional| return if (value) |inner| try own(gpa, optional.child, inner) else null, .pointer => |pointer| { comptime std.debug.assert(pointer.size == .slice); const copy = try gpa.alloc(pointer.child, value.len); var done: usize = 0; errdefer { for (copy[0..done]) |item| release(gpa, pointer.child, item); gpa.free(copy); } while (done < value.len) : (done += 1) { copy[done] = try own(gpa, pointer.child, value[done]); } return copy; }, .@"struct" => |info| { var copy: T = undefined; inline for (info.field_names, info.field_types, 0..) |name, Field, index| { @field(copy, name) = own(gpa, Field, @field(value, name)) catch |err| { inline for (info.field_names[0..index], info.field_types[0..index]) |earlier, Earlier| { release(gpa, Earlier, @field(copy, earlier)); } return err; }; } return copy; }, else => @compileError("the wire cannot carry " ++ @typeName(T)), }}
fn release(gpa: Allocator, comptime T: type, value: T) void { switch (@typeInfo(T)) { .void, .bool, .int, .float, .@"enum" => {}, .optional => |optional| if (value) |inner| release(gpa, optional.child, inner), .pointer => |pointer| { for (value) |item| release(gpa, pointer.child, item); gpa.free(value); }, .@"struct" => |info| inline for (info.field_names, info.field_types) |name, Field| { release(gpa, Field, @field(value, name)); }, else => comptime unreachable, }}
const testing = std.testing;
fn encodeMessage(arena: Allocator, message: Message) ![]const u8 { var out: std.Io.Writer.Allocating = .init(arena); try writeMessage(&out.writer, message); return out.written();}
fn encodeRequest(arena: Allocator, request: Request) ![]const u8 { var out: std.Io.Writer.Allocating = .init(arena); try writeRequest(&out.writer, request); return out.written();}
/// The line without its break, after a check that it is one line.fn oneLine(encoded: []const u8) ![]const u8 { try testing.expect(encoded.len > 0 and encoded[encoded.len - 1] == '\n'); const line = encoded[0 .. encoded.len - 1]; try testing.expect(std.mem.indexOfScalar(u8, line, '\n') == null); return line;}
fn discard(_: *anyopaque, _: Message) bool { return false;}
const test_channel: protocol.Sink(Message) = .{ .ctx = undefined, .sendFn = discard };
const tricky = "say \"hi\"\n\ttab \\ back, \u{597d} and \u{1F600}";
test "every message is one line and reads back as the same message" { var arena_state: std.heap.ArenaAllocator = .init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator();
const block: protocol.core.Block = .{ .text = "bash ls\nsecond", .runs = &.{ .{ .start = 0, .len = 4, .style = .{ .bold = true } }, .{ .start = 4, .len = 10, .style = .{ .italic = true, .color = 3 } }, }, }; const messages = [_]Message{ .{ .response = .{ .id = 7, .result = .{ .attached = .{ .model = "kimi", .level = .high, .cwd = "/work dir" } } } }, .{ .response = .{ .id = 8, .result = .{ .attached = .{ .model = "plain", .level = null, .cwd = "/" } } } }, .{ .response = .{ .id = 0, .result = .already_attached } }, .{ .response = .{ .id = 1, .result = .incompatible } }, .{ .response = .{ .id = 2, .result = .queued } }, .{ .response = .{ .id = 3, .result = .refused } }, .{ .response = .{ .id = 4, .result = .unknown_model } }, .{ .response = .{ .id = std.math.maxInt(protocol.RequestId), .result = .ok } }, .{ .text_delta = tricky }, .{ .text_delta = "" }, .{ .thinking_delta = "hm" }, .{ .tool_call = .{ .id = "call-1", .call = block } }, .{ .tool_call = .{ .id = "", .call = .{} } }, .{ .tool_result = .{ .call_id = "call-1", .is_error = true, .collapsed = .{ .text = "short" }, .expanded = block } }, .{ .notice = .{ .kind = .err, .text = tricky } }, .{ .notice = .{ .kind = .interrupted, .text = "interrupted" } }, .{ .notice = .{ .kind = .info, .text = "kimi" } }, .{ .selection = .{ .model = "kimi", .level = .off } }, .{ .selection = .{ .model = "plain", .level = null } }, .{ .usage = .{ .request = .{ .input = 1, .output = 2, .cache_read = 3, .cache_write = 4 }, .request_cost = 0.0123, .session = .{ .input = 5_000_000_000, .output = 6 }, .session_cost = null, .context_tokens = 10, .context_window = 1_048_576, } }, .prompt_start, .{ .prompts_returned = .{ .count = 2, .text = "one\n\ntwo" } }, .agent_start, .agent_end, }; for (messages) |message| { const line = try oneLine(try encodeMessage(arena, message)); const read = try readMessage(testing.allocator, line); defer read.deinit(testing.allocator); try testing.expectEqualDeep(message, read); }}
test "every request is one line and reads back as the same request, with the channel as its sink" { var arena_state: std.heap.ArenaAllocator = .init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator();
// Another sink than the channel: the wire must not carry it. const other: protocol.Sink(Message) = .{ .ctx = @ptrFromInt(8), .sendFn = discard }; const requests = [_]Request{ .{ .id = 0, .method = .{ .attach = .{ .sink = other, .version = 41 } } }, .{ .id = 1, .method = .{ .detach = other } }, .{ .id = 2, .method = .{ .submit = tricky } }, .{ .id = 3, .method = .{ .submit = "" } }, .{ .id = 4, .method = .interrupt }, .{ .id = 5, .method = .{ .select_model = "kimi-k2.6" } }, .{ .id = 6, .method = .cycle_model }, .{ .id = std.math.maxInt(protocol.RequestId), .method = .cycle_level }, }; for (requests) |request| { const line = try oneLine(try encodeRequest(arena, request)); const read = try readRequest(testing.allocator, line, test_channel); defer read.deinit(testing.allocator); try testing.expectEqual(request.id, read.id); try testing.expectEqual(std.meta.activeTag(request.method), std.meta.activeTag(read.method)); switch (read.method) { .attach => |attach| { try testing.expect(attach.sink.eql(test_channel)); try testing.expectEqual(@as(u32, 41), attach.version); }, .detach => |sink| try testing.expect(sink.eql(test_channel)), .submit => |text| try testing.expectEqualStrings(request.method.submit, text), .select_model => |name| try testing.expectEqualStrings(request.method.select_model, name), .interrupt, .cycle_model, .cycle_level => {}, } }}
test "the lines have the documented form" { var arena_state: std.heap.ArenaAllocator = .init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator();
try testing.expectEqualStrings( "{\"id\":1,\"method\":\"submit\",\"params\":\"hi\"}\n", try encodeRequest(arena, .{ .id = 1, .method = .{ .submit = "hi" } }), ); try testing.expectEqualStrings( "{\"id\":2,\"method\":\"interrupt\"}\n", try encodeRequest(arena, .{ .id = 2, .method = .interrupt }), ); try testing.expectEqualStrings( "{\"id\":1,\"result\":{\"kind\":\"queued\"}}\n", try encodeMessage(arena, .{ .response = .{ .id = 1, .result = .queued } }), ); try testing.expectEqualStrings( "{\"method\":\"text_delta\",\"params\":\"hi\"}\n", try encodeMessage(arena, .{ .text_delta = "hi" }), ); try testing.expectEqualStrings( "{\"method\":\"agent_end\"}\n", try encodeMessage(arena, .agent_end), );}
test "a field that the reader does not know is ignored" { const message = try readMessage( testing.allocator, \\{"method":"notice","later":[1,2],"params":{"kind":"info","text":"hi","color":"blue"}} , ); defer message.deinit(testing.allocator); try testing.expectEqualStrings("hi", message.notice.text);
const response = try readMessage( testing.allocator, \\{"id":3,"result":{"kind":"attached","model":"m","level":null,"cwd":"/","theme":"dark"},"took_ms":4} , ); defer response.deinit(testing.allocator); try testing.expectEqualStrings("m", response.response.result.attached.model);
const request = try readRequest( testing.allocator, \\{"id":3,"method":"attach","params":{"version":1,"name":"tui"},"trace":true} , test_channel, ); try testing.expectEqual(@as(u32, 1), request.method.attach.version);}
test "a line that is not a message is invalid and leaks nothing" { const bad_messages = [_][]const u8{ "", "not json", "[]", "{}", "{\"method\":\"nope\"}", "{\"method\":\"response\"}", "{\"method\":\"text_delta\"}", "{\"method\":\"text_delta\",\"params\":5}", "{\"method\":\"notice\",\"params\":{\"kind\":\"loud\",\"text\":\"hi\"}}", "{\"method\":\"tool_call\",\"params\":{\"id\":\"a\"}}", "{\"id\":1}", "{\"id\":1,\"result\":{\"kind\":\"nope\"}}", "{\"id\":1,\"result\":{\"kind\":\"attached\"}}", "{\"id\":-1,\"result\":{\"kind\":\"ok\"}}", "{\"method\":\"text_delta\",\"params\":\"cut", }; for (bad_messages) |line| { try testing.expectError(error.Invalid, readMessage(testing.allocator, line)); }
const bad_requests = [_][]const u8{ "", "{}", "{\"method\":\"interrupt\"}", "{\"id\":1}", "{\"id\":1,\"method\":\"nope\"}", "{\"id\":1,\"method\":\"submit\"}", "{\"id\":1,\"method\":\"submit\",\"params\":{}}", "{\"id\":1,\"method\":\"attach\"}", "{\"id\":1,\"method\":\"attach\",\"params\":{}}", }; for (bad_requests) |line| { try testing.expectError(error.Invalid, readRequest(testing.allocator, line, test_channel)); }}
fn readAndFree(gpa: Allocator, line: []const u8) !void { const message = try readMessage(gpa, line); message.deinit(gpa);}
test "a failed allocation while a message is read leaks nothing" { var arena_state: std.heap.ArenaAllocator = .init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator();
const block: protocol.core.Block = .{ .text = "ab", .runs = &.{.{ .start = 0, .len = 2, .style = .{} }} }; const messages = [_]Message{ .{ .tool_result = .{ .call_id = "call-1", .is_error = false, .collapsed = block, .expanded = block } }, .{ .response = .{ .id = 1, .result = .{ .attached = .{ .model = "m", .level = .low, .cwd = "/w" } } } }, }; for (messages) |message| { const line = try oneLine(try encodeMessage(arena, message)); try testing.checkAllAllocationFailures(testing.allocator, readAndFree, .{line}); }}