Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
import { randomUUID } from "node:crypto";
import process from "node:process";
import { C } from "./mso-agent-runtime.mjs";
import { api, apiResponse } from "./mso-agent-api.mjs";
import { persistSession } from "./mso-agent-session-ui.mjs";
import { sectionBlock } from "./mso-agent-layout.mjs";
const HEARTBEAT_MS = 20_000;
const RECONNECT_MIN_MS = 800;
const RECONNECT_MAX_MS = 5_000;
function sleep(ms, signal) {
return new Promise((resolve) => {
if (signal?.aborted) return resolve();
const timer = setTimeout(resolve, ms);
signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
});
}
function agentPrefix(label) {
const clean = String(label || "[agent]").replace(/[\u0000-\u001f\u007f]/g, "").replace(/^\[|\]$/g, "");
return clean.startsWith("agent-") ? `[${clean}]` : `[agent-${clean}]`;
}
export function formatLocalAgentEvent(message, colors = C) {
const prefix = agentPrefix(message?.senderLabel);
const kind = message?.kind === "task" ? " task" : "";
const text = String(message?.text || "").replace(/\r/g, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
const indented = text.replace(/\n/g, "\n ");
return `${colors.c}${colors.bold}${prefix}${kind}${colors.reset} ${indented}`;
}
function formatLocalAgentRelay(message, colors = C) {
const prefix = agentPrefix(message?.senderLabel);
const text = String(message?.text || "").replace(/\r/g, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
return `${colors.c}${colors.bold}${prefix} → user${colors.reset} ${text.replace(/\n/g, "\n ")}`;
}
function correlatedRelayRequest(history, message) {
if (message?.intent !== "reply" || message?.requiresUserRelay !== true || !message?.replyToMessageId || !message?.correlationId) return null;
return (Array.isArray(history) ? history : []).find((row) =>
row?.role === "local_request" && String(row.messageId || "") === String(message.replyToMessageId) &&
String(row.correlationId || "") === String(message.correlationId) && row.requiresUserRelay === true,
) || null;
}
export function localAgentPresentation(history, message, colors = C) {
const request = correlatedRelayRequest(history, message);
return request
? { mode: "relay", text: formatLocalAgentRelay(message, colors), request }
: { mode: "event", text: formatLocalAgentEvent(message, colors), request: null };
}
function relayAssistantRow(message) {
const sender = agentPrefix(message?.senderLabel);
return {
role: "assistant",
text: `${sender} replied: ${String(message?.text || "")}`,
synthetic: "local_agent_relay",
relayOfMessageId: String(message?.id || ""),
correlationId: message?.correlationId,
replyToMessageId: message?.replyToMessageId,
createdAt: message?.createdAt || new Date().toISOString(),
};
}
function historyRow(message, relayedToUser = false) {
return {
role: "agent",
text: String(message.text || ""),
senderSessionId: message.senderSessionId,
senderLabel: message.senderLabel,
kind: message.kind === "task" ? "task" : "message",
intent: message.intent || "notify",
correlationId: message.correlationId,
replyToMessageId: message.replyToMessageId,
requiresUserRelay: message.requiresUserRelay === true,
relayedToUser,
messageId: message.id,
createdAt: message.createdAt,
};
}
export class LocalAgentBridge {
constructor({ session, composer, onRequest = (_message) => {}, persist = persistSession }) {
this.session = session;
this.persist = persist;
this.composer = composer;
this.onRequest = typeof onRequest === "function" ? onRequest : null;
this.instanceId = `cli:${process.pid}:${randomUUID()}`;
this.sessionId = null;
this.state = "idle";
this.closed = false;
this.feedAbort = this.heartbeat = this.feedTask = null;
this.pending = [];
this.seen = new Set();
}
async start() {
await this.syncSession();
this.heartbeat = setInterval(() => void this.touch({ flush: false }).catch(() => undefined), HEARTBEAT_MS);
this.heartbeat.unref?.();
}
async syncSession() {
const next = String(this.session?.agentSession?.id || "").trim();
if (!next || next === this.sessionId) return;
const previous = this.sessionId;
if (previous) await this.end(previous).catch(() => undefined);
this.feedAbort?.abort();
this.feedAbort = null;
this.sessionId = next;
this.state = "ready";
this.pending = [];
this.seen = new Set(
(Array.isArray(this.session.history) ? this.session.history : [])
.filter((row) => row?.role === "agent" && row?.messageId)
.map((row) => String(row.messageId)),
);
await this.touch().catch(() => undefined);
this.state = "idle";
await this.touch().catch(() => undefined);
this.startFeed(next);
}
async setState(state) {
if (this.closed || !this.sessionId) return;
this.state = state === "busy" ? "busy" : "idle";
await this.touch().catch(() => undefined);
if (this.state === "idle" && this.pending.length) {
const rows = this.pending.splice(0);
for (const row of rows) await this.accept(row);
}
}
async touch({ flush = true } = {}) {
if (this.closed || !this.sessionId) return;
await api("/api/v1/local-agents", {
method: "POST",
body: JSON.stringify({
action: "presence",
sessionId: this.sessionId,
instanceId: this.instanceId,
state: this.state,
flush,
}),
});
}
async end(sessionId = this.sessionId) {
if (!sessionId) return;
await api("/api/v1/local-agents", {
method: "POST",
body: JSON.stringify({ action: "end", sessionId, instanceId: this.instanceId }),
});
}
startFeed(sessionId) {
const controller = new AbortController();
this.feedAbort = controller;
this.feedTask = this.feedLoop(sessionId, controller.signal).catch(() => undefined);
}
async feedLoop(sessionId, signal) {
let delay = RECONNECT_MIN_MS;
while (!this.closed && !signal.aborted && this.sessionId === sessionId) {
try {
const res = await apiResponse(`/api/v1/local-agents?stream=1&session=${encodeURIComponent(sessionId)}`, { signal });
if (!res.body) throw new Error("local agent event stream is unavailable");
await this.touch({ flush: false }).catch(() => undefined);
delay = RECONNECT_MIN_MS;
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (!signal.aborted) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const blocks = buffer.split("\n\n");
buffer = blocks.pop() || "";
for (const block of blocks) {
let event = "message", data = "";
for (const line of block.split("\n")) {
if (line.startsWith("event:")) event = line.slice(6).trim();
else if (line.startsWith("data:")) data += line.slice(5).trim();
}
if (event !== "message" || !data) continue;
const message = JSON.parse(data);
if (this.state === "busy") this.pending.push(message);
else await this.accept(message);
}
}
} catch {
if (signal.aborted || this.closed) return;
}
if (!signal.aborted && !this.closed) {
await sleep(delay, signal);
delay = Math.min(RECONNECT_MAX_MS, delay * 2);
}
}
}
async accept(message) {
if (!message?.id || this.seen.has(String(message.id))) {
if (message?.id && message?.intent !== "request") await this.ack([String(message.id)]).catch(() => undefined);
return;
}
if (String(message.targetSessionId || "") !== this.sessionId) return;
const id = String(message.id);
const alreadyStored = this.session.history.some((row) => row?.role === "agent" && String(row?.messageId || "") === id);
const presentation = localAgentPresentation(this.session.history, message);
if (!alreadyStored) {
this.session.history.push(historyRow(message, presentation.mode === "relay"));
if (presentation.mode === "relay") this.session.history.push(relayAssistantRow(message));
}
await this.persist(this.session);
this.seen.add(id);
if (!alreadyStored) this.composer.notify(sectionBlock("local", presentation.text, {
columns: this.composer?.output?.columns, detail: String(message?.senderLabel || "peer"), colors: C,
}));
// Requests are actionable work, unlike notify/reply events. Wake the owning
// interactive loop after durable persistence so it can make a correlated reply.
if (!alreadyStored && message?.intent === "request") this.onRequest?.(message);
if (message?.intent !== "request") await this.ack([id]).catch(() => undefined);
}
async ack(messageIds) {
if (!this.sessionId || !messageIds.length) return;
await api("/api/v1/local-agents", {
method: "POST",
body: JSON.stringify({ action: "ack", sessionId: this.sessionId, messageIds }),
});
}
async close({ ended = true } = {}) {
if (this.closed) return;
if (ended) await this.end().catch(() => undefined);
this.closed = true;
this.feedAbort?.abort();
if (this.heartbeat) clearInterval(this.heartbeat);
}
}