El WebSocket
Una conexión bidireccional con banderas y latido, para programas que hablan con el gateway.
El navegador y POST /task siguen una ejecución por SSE. El gateway también habla WebSocket en GET /v1/sessions/{id}/ws: una conexión persistente y bidireccional con banderas, latido y un formato de mensaje estructurado, para programas que quieren más que una petición HTTP puntual. Es un segundo transporte, no un segundo agente: misma conversación, mismo token, mismo turno de ejecución.
Quién puede conectarse
El endpoint está detrás del mismo token que el resto de la API, en dos capas, y se exigen ambas:
- La petición de upgrade lleva
Authorization: Bearer <token>. Un navegador no puede añadir esa cabecera a un handshake WebSocket, así que se acepta la cookie de sesión de la propia interfaz web, y una petición autorizada por cookie debe venir además del origen del propio servidor (otro origen recibe403). Sin ninguna credencial, el upgrade se rechaza con401. - El mensaje
authrepite el token dentro del protocolo. Hasta que tiene éxito, unqueryse responde conUNAUTHORIZED; un token incorrecto recibeUNAUTHORIZEDy la conexión sigue abierta para reintentar.
query ejecuta el mismo planificador de solo lectura que POST /plan.El sobre del mensaje
Cada mensaje, en ambos sentidos, es un objeto JSON:
{
"msg_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "query",
"flags": ["PROCESSING"],
"timestamp": "2026-09-25T12:00:00.000Z",
"payload": {}
}
| Campo | Significado |
|---|---|
msg_id | UUID v4, único por mensaje. |
type | El tipo de mensaje (abajo). |
flags | Lista de indicadores de estado (abajo). |
timestamp | ISO-8601. |
payload | Datos propios del tipo. |
Tipos de mensaje
| Tipo | Sentido | Uso |
|---|---|---|
auth | Cliente → servidor | Autenticarse con el token. |
auth_response | Servidor → cliente | El resultado de la autenticación. |
query | Cliente → servidor | Una pregunta o petición. |
query_response | Servidor → cliente | Acuse, avance parcial o respuesta final. |
heartbeat, heartbeat_ack | Ambos | Sonda de keep-alive y su respuesta. |
error | Servidor → cliente | Algo salió mal. |
notification | Servidor → cliente | Reservado, aún no se envía. |
Banderas
| Bandera | Significado |
|---|---|
AUTHENTICATED, UNAUTHORIZED | La autenticación tuvo éxito o falló. |
IDLE, BUSY | El agente espera, o ya está ejecutando algo. |
PROCESSING, PARTIAL, COMPLETED | Una consulta se está procesando, envía una línea de avance, o terminó. |
ERROR_RECOVERABLE | Un error que la conexión supera. |
Reservadas. El tipo notification y las banderas FATAL_ERROR, LOW_MEMORY, RATE_LIMITED, CACHE_HIT, CACHE_MISS y ENCRYPTED forman parte del vocabulario, pero nada las emite. Un cliente debe aceptarlas y no esperarlas.
La conversación
El acuse llega de inmediato, las líneas de avance fluyen según ocurren y el último mensaje trae el resultado. Una consulta fallida termina en un error con ERROR_RECOVERABLE.
JSON mal formado y tipos desconocidos reciben un error ERROR_RECOVERABLE. Pueden conectarse varios clientes a la vez, pero la conversación ejecuta una tarea a la vez: un segundo cliente que inicie una ejecución mientras otra corre recibe BUSY.
Lo que un cliente debe cumplir
- Solo tramas de texto con JSON. Un mensaje binario o fragmentado recibe un
ERROR_RECOVERABLEy la conexión sigue abierta. - Las tramas del cliente deben ir enmascaradas (RFC 6455); una trama sin máscara cierra la conexión con el código 1002. Cualquier librería WebSocket lo hace por ti.
- Un ping se responde con pong, y un pong del cliente también cuenta como respuesta a un latido.
- Una conexión que no envía nada durante 90 segundos se cierra, y no responder el latido también la cierra.
- El código 1000 indica que el cliente cerró; 1001 que el gateway se apaga o que el latido quedó sin respuesta, así que reconecta.
- Un
queryes de solo lectura y va atado a la conexión: si el cliente se desconecta, la consulta se cancela.
Clientes de ejemplo
El mismo cliente en los lenguajes más usados. Cada uno se autentica, hace una pregunta, responde el latido e imprime el resultado. Primero define MOTITA_TOKEN con el token del gateway.
// npm install ws
import WebSocket from "ws";
import { randomUUID } from "node:crypto";
const TOKEN = process.env.MOTITA_TOKEN; // el token del gateway: motita gateway start -token-only
const ws = new WebSocket("ws://127.0.0.1:7477/v1/sessions/default/ws", {
headers: { Authorization: "Bearer " + TOKEN },
});
const send = (type, payload) =>
ws.send(JSON.stringify({
msg_id: randomUUID(), type, flags: [],
timestamp: new Date().toISOString(), payload,
}));
ws.on("open", () => send("auth", { token: TOKEN })); // el servidor saluda primero; responde con el token
ws.on("message", (data) => {
const msg = JSON.parse(data.toString());
const has = (flag) => msg.flags.includes(flag);
if (msg.type === "auth_response" && has("AUTHENTICATED")) {
send("query", { query: "what does this project do?" }); // autenticado: ahora pregunta algo
} else if (msg.type === "auth_response" && has("UNAUTHORIZED")) {
console.error("unauthorized"); // token incorrecto (la conexión sigue abierta)
ws.close();
} else if (msg.type === "heartbeat") {
send("heartbeat_ack", {}); // responde el keep-alive en menos de 10 s
} else if (has("COMPLETED")) {
console.log(msg.payload.result); // la respuesta final
ws.close();
} else if (msg.type === "error" || has("BUSY")) {
console.error(msg.payload); // un error, o otro cliente ya está ejecutando una tarea
ws.close();
}
});// npm install ws @types/ws
import WebSocket from "ws";
import { randomUUID } from "node:crypto";
interface Envelope<P = Record<string, unknown>> {
msg_id: string;
type: string;
flags: string[];
timestamp: string;
payload: P;
}
const TOKEN = process.env.MOTITA_TOKEN ?? ""; // el token del gateway: motita gateway start -token-only
const ws = new WebSocket("ws://127.0.0.1:7477/v1/sessions/default/ws", {
headers: { Authorization: "Bearer " + TOKEN },
});
function send(type: string, payload: object): void {
const msg: Envelope<object> = {
msg_id: randomUUID(), type, flags: [],
timestamp: new Date().toISOString(), payload,
};
ws.send(JSON.stringify(msg));
}
ws.on("open", () => send("auth", { token: TOKEN })); // el servidor saluda primero; responde con el token
ws.on("message", (data) => {
const msg = JSON.parse(data.toString()) as Envelope<{ result?: string }>;
const has = (flag: string): boolean => msg.flags.includes(flag);
if (msg.type === "auth_response" && has("AUTHENTICATED")) {
send("query", { query: "what does this project do?" }); // autenticado: ahora pregunta algo
} else if (msg.type === "heartbeat") {
send("heartbeat_ack", {}); // responde el keep-alive en menos de 10 s
} else if (has("COMPLETED")) {
console.log(msg.payload.result); // la respuesta final
ws.close();
} else if (msg.type === "error" || has("BUSY") || has("UNAUTHORIZED")) {
console.error(msg.payload); // un error, o otro cliente ya está ejecutando una tarea
ws.close();
}
});# pip install websocket-client
import datetime
import json
import os
import uuid
import websocket
TOKEN = os.environ["MOTITA_TOKEN"] # el token del gateway: motita gateway start -token-only
def send(ws, type_, payload):
ws.send(json.dumps({
"msg_id": str(uuid.uuid4()), "type": type_, "flags": [],
"timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
"payload": payload,
}))
ws = websocket.create_connection(
"ws://127.0.0.1:7477/v1/sessions/default/ws",
header=["Authorization: Bearer " + TOKEN],
)
json.loads(ws.recv()) # el servidor saluda primero; responde con el token
send(ws, "auth", {"token": TOKEN})
json.loads(ws.recv()) # auth_response / AUTHENTICATED
send(ws, "query", {"query": "what does this project do?"}) # autenticado: ahora pregunta algo
while True:
msg = json.loads(ws.recv())
if msg["type"] == "heartbeat":
send(ws, "heartbeat_ack", {}) # responde el keep-alive en menos de 10 s
elif "COMPLETED" in msg["flags"]:
print(msg["payload"]["result"]) # la respuesta final
break
elif msg["type"] == "error" or "BUSY" in msg["flags"]:
raise SystemExit(msg["payload"]) # un error, o otro cliente ya está ejecutando una tarea// go get github.com/gorilla/websocket github.com/google/uuid
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
"slices"
"time"
"github.com/google/uuid"
"github.com/gorilla/websocket"
)
type Envelope struct {
MsgID string `json:"msg_id"`
Type string `json:"type"`
Flags []string `json:"flags"`
Timestamp string `json:"timestamp"`
Payload json.RawMessage `json:"payload"`
}
func send(c *websocket.Conn, typ string, payload any) {
body, _ := json.Marshal(payload)
err := c.WriteJSON(Envelope{
MsgID: uuid.NewString(), Type: typ, Flags: []string{},
Timestamp: time.Now().UTC().Format(time.RFC3339Nano), Payload: body,
})
if err != nil {
log.Fatal(err)
}
}
func main() {
token := os.Getenv("MOTITA_TOKEN") // el token del gateway: motita gateway start -token-only
header := http.Header{"Authorization": {"Bearer " + token}}
c, _, err := websocket.DefaultDialer.Dial("ws://127.0.0.1:7477/v1/sessions/default/ws", header)
if err != nil {
log.Fatal(err)
}
defer c.Close()
send(c, "auth", map[string]string{"token": token}) // el servidor saluda primero; responde con el token
for {
var msg Envelope
if err := c.ReadJSON(&msg); err != nil {
log.Fatal(err)
}
has := func(flag string) bool { return slices.Contains(msg.Flags, flag) }
switch {
case msg.Type == "auth_response" && has("AUTHENTICATED"):
send(c, "query", map[string]string{"query": "what does this project do?"}) // autenticado: ahora pregunta algo
case msg.Type == "heartbeat":
send(c, "heartbeat_ack", map[string]string{}) // responde el keep-alive en menos de 10 s
case has("COMPLETED"):
fmt.Println(string(msg.Payload)) // la respuesta final
return
case msg.Type == "error" || has("BUSY") || has("UNAUTHORIZED"):
log.Fatalf("%s", msg.Payload) // un error, o otro cliente ya está ejecutando una tarea
}
}
}// Cargo.toml: tungstenite = "0.26", serde_json = "1", uuid = { version = "1", features = ["v4"] }, chrono = "0.4"
use serde_json::{json, Value};
use tungstenite::{client::IntoClientRequest, connect, Message};
fn envelope(kind: &str, payload: Value) -> Message {
Message::text(
json!({
"msg_id": uuid::Uuid::new_v4().to_string(), "type": kind, "flags": [],
"timestamp": chrono::Utc::now().to_rfc3339(), "payload": payload,
})
.to_string(),
)
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let token = std::env::var("MOTITA_TOKEN")?; // el token del gateway: motita gateway start -token-only
let mut request = "ws://127.0.0.1:7477/v1/sessions/default/ws".into_client_request()?;
request.headers_mut().insert("Authorization", format!("Bearer {token}").parse()?);
let (mut socket, _) = connect(request)?;
socket.send(envelope("auth", json!({ "token": token })))?; // el servidor saluda primero; responde con el token
loop {
let text = socket.read()?.into_text()?;
let msg: Value = serde_json::from_str(text.as_str())?;
let has = |flag: &str| msg["flags"].as_array().is_some_and(|f| f.iter().any(|x| x == flag));
if msg["type"] == "auth_response" && has("AUTHENTICATED") {
socket.send(envelope("query", json!({ "query": "what does this project do?" })))?; // autenticado: ahora pregunta algo
} else if msg["type"] == "heartbeat" {
socket.send(envelope("heartbeat_ack", json!({})))?; // responde el keep-alive en menos de 10 s
} else if has("COMPLETED") {
println!("{}", msg["payload"]["result"].as_str().unwrap_or_default()); // la respuesta final
return Ok(());
} else if msg["type"] == "error" || has("BUSY") || has("UNAUTHORIZED") {
return Err(msg["payload"].to_string().into()); // un error, o otro cliente ya está ejecutando una tarea
}
}
}Authorization a un WebSocket, así que usa la cookie de la interfaz web y debe ser servida por el propio gateway.Fuera de loopback el gateway habla http plano, así que usa wss:// detrás de una de las opciones de Red y acceso remoto en lugar de enviar el token en claro.