Sesiones, alertas y estado: la Status API de Miblo

El cliente#

Todo empieza con un MibloStatus. Guarda el token y el puerto y firma cada solicitud; no abre ninguna conexión hasta que se usa por primera vez.

import { MibloStatus } from '@miblo/status';

const miblo = new MibloStatus({ token, port, timeoutMs });   // all optional

from miblo_status import MibloStatus

miblo = MibloStatus(token=None, port=None, timeout=3.0)     # all optional

hello()#

Verifica el token y la versión de Miblo sin cambiar nada: { api, version } (por ejemplo { api: 2, version: "1.37.0" }: api es la API del SDK que habla el puente). Útil para comprobar la configuración cuando tu programa arranca.

const { api, version } = await miblo.hello();

info = miblo.hello()   # {"api": 2, "version": "1.37.0"}

Cómo se firma cada solicitud#

Tú no haces nada de esto, lo hacen los paquetes: antes de cada solicitud el cliente pide un desafío (GET /sdk/v1/hello con un nonce aleatorio), verifica que el puente demostró conocer el token y que las versiones coinciden (upgrade, bridge_outdated), firma la solicitud con HMAC-SHA256 (método, ruta y el SHA-256 del cuerpo) y, a la vuelta, verifica la firma de la respuesta. Un programa que toma el puerto de Miblo mientras Miblo está caído no puede demostrar el token, y el cliente no le envía nada. El paso a paso está en la referencia.

Sesiones#

Una sesión es tu programa en la lista de Miblo, junto a las sesiones de las herramientas de IA.

session()#

const job = await miblo.session({ tool, title, cwd, state, detail, pid });

job = miblo.session(tool, title=None, cwd=None, state="working", detail=None, pid=-1)

Devuelve una Session con id (sdk- + 32 caracteres hexadecimales, hecho por el puente) y state. Después solo se aceptan ids sdk-, así que un programa nunca puede cambiar ni terminar la sesión de una herramienta de IA.

Cambiar el estado#

Cada llamada devuelve { id, state }. Los modos reunión y discreto ocultan el detail, como hacen con toda sesión. Las sesiones sobreviven a una actualización del puente, pero no a un reinicio del computador.

Mensajes, enfoque y temporizador#

Las mismas acciones que miblo say, miblo focus y miblo timer, con los límites propios del Miblo Desk.

Cada una devuelve { ok, delivered, gadgets }: delivered cuenta los dispositivos que lo recibieron, y gadgets lista cada dispositivo emparejado como { id, name, ok, error? }, donde error es offline, unpaired, unsupported, rejected o busy (un Miblo Desk con un firmware anterior a 1.30.0 no se maneja y aparece como offline: actualízalo). Sin ningún Miblo emparejado, delivered es 0, que no es un error. Nada de esto se convierte en una notificación de escritorio.

Snapshot#

snapshot() lee quién está trabajando y quién te necesita, sin cambiar nada.

const { sessions, gadgets } = await miblo.snapshot();
const waiting = sessions.filter((s) => s.state === 'needs_you');

snap = miblo.snapshot()
waiting = [s for s in snap["sessions"] if s["state"] == "needs_you"]

• sessions: [{ id, name, state, tool, sdk, since }]. La sesión de una herramienta de IA aparece con un id de 8 caracteres y el nombre de la herramienta en tool ("Claude Code", "Codex"...); sdk es true para las sesiones de programas; since es cuándo entró en su estado (segundos epoch).

• gadgets: [{ id, name, online }].

• Nunca lleva un comando, un archivo, un prompt, un costo, un límite ni nada de Miblo+. Lecturas: 5 por segundo, ráfagas de 10.

Ejemplo completo#

Un vigilante de builds: ejecuta el comando, muestra su progreso, te avisa cuando falla y pone un mensaje cuando pasa.

// MIBLO_TOKEN=$(miblo sdk token) node build-watch.mjs
import { spawn } from 'node:child_process';
import { MibloStatus, MibloError } from '@miblo/status';

const miblo = new MibloStatus();
const job = await miblo.session({ tool: 'build', title: 'Site build', detail: 'npm run build' });

const code = await new Promise((resolve) => {
  spawn('npm', ['run', 'build'], { stdio: 'inherit' }).on('exit', resolve);
});

try {
  if (code === 0) {
    await job.done('passed');
    await miblo.say('Build green', { minutes: 10 });
  } else {
    await job.needsYou(`failed (exit ${code})`);
  }
} catch (e) {
  if (e instanceof MibloError && e.code === 'rate_limited') console.log(`try again in ${e.retryAfter} s`);
  else throw e;
}

# MIBLO_TOKEN=$(miblo sdk token) python3 build_watch.py
import subprocess
from miblo_status import MibloStatus, MibloError

miblo = MibloStatus()
job = miblo.session("build", title="Site build", detail="npm run build")

code = subprocess.call(["npm", "run", "build"])

try:
    if code == 0:
        job.done("passed")
        miblo.say("Build green", minutes=10)
    else:
        job.needs_you(f"failed (exit {code})")
except MibloError as e:
    if e.code == "rate_limited":
        print(f"try again in {e.retry_after} s")
    else:
        raise

Errores#

Cada error es un MibloError con:

• code: estable, nunca se renombra (lista abajo);

• status: el estado HTTP, o 0 cuando no se llegó al puente;

• field (en bad_request): el campo con el problema, como tool o detail;

• retryAfter (TS) / retry_after (Python) en rate_limited: cuántos segundos esperar.

Del lado del cliente: no_token, bridge_unavailable, timeout, unverified_answer y bridge_outdated (ver Instalación). Las páginas de la pantalla, las apps y las alertas listan sus propios códigos.

Llamadas de bajo nivel#

call(method, path, body?, opts?) hace una solicitud firmada a cualquier ruta /sdk/v1/* y devuelve el JSON de la respuesta (lanza MibloError ante un error). Un Uint8Array (TS) o bytes (Python) va como application/octet-stream. Úsalo para rutas nuevas antes de que el paquete tenga un método para ellas. Opciones: { tool, timeoutMs } (TS) / tool=, timeout= (Python); tool es el nombre de tu programa, que las rutas de pantalla y de apps necesitan.

const screen = await miblo.call('GET', '/sdk/v1/screen', undefined, { tool: 'build' });

screen = miblo.call("GET", "/sdk/v1/screen", tool="build")