anil.recoil.org
A Zulip bot agent to sit in our Black Sun. Ever evolving
1(*---------------------------------------------------------------------------
2 Copyright (c) 2026 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Combined loop for change detection, broadcast, and message handling.
7
8 This module implements a polling loop that periodically checks for new
9 changes in the monorepo and broadcasts them to Zulip. It also runs a
10 concurrent message handler to respond to DMs and mentions while the
11 broadcast loop sleeps. *)
12
13val run :
14 sw:Eio.Switch.t ->
15 env:< clock : float Eio.Time.clock_ty Eio.Resource.t ;
16 fs : Eio.Fs.dir_ty Eio.Path.t ;
17 net : [ `Generic | `Unix ] Eio.Net.ty Eio.Resource.t ;
18 process_mgr : _ Eio.Process.mgr ;
19 .. > ->
20 config:Config.t ->
21 zulip_config:Zulip_bot.Config.t ->
22 handler:Zulip_bot.Bot.handler ->
23 interval:int ->
24 unit
25(** [run ~sw ~env ~config ~zulip_config ~handler ~interval] starts both the
26 polling loop and the message handler concurrently.
27
28 The broadcast loop flow:
29 1. Pull latest changes from remote (git pull --ff-only)
30 2. Check if git HEAD has changed (compare with stored last_git_head)
31 3. If changed:
32 - Get commits since last HEAD via git log
33 - Fetch channel members for mention matching
34 - Generate narrative changelog using Claude
35 - Send to Zulip channel
36 - Update last_broadcast_time and last_git_head in storage
37 4. Sleep for interval seconds
38 5. Repeat
39
40 Concurrently, the message handler listens for incoming Zulip messages
41 (DMs and mentions) and processes them using the provided handler.
42
43 @param sw Eio switch for resource management
44 @param env Eio environment
45 @param config Poe configuration
46 @param zulip_config Zulip bot configuration
47 @param handler Message handler function
48 @param interval Seconds between broadcast checks (default: 3600) *)