tiny.acp.Update

1/// One `session/update` notification from the agent, with the two numbers the client gave it, the2/// exact line, and fields read from it, received by the observer so the caller records and inspects3/// the agent's progress. The client builds one structure per notification, hands it to the4/// observer, and frees it when the callback returns. The structure owns every `[]u8` field, and5/// `deinit` frees them. A field the notification lacks is empty, null or 0.6pub const Update = struct {7    /// The caller's number for the client that received the notification.8    transport_epoch: u64,9    /// The notification's place among all the notifications the client has received, counting10    /// from 1.11    update_sequence: u64,12    /// The exact line the agent sent, trimmed of surrounding whitespace. The client trims spaces,13    /// tabs, carriage returns and newlines from both ends of the line. This slice is borrowed from14    /// the reader's buffer and remains valid only until the observer's callback returns. The15    /// `deinit` function leaves it alone.16    envelope: []const u8,17    /// The kind read from `sessionUpdate`.18    kind: UpdateKind,19    /// The `sessionUpdate` string as the agent sent it. The update owns this field.20    name: []u8,21    /// The notification's `params.sessionId`, empty when absent. The update owns this field.22    session_id: []u8,23    /// A summary text for the notification. For an `agent_message_chunk`, this field carries the24    /// chunk's text, and the client adds it to the reply. The client picks the first of these the25    /// update carries: the content text, the title, the mode id, the first plan entry's content,26    /// the first command name, the usage as "used/size", and else the update's name. The update27    /// owns this field.28    text: []u8,29    /// A minified JSON copy of the `params.update` object. The update owns this field.30    raw: []u8,31    /// The update's `toolCallId`, empty when absent. The update owns this field.32    tool_call_id: []u8 = &.{},33    /// The update's `status`, empty when absent. The update owns this field.34    status: []u8 = &.{},35    /// The update's `kind`, the tool call's kind, empty when absent. The update owns this field.36    tool_kind: []u8 = &.{},37    /// The update's `currentModeId`, empty when absent. The update owns this field.38    mode_id: []u8 = &.{},39    /// The update's integer `used`, or null when absent.40    usage_used: ?i64 = null,41    /// The update's integer `size`, or null when absent.42    usage_size: ?i64 = null,43    /// The number of entries in the update's `entries` list, 0 when absent.44    plan_entries: usize = 0,45    /// The number of entries in the update's `availableCommands` list, 0 when absent.46    available_commands: usize = 0,47    /// The number of entries in the update's `configOptions` list, 0 when absent.48    config_options: usize = 0,49    /// The update's `title`, empty when absent. The update owns this field.50    title: []u8 = &.{},51    /// The update's `updatedAt`, empty when absent. The update owns this field.52    updated_at: []u8 = &.{},5354    /// Frees every owned string with the given allocator and leaves the value undefined, so the55    /// caller frees an update built with `fromSessionNotification`. The call leaves the borrowed56    /// line alone.57    pub fn deinit(self: *Update, allocator: Allocator) void {58        if (self.name.len != 0) allocator.free(self.name);59        if (self.session_id.len != 0) allocator.free(self.session_id);60        if (self.text.len != 0) allocator.free(self.text);61        if (self.raw.len != 0) allocator.free(self.raw);62        if (self.tool_call_id.len != 0) allocator.free(self.tool_call_id);63        if (self.status.len != 0) allocator.free(self.status);64        if (self.tool_kind.len != 0) allocator.free(self.tool_kind);65        if (self.mode_id.len != 0) allocator.free(self.mode_id);66        if (self.title.len != 0) allocator.free(self.title);67        if (self.updated_at.len != 0) allocator.free(self.updated_at);68        self.* = undefined;69    }7071    /// Reads `params.update` from a parsed notification object, so the caller turns one parsed72    /// `session/update` notification into an `Update`, as the client does for each one it reads.73    /// The call returns null when `params`, `params.update` or its `sessionUpdate` string is74    /// missing, and the client then fails its call with `error.AgentProtocolError`. The function75    /// stores the given epoch, sequence and line, and keeps the line by reference. The call copies76    /// every string it keeps with the allocator, and the caller frees them with `deinit`. The77    /// function fails with `error.OutOfMemory` and leaves nothing allocated when a copy fails. The78    /// call reads the object as given and does not look at `method`, because the client checks the79    /// method name before it calls this.80    pub fn fromSessionNotification(81        allocator: Allocator,82        object: std.json.ObjectMap,83        transport_epoch: u64,84        update_sequence: u64,85        envelope: []const u8,86    ) !?Update {87        const params = json.objectObject(object, "params") orelse return null;88        const update = json.objectObject(params, "update") orelse return null;89        const name = json.objectString(update, "sessionUpdate") orelse return null;90        const session_id = json.objectString(params, "sessionId") orelse "";91        const owned_name = try allocator.dupe(u8, name);92        errdefer allocator.free(owned_name);93        const owned_session = try allocator.dupe(u8, session_id);94        errdefer allocator.free(owned_session);95        const text = try summaryTextAlloc(allocator, update, name);96        errdefer if (text.len != 0) allocator.free(text);97        const raw = try rawJsonAlloc(allocator, update);98        errdefer if (raw.len != 0) allocator.free(raw);99        const tool_call_id = try optionalStringAlloc(allocator, update, "toolCallId");100        errdefer if (tool_call_id.len != 0) allocator.free(tool_call_id);101        const status = try optionalStringAlloc(allocator, update, "status");102        errdefer if (status.len != 0) allocator.free(status);103        const tool_kind = try optionalStringAlloc(allocator, update, "kind");104        errdefer if (tool_kind.len != 0) allocator.free(tool_kind);105        const mode_id = try optionalStringAlloc(allocator, update, "currentModeId");106        errdefer if (mode_id.len != 0) allocator.free(mode_id);107        const title = try optionalStringAlloc(allocator, update, "title");108        errdefer if (title.len != 0) allocator.free(title);109        const updated_at = try optionalStringAlloc(allocator, update, "updatedAt");110        errdefer if (updated_at.len != 0) allocator.free(updated_at);111        return .{112            .transport_epoch = transport_epoch,113            .update_sequence = update_sequence,114            .envelope = envelope,115            .kind = kindFromName(name),116            .name = owned_name,117            .session_id = owned_session,118            .text = text,119            .raw = raw,120            .tool_call_id = tool_call_id,121            .status = status,122            .tool_kind = tool_kind,123            .mode_id = mode_id,124            .usage_used = json.objectInteger(update, "used"),125            .usage_size = json.objectInteger(update, "size"),126            .plan_entries = arrayLength(update, "entries"),127            .available_commands = arrayLength(update, "availableCommands"),128            .config_options = arrayLength(update, "configOptions"),129            .title = title,130            .updated_at = updated_at,131        };132    }133134    /// Returns true for an `agent_message_chunk`, the only kind the client adds to a reply, so the135    /// caller tells whether an update carries reply text.136    pub fn assistantMessage(self: Update) bool {137        return self.kind == .agent_message_chunk;138    }139};

1pub const Update = protocol.Update;