My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** SDK Control Protocol for Claude.
2
3 This module defines the typed SDK control protocol for communication
4 between the SDK and Claude, including request and response types. *)
5
6open Ezjsonm
7
8(** The log source for SDK control operations *)
9val src : Logs.Src.t
10
11(** {1 Request Types} *)
12
13module Request : sig
14 (** SDK control request types. *)
15
16 type interrupt = {
17 subtype : [`Interrupt];
18 }
19 (** Interrupt request to stop execution. *)
20
21 type permission = {
22 subtype : [`Can_use_tool];
23 tool_name : string;
24 input : value;
25 permission_suggestions : Permissions.Update.t list option;
26 blocked_path : string option;
27 }
28 (** Permission request for tool usage. *)
29
30 type initialize = {
31 subtype : [`Initialize];
32 hooks : (string * value) list option; (* Hook event to configuration *)
33 }
34 (** Initialize request with optional hook configuration. *)
35
36 type set_permission_mode = {
37 subtype : [`Set_permission_mode];
38 mode : Permissions.Mode.t;
39 }
40 (** Request to change permission mode. *)
41
42 type hook_callback = {
43 subtype : [`Hook_callback];
44 callback_id : string;
45 input : value;
46 tool_use_id : string option;
47 }
48 (** Hook callback request. *)
49
50 type mcp_message = {
51 subtype : [`Mcp_message];
52 server_name : string;
53 message : value;
54 }
55 (** MCP server message request. *)
56
57 type t =
58 | Interrupt of interrupt
59 | Permission of permission
60 | Initialize of initialize
61 | Set_permission_mode of set_permission_mode
62 | Hook_callback of hook_callback
63 | Mcp_message of mcp_message
64 (** The type of SDK control requests. *)
65
66 val interrupt : unit -> t
67 (** [interrupt ()] creates an interrupt request. *)
68
69 val permission :
70 tool_name:string ->
71 input:value ->
72 ?permission_suggestions:Permissions.Update.t list ->
73 ?blocked_path:string ->
74 unit -> t
75 (** [permission ~tool_name ~input ?permission_suggestions ?blocked_path ()]
76 creates a permission request. *)
77
78 val initialize : ?hooks:(string * value) list -> unit -> t
79 (** [initialize ?hooks ()] creates an initialize request. *)
80
81 val set_permission_mode : mode:Permissions.Mode.t -> t
82 (** [set_permission_mode ~mode] creates a permission mode change request. *)
83
84 val hook_callback :
85 callback_id:string ->
86 input:value ->
87 ?tool_use_id:string ->
88 unit -> t
89 (** [hook_callback ~callback_id ~input ?tool_use_id ()] creates a hook callback request. *)
90
91 val mcp_message : server_name:string -> message:value -> t
92 (** [mcp_message ~server_name ~message] creates an MCP message request. *)
93
94 val to_json : t -> value
95 (** [to_json t] converts a request to JSON. *)
96
97 val of_json : value -> t
98 (** [of_json json] parses a request from JSON.
99 @raise Invalid_argument if the JSON is not a valid request. *)
100
101 val pp : Format.formatter -> t -> unit
102 (** [pp fmt t] pretty-prints the request. *)
103end
104
105(** {1 Response Types} *)
106
107module Response : sig
108 (** SDK control response types. *)
109
110 type success = {
111 subtype : [`Success];
112 request_id : string;
113 response : value option;
114 }
115 (** Successful response. *)
116
117 type error = {
118 subtype : [`Error];
119 request_id : string;
120 error : string;
121 }
122 (** Error response. *)
123
124 type t =
125 | Success of success
126 | Error of error
127 (** The type of SDK control responses. *)
128
129 val success : request_id:string -> ?response:value -> unit -> t
130 (** [success ~request_id ?response ()] creates a success response. *)
131
132 val error : request_id:string -> error:string -> t
133 (** [error ~request_id ~error] creates an error response. *)
134
135 val to_json : t -> value
136 (** [to_json t] converts a response to JSON. *)
137
138 val of_json : value -> t
139 (** [of_json json] parses a response from JSON.
140 @raise Invalid_argument if the JSON is not a valid response. *)
141
142 val pp : Format.formatter -> t -> unit
143 (** [pp fmt t] pretty-prints the response. *)
144end
145
146(** {1 Control Messages} *)
147
148type control_request = {
149 type_ : [`Control_request];
150 request_id : string;
151 request : Request.t;
152}
153(** Control request message. *)
154
155type control_response = {
156 type_ : [`Control_response];
157 response : Response.t;
158}
159(** Control response message. *)
160
161type t =
162 | Request of control_request
163 | Response of control_response
164(** The type of SDK control messages. *)
165
166val create_request : request_id:string -> request:Request.t -> t
167(** [create_request ~request_id ~request] creates a control request message. *)
168
169val create_response : response:Response.t -> t
170(** [create_response ~response] creates a control response message. *)
171
172val to_json : t -> value
173(** [to_json t] converts a control message to JSON. *)
174
175val of_json : value -> t
176(** [of_json json] parses a control message from JSON.
177 @raise Invalid_argument if the JSON is not a valid control message. *)
178
179val pp : Format.formatter -> t -> unit
180(** [pp fmt t] pretty-prints the control message. *)
181
182(** {1 Logging} *)
183
184val log_request : Request.t -> unit
185(** [log_request req] logs an SDK control request. *)
186
187val log_response : Response.t -> unit
188(** [log_response resp] logs an SDK control response. *)