//! The messages that the core and a UI send each other: requests from a UI, //! and responses and notifications from the core. const std = @import("std"); /// Picked by the UI. The response to a request carries the same id. pub const RequestId = u32; /// The version of this protocol. A core and a UI must have the same one. pub const version: u32 = 1; /// How many requests the core holds before it reads them. A UI keeps at most /// `inbox_capacity - 1` requests without a response, so a request is never /// refused for room and `detach` always fits. pub const inbox_capacity = 16; /// What the core sends to a UI. pub const core = struct { pub const Notice = struct { kind: Kind, text: []const u8, pub const Kind = enum { err, interrupted, info }; }; pub const Block = @import("content.zig").Block; pub const Usage = @import("provider.zig").Usage; /// What one provider request used, and the totals since the core started. pub const UsageReport = struct { request: Usage, /// In USD. Null when the price of the model is unknown. request_cost: ?f64, session: Usage, /// In USD. Null when the price of any request is unknown. session_cost: ?f64, /// How many tokens the conversation holds after this request. context_tokens: u64, /// How many tokens the model can hold. Zero when unknown. context_window: u32, }; pub const Level = @import("models.zig").Level; /// The model that answers the next request. pub const Selection = struct { model: []const u8, /// How much the model reasons. Null for a model without reasoning. level: ?Level, }; pub const Session = struct { model: []const u8, /// How much the model reasons. Null for a model without reasoning. level: ?Level = null, cwd: []const u8, pub fn deinit(self: Session, gpa: std.mem.Allocator) void { gpa.free(self.model); gpa.free(self.cwd); } }; /// The answer to one request. The core answers each request once, in the /// order it received them. pub const Response = struct { id: RequestId, result: Result, pub const Result = union(enum) { /// To `attach`: what the core works with. attached: Session, /// To `attach`: another UI is attached. already_attached, /// To `attach`: the UI has another protocol version than the core. incompatible, /// To `submit`: the prompt waits to run, after the prompts queued /// before it. queued, /// To `submit`: the core had no room for the prompt. refused, /// To `select_model`: no model with this name can be selected. unknown_model, /// To `detach`, `interrupt` and a change of the selection. ok, }; }; pub const Message = union(enum) { response: Response, text_delta: []const u8, thinking_delta: []const u8, /// A call the model made, as a UI shows it. tool_call: struct { id: []const u8, call: Block }, /// A finished call, as a UI shows it while collapsed and once expanded. tool_result: struct { call_id: []const u8, is_error: bool, collapsed: Block, expanded: Block }, notice: Notice, /// The model or the reasoning level changed. Requests that already /// run keep the selection they started with. Arrives before the /// response to the request that changed it. selection: Selection, /// A provider request ended and reported what it used. A request that /// failed or was interrupted can report usage too. usage: UsageReport, /// The first queued prompt started running. prompt_start, /// An interrupt took the first `count` queued prompts off the queue. `text` /// joins them in queue order with blank lines. prompts_returned: struct { count: usize, text: []const u8 }, /// The agent picked work up. Sent when a run starts, not when a prompt /// was submitted, so queued prompts do not flicker the UI. agent_start, /// Nothing is queued any more. agent_end, pub fn deinit(self: Message, gpa: std.mem.Allocator) void { switch (self) { .response => |response| switch (response.result) { .attached => |session| session.deinit(gpa), .already_attached, .incompatible, .queued, .refused, .unknown_model, .ok => {}, }, .text_delta => |text| gpa.free(text), .thinking_delta => |text| gpa.free(text), .tool_call => |call| { gpa.free(call.id); call.call.deinit(gpa); }, .tool_result => |result| { gpa.free(result.call_id); result.collapsed.deinit(gpa); result.expanded.deinit(gpa); }, .notice => |notice| gpa.free(notice.text), .selection => |selection| gpa.free(selection.model), .prompts_returned => |returned| gpa.free(returned.text), .usage, .prompt_start, .agent_start, .agent_end => {}, } } }; }; /// What a UI sends to the core. pub const ui = struct { pub const Request = struct { id: RequestId, method: Method, pub const Method = union(enum) { /// The core sends its messages to `sink` from now on. `version` /// is the protocol version of the UI. attach: struct { sink: Sink(core.Message), version: u32 = version }, /// Answered on this sink. When it is the attached sink, the response is /// the last message the core sends to it. detach: Sink(core.Message), /// The user submitted a prompt. submit: []const u8, /// The user wants the running prompt to stop and the queued prompts back. interrupt, /// Selects the model with this name and the nearest reasoning level /// that it supports. select_model: []const u8, /// Selects the next model that can be selected, and the first one /// after the last. cycle_model, /// Selects the next reasoning level that the model supports, and /// the first one after the last. cycle_level, }; pub fn deinit(self: Request, gpa: std.mem.Allocator) void { switch (self.method) { .submit, .select_model => |text| gpa.free(text), .attach, .detach, .interrupt, .cycle_model, .cycle_level => {}, } } }; }; /// Where messages of type `T` go. `send` takes ownership of the message and /// returns true, or returns false when the receiver is gone or refused it, and /// then the sender frees the message. pub fn Sink(comptime T: type) type { return struct { ctx: *anyopaque, sendFn: *const fn (ctx: *anyopaque, message: T) bool, pub fn send(self: @This(), message: T) bool { return self.sendFn(self.ctx, message); } pub fn eql(self: @This(), other: @This()) bool { return self.ctx == other.ctx and self.sendFn == other.sendFn; } }; }