Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

feat(socket): register socket controllers as bound entries

Steven Enamakelaea56b21d323
diff --git a/crates/openhuman-core/src/core/all.rs b/crates/openhuman-core/src/core/all.rs
index ed43677bea..a42e68f578 100644
--- a/crates/openhuman-core/src/core/all.rs
+++ b/crates/openhuman-core/src/core/all.rs
@@ -510,10 +510,10 @@ fn build_registered_controllers() -> Vec<GroupedController> {
crate::sandbox::all_sandbox_registered_controllers(),
);
// Backend Socket.IO bridge + related runtime plumbing
- push(
+ push_entries(
&mut controllers,
DomainGroup::Platform,
- crate::platform::socket::all_socket_registered_controllers(),
+ crate::platform::socket::all_controller_entries(),
);
// Discovered SKILL.md skills and their bundled resources
push(
diff --git a/crates/openhuman-core/src/core/all_bound_controller_tests.rs b/crates/openhuman-core/src/core/all_bound_controller_tests.rs
index 2f543ef944..a1d8e773f5 100644
--- a/crates/openhuman-core/src/core/all_bound_controller_tests.rs
+++ b/crates/openhuman-core/src/core/all_bound_controller_tests.rs
@@ -11,6 +11,8 @@ static EVENTS: Mutex<Vec<&'static str>> = Mutex::new(Vec::new());
fn staged_bound_methods() -> Vec<&'static str> {
let mut methods = vec!["composio.execute"];
+ #[cfg(feature = "mcp")]
+ methods.push("mcp_clients.registry_get");
methods.extend([
"socket.connect",
"socket.disconnect",
@@ -18,8 +20,6 @@ fn staged_bound_methods() -> Vec<&'static str> {
"socket.emit",
"socket.connect_with_session",
]);
- #[cfg(feature = "mcp")]
- methods.push("mcp_clients.registry_get");
#[cfg(feature = "voice")]
methods.extend([
"voice.status",
@@ -46,8 +46,6 @@ fn staged_bound_methods() -> Vec<&'static str> {
#[test]
fn production_registry_binds_every_socket_controller_to_its_declared_parser() {
- use serde_json::json;
-
let entries: Vec<_> = registry()
.iter()
.filter(|grouped| {
@@ -67,41 +65,7 @@ fn production_registry_binds_every_socket_controller_to_its_declared_parser() {
.starts_with("socket.")),
"socket methods remain public registry entries"
);
- let contracts = [
- ControllerParamContract {
- method: "socket.connect",
- required: &["url", "token"],
- optional: &[],
- examples: vec![json!({"url":"https://example.invalid/socket", "token":"test-token"})],
- },
- ControllerParamContract {
- method: "socket.disconnect",
- required: &[],
- optional: &[],
- examples: vec![json!({})],
- },
- ControllerParamContract {
- method: "socket.state",
- required: &[],
- optional: &[],
- examples: vec![json!({})],
- },
- ControllerParamContract {
- method: "socket.emit",
- required: &["event"],
- optional: &["data"],
- examples: vec![
- json!({"event":"message", "data":{"text":"hello"}}),
- json!({"event":"message"}),
- ],
- },
- ControllerParamContract {
- method: "socket.connect_with_session",
- required: &[],
- optional: &[],
- examples: vec![json!({})],
- },
- ];
+ let contracts = crate::platform::socket::socket_parameter_contracts();
assert_eq!(
entries.len(),
contracts.len(),
@@ -595,9 +559,11 @@ fn production_registry_binds_composio_execute_to_its_declared_parser() {
.find(|field| field.name == "tool")
.expect("tool schema field")
.required = false;
- assert!(required_input_contract(&optional_required, &["tool"])
+ assert!(
+ required_input_contract(&optional_required, &["tool"])
.unwrap_err()
- .contains("required inputs mismatch"));
+ .contains("required inputs mismatch")
+ );
for example in [
json!({"tool":"GMAIL_SEND_EMAIL"}),
diff --git a/crates/openhuman-core/src/platform/socket/mod.rs b/crates/openhuman-core/src/platform/socket/mod.rs
index 0db1116798..925792e233 100644
--- a/crates/openhuman-core/src/platform/socket/mod.rs
+++ b/crates/openhuman-core/src/platform/socket/mod.rs
@@ -14,8 +14,13 @@ pub mod types;
pub mod url;
pub(crate) mod ws_loop;
-pub use manager::{global_socket_manager, set_global_socket_manager, SocketManager};
+pub use manager::{SocketManager, global_socket_manager, set_global_socket_manager};
pub use schemas::{
all_controller_schemas as all_socket_controller_schemas,
all_registered_controllers as all_socket_registered_controllers,
};
+
+pub(crate) use schemas::all_controller_entries;
+
+#[cfg(test)]
+pub(crate) use schemas::socket_parameter_contracts;
diff --git a/crates/openhuman-core/src/platform/socket/schemas.rs b/crates/openhuman-core/src/platform/socket/schemas.rs
index 467bf66a94..85e47d9173 100644
--- a/crates/openhuman-core/src/platform/socket/schemas.rs
+++ b/crates/openhuman-core/src/platform/socket/schemas.rs
@@ -1,9 +1,12 @@
//! Controller schemas and RPC handlers for the `socket` namespace.
use crate::core::runtime::DispatchCtx;
-use serde_json::{json, Map, Value};
+use serde_json::{Map, Value, json};
-use crate::core::all::{ControllerFuture, RegisteredController};
+use crate::core::all::{
+ BoundRegisteredController, ControllerEntry, ControllerFuture, ControllerTask,
+ RegisteredController,
+};
use crate::core::{ControllerSchema, FieldSchema, TypeSchema};
use super::manager::global_socket_manager;
@@ -48,6 +51,17 @@ pub fn all_registered_controllers() -> Vec<RegisteredController> {
]
}
+/// Runtime registrations share each decoder with the compatible legacy handlers below.
+pub(crate) fn all_controller_entries() -> Vec<ControllerEntry> {
+ vec![
+ connect_entry(),
+ disconnect_entry(),
+ state_entry(),
+ emit_entry(),
+ connect_with_session_entry(),
+ ]
+}
+
pub fn schemas(function: &str) -> ControllerSchema {
match function {
"connect" => ControllerSchema {
@@ -127,8 +141,7 @@ pub fn schemas(function: &str) -> ControllerSchema {
"connect_with_session" => ControllerSchema {
namespace: "socket",
function: "connect_with_session",
- description:
- "Connect to the backend using the stored session token and configured API URL.",
+ description: "Connect to the backend using the stored session token and configured API URL.",
inputs: vec![],
outputs: vec![FieldSchema {
name: "status",
@@ -161,6 +174,98 @@ fn require_manager() -> Result<&'static std::sync::Arc<super::SocketManager>, St
.ok_or_else(|| "SocketManager not initialized — runtime not bootstrapped".to_string())
}
+type SocketManagerRef = &'static std::sync::Arc<super::SocketManager>;
+
+struct ConnectParams {
+ url: String,
+ token: String,
+}
+
+struct EmitParams {
+ event: String,
+ data: Value,
+}
+
+fn gate_manager(_ctx: DispatchCtx) -> ControllerTask<SocketManagerRef> {
+ Box::pin(async { require_manager() })
+}
+
+fn parse_connect(params: Map<String, Value>) -> Result<ConnectParams, String> {
+ let url = params
+ .get("url")
+ .and_then(Value::as_str)
+ .ok_or("missing required param 'url'")?;
+ let token = params
+ .get("token")
+ .and_then(Value::as_str)
+ .ok_or("missing required param 'token'")?;
+ Ok(ConnectParams {
+ url: url.to_owned(),
+ token: token.to_owned(),
+ })
+}
+
+fn parse_emit(params: Map<String, Value>) -> Result<EmitParams, String> {
+ let event = params
+ .get("event")
+ .and_then(Value::as_str)
+ .ok_or("missing required param 'event'")?;
+ let data = params.get("data").cloned().unwrap_or(Value::Null);
+ Ok(EmitParams {
+ event: event.to_owned(),
+ data,
+ })
+}
+
+fn parse_ignored_params(_params: Map<String, Value>) -> Result<(), String> {
+ Ok(())
+}
+
+fn connect_entry() -> ControllerEntry {
+ ControllerEntry::bound(BoundRegisteredController::after_gate(
+ schemas("connect"),
+ gate_manager,
+ parse_connect,
+ run_connect,
+ ))
+}
+
+fn disconnect_entry() -> ControllerEntry {
+ ControllerEntry::bound(BoundRegisteredController::after_gate(
+ schemas("disconnect"),
+ gate_manager,
+ parse_ignored_params,
+ run_disconnect,
+ ))
+}
+
+fn state_entry() -> ControllerEntry {
+ ControllerEntry::bound(BoundRegisteredController::after_gate(
+ schemas("state"),
+ gate_manager,
+ parse_ignored_params,
+ run_state,
+ ))
+}
+
+fn emit_entry() -> ControllerEntry {
+ ControllerEntry::bound(BoundRegisteredController::after_gate(
+ schemas("emit"),
+ gate_manager,
+ parse_emit,
+ run_emit,
+ ))
+}
+
+fn connect_with_session_entry() -> ControllerEntry {
+ ControllerEntry::bound(BoundRegisteredController::after_gate(
+ schemas("connect_with_session"),
+ gate_manager,
+ parse_ignored_params,
+ run_connect_with_session,
+ ))
+}
+
/// Serialise a [`ConnectionStatus`] the way every other surface publishes it.
///
/// `socket_state` (`serde_json::to_value(state)`) and `connectivity_diag` both go through
@@ -184,63 +289,76 @@ fn status_slug(status: ConnectionStatus) -> String {
.unwrap_or_else(|| format!("{status:?}").to_lowercase())
}
-fn handle_connect(_ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+fn run_connect(
+ _ctx: DispatchCtx,
+ manager: SocketManagerRef,
+ params: ConnectParams,
+) -> ControllerFuture {
Box::pin(async move {
- let mgr = require_manager()?;
- let url = params
- .get("url")
- .and_then(|v| v.as_str())
- .ok_or("missing required param 'url'")?;
- let token = params
- .get("token")
- .and_then(|v| v.as_str())
- .ok_or("missing required param 'token'")?;
-
- let state = super::ops::connect_static(mgr, url, token).await?;
+ let state = super::ops::connect_static(manager, &params.url, &params.token).await?;
Ok(status_payload(&state))
})
}
-fn handle_disconnect(_ctx: DispatchCtx, _params: Map<String, Value>) -> ControllerFuture {
+fn run_disconnect(_ctx: DispatchCtx, manager: SocketManagerRef, _params: ()) -> ControllerFuture {
Box::pin(async move {
- let mgr = require_manager()?;
- let state = super::ops::disconnect(mgr).await?;
+ let state = super::ops::disconnect(manager).await?;
Ok(status_payload(&state))
})
}
-fn handle_state(_ctx: DispatchCtx, _params: Map<String, Value>) -> ControllerFuture {
+fn run_state(_ctx: DispatchCtx, manager: SocketManagerRef, _params: ()) -> ControllerFuture {
Box::pin(async move {
- let mgr = require_manager()?;
- let state = mgr.get_state();
+ let state = manager.get_state();
log::debug!("[socket:rpc] state → {:?}", state.status);
serde_json::to_value(state).map_err(|e| format!("serialize: {e}"))
})
}
-fn handle_emit(_ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+fn run_emit(_ctx: DispatchCtx, manager: SocketManagerRef, params: EmitParams) -> ControllerFuture {
Box::pin(async move {
- let mgr = require_manager()?;
- let event = params
- .get("event")
- .and_then(|v| v.as_str())
- .ok_or("missing required param 'event'")?;
- let data = params.get("data").cloned().unwrap_or(Value::Null);
-
- log::debug!("[socket:rpc] emit event={}", event);
- mgr.emit(event, data).await?;
+ log::debug!("[socket:rpc] emit event={}", params.event);
+ manager.emit(&params.event, params.data).await?;
Ok(json!({ "ok": true }))
})
}
-fn handle_connect_with_session(ctx: DispatchCtx, _params: Map<String, Value>) -> ControllerFuture {
+fn run_connect_with_session(
+ ctx: DispatchCtx,
+ manager: SocketManagerRef,
+ _params: (),
+) -> ControllerFuture {
Box::pin(async move {
- let mgr = require_manager()?;
- let state = super::ops::connect_with_session(&ctx, mgr).await?;
+ let state = super::ops::connect_with_session(&ctx, manager).await?;
Ok(status_payload(&state))
})
}
+fn handle_connect(ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+ connect_entry().invoke(ctx, params)
+}
+
+fn handle_disconnect(ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+ disconnect_entry().invoke(ctx, params)
+}
+
+fn handle_state(ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+ state_entry().invoke(ctx, params)
+}
+
+fn handle_emit(ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+ emit_entry().invoke(ctx, params)
+}
+
+fn handle_connect_with_session(ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+ connect_with_session_entry().invoke(ctx, params)
+}
+
+#[cfg(test)]
+pub(crate) fn socket_parameter_contracts() -> Vec<crate::core::all::ControllerParamContract> {
+ tests::socket_parameter_contracts()
+}
+
#[cfg(test)]
#[path = "schemas_tests.rs"]
mod tests;
diff --git a/crates/openhuman-core/src/platform/socket/schemas_tests.rs b/crates/openhuman-core/src/platform/socket/schemas_tests.rs
index 7e2ad786b8..52049459dd 100644
--- a/crates/openhuman-core/src/platform/socket/schemas_tests.rs
+++ b/crates/openhuman-core/src/platform/socket/schemas_tests.rs
@@ -1,56 +1,173 @@
use super::*;
use crate::core::all::{
- assert_schema_controller_parity, expect_schema_fields, expect_schema_identity,
- expect_schema_required_inputs,
+ ControllerHandler, ControllerParamContract, assert_schema_controller_parity,
+ verify_parameter_schema,
};
use crate::core::runtime::DispatchCtx;
#[test]
fn socket_schema_contracts_are_preserved() {
- crate::core::all::expect_schema_namespace(&all_controller_schemas(), "socket");
- assert_schema_controller_parity(
- &all_controller_schemas(),
- &all_registered_controllers(),
- "connect",
- );
- let functions: Vec<_> = all_controller_schemas()
- .iter()
- .map(|schema| schema.function)
- .collect();
- assert_eq!(functions.len(), 5);
- for expected in [
- "connect",
- "disconnect",
- "state",
- "emit",
- "connect_with_session",
- ] {
- assert!(functions.contains(&expected), "missing socket.{expected}");
+ let schemas = all_controller_schemas();
+ crate::core::all::expect_schema_namespace(&schemas, "socket");
+ assert_schema_controller_parity(&schemas, &all_registered_controllers(), "connect");
+ let contracts = socket_parameter_contracts();
+ for contract in &contracts {
+ let schema = schemas
+ .iter()
+ .find(|schema| schema.method_name() == contract.method)
+ .expect("socket schema has an independent contract");
+ verify_parameter_schema(schema, contract)
+ .expect("independent socket schema contract matches");
}
- for schema in all_controller_schemas() {
- assert_eq!(schema.namespace, "socket");
+ for schema in schemas {
assert!(
!schema.outputs.is_empty(),
"{} output fields",
schema.function
);
}
- for (function, required) in [
- ("connect", &["url", "token"][..]),
- ("disconnect", &[][..]),
- ("state", &[][..]),
- ("connect_with_session", &[][..]),
+}
+
+pub(super) fn socket_parameter_contracts() -> Vec<ControllerParamContract> {
+ use serde_json::json;
+
+ vec![
+ ControllerParamContract {
+ method: "socket.connect",
+ required: &["url", "token"],
+ optional: &[],
+ examples: vec![json!({"url":"https://example.invalid/socket", "token":"test-token"})],
+ },
+ ControllerParamContract {
+ method: "socket.disconnect",
+ required: &[],
+ optional: &[],
+ examples: vec![json!({})],
+ },
+ ControllerParamContract {
+ method: "socket.state",
+ required: &[],
+ optional: &[],
+ examples: vec![json!({})],
+ },
+ ControllerParamContract {
+ method: "socket.emit",
+ required: &["event"],
+ optional: &["data"],
+ examples: vec![
+ json!({"event":"message", "data":{"text":"hello"}}),
+ json!({"event":"message"}),
+ ],
+ },
+ ControllerParamContract {
+ method: "socket.connect_with_session",
+ required: &[],
+ optional: &[],
+ examples: vec![json!({})],
+ },
+ ]
+}
+
+#[test]
+fn socket_legacy_catalog_keeps_handler_identities() {
+ let expected: [(&str, ControllerHandler); 5] = [
+ ("socket.connect", handle_connect),
+ ("socket.disconnect", handle_disconnect),
+ ("socket.state", handle_state),
+ ("socket.emit", handle_emit),
+ ("socket.connect_with_session", handle_connect_with_session),
+ ];
+ let registered = all_registered_controllers();
+ assert_eq!(registered.len(), expected.len());
+ for ((method, handler), controller) in expected.iter().zip(&registered) {
+ assert_eq!(controller.schema.method_name(), *method);
+ assert!(std::ptr::fn_addr_eq(controller.handler, *handler));
+ }
+}
+
+#[test]
+fn connect_parser_keeps_reader_order_and_string_values() {
+ let error = parse_connect(Map::new()).err().expect("missing URL fails");
+ assert_eq!(error, "missing required param 'url'");
+
+ let params = serde_json::from_value(serde_json::json!({"url":" ", "extra":true}))
+ .expect("object params");
+ assert_eq!(
+ parse_connect(params).err().expect("missing token fails"),
+ "missing required param 'token'"
+ );
+
+ let params = serde_json::from_value(serde_json::json!({
+ "url":" https://example.invalid/socket ",
+ "token":" token ",
+ "unknown":{"ignored":true}
+ }))
+ .expect("object params");
+ let parsed = parse_connect(params).expect("string values remain permissive");
+ assert_eq!(parsed.url, " https://example.invalid/socket ");
+ assert_eq!(parsed.token, " token ");
+
+ for invalid in [
+ serde_json::json!({"url":null,"token":"token"}),
+ serde_json::json!({"url":42,"token":"token"}),
+ ] {
+ let params = serde_json::from_value(invalid).expect("object params");
+ assert_eq!(
+ parse_connect(params)
+ .err()
+ .expect("invalid URL is rejected before token"),
+ "missing required param 'url'"
+ );
+ }
+ for invalid_token in [
+ serde_json::Value::Null,
+ serde_json::json!(42),
+ serde_json::json!({"token":"nested"}),
+ ] {
+ let params = serde_json::json!({"url":"url", "token":invalid_token});
+ assert_eq!(
+ parse_connect(serde_json::from_value(params).expect("object params"))
+ .err()
+ .expect("non-string token is rejected"),
+ "missing required param 'token'"
+ );
+ }
+}
+
+#[test]
+fn emit_parser_defaults_data_to_null_and_preserves_any_json_value() {
+ let missing = serde_json::from_value(serde_json::json!({"event":" message ", "extra":1}))
+ .expect("object params");
+ let parsed = parse_emit(missing).expect("event is a string");
+ assert_eq!(parsed.event, " message ");
+ assert_eq!(parsed.data, Value::Null);
+
+ for data in [
+ serde_json::Value::Null,
+ serde_json::json!(42),
+ serde_json::json!("payload"),
+ serde_json::json!([true, null]),
+ serde_json::json!({"nested":{"value":true}}),
] {
- let schema = schemas(function);
- expect_schema_identity(&schema, "socket", function);
- expect_schema_required_inputs(&schema, required);
- if required.is_empty() {
- assert!(schema.inputs.is_empty());
- }
+ let params = serde_json::json!({"event":"message", "data":data.clone()});
+ let parsed = parse_emit(serde_json::from_value(params).expect("object params"))
+ .expect("all JSON payload values remain accepted");
+ assert_eq!(parsed.data, data);
}
- let emit = schemas("emit");
- expect_schema_identity(&emit, "socket", "emit");
- expect_schema_fields(&emit, &[("event", Some(true)), ("data", Some(false))]);
+ assert_eq!(
+ parse_emit(Map::new()).err().expect("missing event fails"),
+ "missing required param 'event'"
+ );
+}
+
+#[test]
+fn ignored_map_parser_accepts_unknown_values() {
+ let params = serde_json::from_value(serde_json::json!({
+ "anything":[null, true, {"nested":42}],
+ "other":"ignored"
+ }))
+ .expect("object params");
+ assert_eq!(parse_ignored_params(params), Ok(()));
}
// ── handlers (without manager): require_manager errors ─────────
@@ -92,6 +209,11 @@ async fn handlers_error_without_initialized_manager() {
.await
.unwrap_err();
assert!(err.contains("SocketManager not initialized"));
+
+ let err = handle_connect_with_session(DispatchCtx::process_default(), Map::new())
+ .await
+ .unwrap_err();
+ assert!(err.contains("SocketManager not initialized"));
}
/// #6111 — the lifecycle handlers and `socket_state` must publish `status` in one vocabulary.