Motita

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:

  1. 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 recibe 403). Sin ninguna credencial, el upgrade se rechaza con 401.
  2. El mensaje auth repite el token dentro del protocolo. Hasta que tiene éxito, un query se responde con UNAUTHORIZED; un token incorrecto recibe UNAUTHORIZED y la conexión sigue abierta para reintentar.
No hay interruptor para apagar el endpoint: no expone nada que la API HTTP autenticada no exponga ya. Un 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": {}
}
CampoSignificado
msg_idUUID v4, único por mensaje.
typeEl tipo de mensaje (abajo).
flagsLista de indicadores de estado (abajo).
timestampISO-8601.
payloadDatos propios del tipo.

Tipos de mensaje

TipoSentidoUso
authCliente → servidorAutenticarse con el token.
auth_responseServidor → clienteEl resultado de la autenticación.
queryCliente → servidorUna pregunta o petición.
query_responseServidor → clienteAcuse, avance parcial o respuesta final.
heartbeat, heartbeat_ackAmbosSonda de keep-alive y su respuesta.
errorServidor → clienteAlgo salió mal.
notificationServidor → clienteReservado, aún no se envía.

Banderas

BanderaSignificado
AUTHENTICATED, UNAUTHORIZEDLa autenticación tuvo éxito o falló.
IDLE, BUSYEl agente espera, o ya está ejecutando algo.
PROCESSING, PARTIAL, COMPLETEDUna consulta se está procesando, envía una línea de avance, o terminó.
ERROR_RECOVERABLEUn 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

ClienteGateway/v1/sessions/{id}/wsauth_response [IDLE]auth { token }auth_response [AUTHENTICATED, IDLE]query { query }query_response [PROCESSING]query_response [PARTIAL, PROCESSING]query_response [COMPLETED] { result }cada 30 s: heartbeat, que se responde con heartbeat_ack en 10 s

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

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
        }
    }
}
Una página del navegador no puede añadir la cabecera 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.

Profundizar