Sessions, alerts and status: the Miblo status API

The client#

Everything starts with a MibloStatus. It holds the token and the port and signs every request; it opens no connection until it is first used.

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()#

Checks the token and Miblo's version without changing anything: { api, version } (for example { api: 1, version: "1.25.0" }). Handy to check the setup when your program starts.

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

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

How each request is signed#

You do none of this, the packages do: before each request the client asks for a challenge (GET /sdk/v1/hello with a random nonce), checks that the bridge proved it knows the token, signs the request with HMAC-SHA256 (method, path and the SHA-256 of the body) and, on the way back, checks the answer's signature. A program that takes Miblo's port while Miblo is down cannot prove the token, and the client sends it nothing. The step by step is in the reference.

Sessions#

A session is your program in Miblo's list, next to the AI tools' sessions.

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)

Returns a Session with id (sdk- + 32 hex characters, made by the bridge) and state. Only sdk- ids are accepted afterwards, so a program can never change or end an AI tool's session.

Changing the state#

Each call returns { id, state }. Meeting and discreet modes hide the detail, as they do for every session. Sessions survive a bridge update but not a computer restart.

Messages, focus and timer#

The same actions as miblo say, miblo focus and miblo timer, with the gadget's own limits.

Each returns { ok, delivered, gadgets }: delivered counts the gadgets that took it, and gadgets lists each paired gadget as { id, name, ok, error? }, where error is offline, unpaired, unsupported, rejected or busy. With no Miblo paired, delivered is 0, which is not an error. None of this becomes a desktop notification.

Snapshot#

snapshot() reads who is working and who needs you, without changing anything.

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 }]. An AI tool's session shows with an 8-character id and the tool's name in tool ("Claude Code", "Codex"...); sdk is true for programs' sessions; since is when it entered its state (epoch seconds).

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

• It never carries a command, a file, a prompt, a cost, a limit or anything of Miblo+. Reads: 5 a second, bursts of 10.

Complete example#

A build watcher: runs the command, shows its progress, alerts you when it fails and puts a message up when it passes.

// 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

Errors#

Every error is a MibloError with:

• code: stable, never renamed (list below);

• status: the HTTP status, or 0 when the bridge was not reached;

• field (on bad_request): the field at fault, such as tool or detail;

• retryAfter (TS) / retry_after (Python) on rate_limited: how many seconds to wait.

On the client's side: no_token, bridge_unavailable, timeout and unverified_answer (see Install).

Low-level calls#

call(method, path, body?, opts?) makes one signed request to any /sdk/v1/* route and returns the answer's JSON (throws MibloError on an error). A Uint8Array (TS) or bytes (Python) goes as application/octet-stream. Use it for new routes before the package has a method for them.

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

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