Sessões, avisos e status: a API de status do Miblo

O cliente#

Tudo começa com um MibloStatus. Ele guarda o token e a porta e assina cada pedido; não abre conexão até o primeiro uso.

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

const miblo = new MibloStatus({ token, port, timeoutMs });   // todos opcionais

from miblo_status import MibloStatus

miblo = MibloStatus(token=None, port=None, timeout=3.0)     # todos opcionais

hello()#

Confere o token e a versão do Miblo, sem mudar nada: { api, version } (por exemplo { api: 1, version: "1.25.0" }). Útil para checar a instalação no início do programa.

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

info = miblo.hello()   # {"api": 1, "version": "1.25.0"}

Como cada pedido é assinado#

Você não precisa fazer nada disso, os pacotes fazem: antes de cada pedido o cliente pede um desafio (GET /sdk/v1/hello com um nonce aleatório), confere que a ponte provou conhecer o token, assina o pedido com HMAC-SHA256 (método, caminho e o SHA-256 do corpo) e, na volta, confere a assinatura da resposta. Um programa que ocupe a porta do Miblo enquanto ele está fora não consegue provar o token, e o cliente não manda nada a ele. O passo a passo está na referência.

Sessões#

Uma sessão é o seu programa na lista do Miblo, ao lado das sessões das ferramentas 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)

Devolve um objeto Session com id (sdk- + 32 hexadecimais, criado pela ponte) e state. Só ids sdk- são aceitos depois, então um programa nunca consegue mudar ou encerrar a sessão de uma ferramenta de IA.

Mudar o estado#

Cada chamada devolve { id, state }. Os modos reunião e discreto escondem o detail, como fazem com toda sessão. As sessões sobrevivem a uma atualização da ponte, mas não a um reinício do computador.

Mensagens, foco e timer#

As mesmas ações de miblo say, miblo focus e miblo timer, com os mesmos limites do aparelho.

Cada uma devolve { ok, delivered, gadgets }: delivered conta os aparelhos que aceitaram, e gadgets traz cada aparelho pareado com { id, name, ok, error? }, onde error é offline, unpaired, unsupported, rejected ou busy. Sem Miblo pareado, delivered é 0 e não é erro. Nada disso vira notificação no computador.

Snapshot#

snapshot() lê quem está trabalhando e quem precisa de você, sem mudar 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 }]. Uma sessão de ferramenta de IA aparece com um id de 8 caracteres e o nome da ferramenta em tool ("Claude Code", "Codex"...); sdk é true nas sessões de programas; since é o momento (epoch, em segundos) em que entrou no estado.

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

• Nunca traz um comando, um arquivo, um prompt, um custo, um limite ou nada do Miblo+. Leituras: 5 por segundo, em rajadas de 10.

Exemplo completo#

Um vigia de build: roda o comando, mostra o andamento, avisa quando falha e põe uma mensagem quando passa.

// 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: 'Build do site', 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('passou');
    await miblo.say('Build verde', { minutes: 10 });
  } else {
    await job.needsYou(`falhou (saída ${code})`);
  }
} catch (e) {
  if (e instanceof MibloError && e.code === 'rate_limited') console.log(`tente em ${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="Build do site", detail="npm run build")

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

try:
    if code == 0:
        job.done("passou")
        miblo.say("Build verde", minutes=10)
    else:
        job.needs_you(f"falhou (saída {code})")
except MibloError as e:
    if e.code == "rate_limited":
        print(f"tente em {e.retry_after} s")
    else:
        raise

Erros#

Todo erro é um MibloError com:

• code: estável, nunca renomeado (lista abaixo);

• status: o status HTTP, ou 0 quando a ponte não foi alcançada;

• field (em bad_request): o campo com problema, como tool ou detail;

• retryAfter (TS) / retry_after (Python) em rate_limited: quantos segundos esperar.

Do lado do cliente: no_token, bridge_unavailable, timeout e unverified_answer (veja Instalação).

Chamadas de baixo nível#

call(method, path, body?, opts?) faz um pedido assinado a qualquer rota /sdk/v1/* e devolve o JSON da resposta (lança MibloError em erro). Um Uint8Array (TS) ou bytes (Python) vai como application/octet-stream. Serve para rotas novas antes de o pacote ter um método para elas.

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

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