///|
/// What the transport has to do about one incoming line.
priv enum Action {
Reply(Json)
Call(id~ : Json, tool~ : Tool, arguments~ : Json, era~ : Era)
Cancel(request_id~ : Json)
Nothing
}
///|
fn Server::dispatch(self : Server, line : String) -> Action {
match parse_message(line) {
Unparseable(reason) =>
Reply(error_response(Json::null(), parse_error(reason)))
Malformed(id~, reason~) =>
Reply(error_response(id, invalid_request(reason)))
Response => Nothing
Notification(name~, params~) =>
match (name, params.get("requestId")) {
(
"notifications/cancelled",
Some(String(_) as id)
| Some(Number(_) as id),
) => Cancel(request_id=id)
_ => Nothing
}
Request(id~, name~, params~) => self.route(id, name, params)
}
}
///|
fn Server::route(
self : Server,
id : Json,
name : String,
params : Map[String, Json],
) -> Action {
let outcome = match name {
"initialize" => self.initialize(params)
"ping" => self.ping(params)
"server/discover" => self.discover(params)
"tools/list" => self.list_tools(params)
"tools/call" =>
match self.plan_call(params) {
Ok((tool, arguments, era)) => return Call(id~, tool~, arguments~, era~)
Err(error) => Err(error)
}
_ => Err(method_not_found(name))
}
match outcome {
Ok(result) => Reply(result_response(id, result))
Err(error) => Reply(error_response(id, error))
}
}
///|
/// Runs the tool of a planned call. The only await in the protocol, so the
/// transport can keep reading while a handler waits.
async fn Server::respond(
self : Server,
id~ : Json,
tool~ : Tool,
arguments~ : Json,
era~ : Era,
) -> Json {
let result = (tool.invoke)(arguments, self.on_invalid)
result_response(id, self.result_for(era, result.to_fields()))
}
///|
fn Server::initialize(
self : Server,
params : Map[String, Json],
) -> Result[Json, RpcError] {
guard params.get("protocolVersion") is Some(String(requested)) else {
return Err(invalid_params("`protocolVersion` is required"))
}
let negotiated = if legacy_versions.contains(requested) {
requested
} else {
fallback_legacy_version
}
self.initialized = true
let fields : Array[(String, Json)] = [
("protocolVersion", Json(negotiated)),
("capabilities", capabilities),
("serverInfo", self.server_info()),
]
self.add_instructions(fields)
Ok(Json::object(Map::from_array(fields)))
}
///|
fn Server::ping(
self : Server,
params : Map[String, Json],
) -> Result[Json, RpcError] {
match resolve_era(params, self.initialized) {
Ok(era) => Ok(self.result_for(era, []))
Err({ code, .. } as error) if code == unsupported_version_code => Err(error)
Err(_) => Ok({})
}
}
///|
fn Server::discover(
self : Server,
params : Map[String, Json],
) -> Result[Json, RpcError] {
match resolve_era(params, self.initialized) {
Err(error) => Err(error)
Ok(Legacy) => Err(method_not_found("server/discover"))
Ok(Modern) => {
let fields : Array[(String, Json)] = [
(
"supportedVersions",
Json::array(supported_versions().map(v => Json(v))),
),
("capabilities", capabilities),
]
self.add_instructions(fields)
fields.append(caching_hints)
Ok(self.result_for(Modern, fields))
}
}
}
///|
fn Server::list_tools(
self : Server,
params : Map[String, Json],
) -> Result[Json, RpcError] {
match resolve_era(params, self.initialized) {
Err(error) => Err(error)
Ok(era) => {
let fields : Array[(String, Json)] = [
("tools", Json::array(self.tools.map(t => t.to_json()))),
]
if era is Modern {
fields.append(caching_hints)
}
Ok(self.result_for(era, fields))
}
}
}
///|
fn Server::plan_call(
self : Server,
params : Map[String, Json],
) -> Result[(Tool, Json, Era), RpcError] {
let era = match resolve_era(params, self.initialized) {
Err(error) => return Err(error)
Ok(era) => era
}
guard params.get("name") is Some(String(name)) else {
return Err(invalid_params("`name` is required"))
}
let arguments = match params.get("arguments") {
None | Some(Null) => Json::object({})
Some(Object(_) as arguments) => arguments
Some(_) => return Err(invalid_params("`arguments` must be an object"))
}
for tool in self.tools {
if tool.name == name {
return Ok((tool, arguments, era))
}
}
Err(invalid_params("Unknown tool: \{name}"))
}
///|
/// The tool list is fixed at startup, so an hour is a safe lifetime. Clients
/// that validate against the 2026-07-28 schema reject list results without it.
let cache_ttl_ms : Int32 = 3600000
///|
/// `public` because the list is identical for every user of this server.
let caching_hints : Array[(String, Json)] = [
("ttlMs", Json(cache_ttl_ms)),
("cacheScope", "public"),
]