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 { listLocalAgents } from "./local-agent-directory";
import {
findLocalAgentReply,
getLocalAgentSentMessage,
listLocalAgentInbox,
} from "./local-agent-mailbox";
import { subscribeLocalAgentMessages } from "./local-agent-events";
import type { LocalAgentMessageView } from "./local-agent-types";
export const MAX_LOCAL_AGENT_INBOX_WAIT_MS = 20_000;
export async function waitForLocalAgentInbox(input: {
principal: string;
sessionId: string;
includeRead?: boolean;
limit?: number;
waitMs?: number;
signal?:AbortSignal;
authorize?:()=>Promise<void>;
}): Promise<LocalAgentMessageView[]> {
const limit = Math.max(1, Math.min(200, Math.trunc(input.limit ?? 100)));
const waitMs = Number.isFinite(input.waitMs)
? Math.max(0, Math.min(MAX_LOCAL_AGENT_INBOX_WAIT_MS, Math.trunc(input.waitMs ?? 0)))
: 0;
const read = async () => {
input.signal?.throwIfAborted(); await input.authorize?.();
const messages=await listLocalAgentInbox(input.principal,input.sessionId,{includeRead:input.includeRead===true,limit});
input.signal?.throwIfAborted(); await input.authorize?.();
return messages;
};
const initial = await read();
if (initial.length || waitMs === 0) return initial;
let wake = () => {};
const signalled = new Promise<void>((resolve) => { wake = resolve; });
const unsubscribe = subscribeLocalAgentMessages(input.sessionId, () => wake());
let timer: ReturnType<typeof setTimeout> | undefined;
let authorizationTimer: ReturnType<typeof setInterval> | undefined;
let abort=()=>{};
try {
// Close the read→subscribe race; durable mailbox remains authoritative.
const afterSubscribe = await read();
if (afterSubscribe.length) return afterSubscribe;
const timedOut = new Promise<void>((resolve) => { timer = setTimeout(resolve, waitMs); });
const revoked=new Promise<never>((_resolve,reject)=>{
abort=()=>reject(input.signal?.reason ?? new Error("Local-agent wait aborted"));
input.signal?.addEventListener("abort",abort,{once:true});
if (input.signal?.aborted) abort();
let checking=false;
if(input.authorize) authorizationTimer=setInterval(()=>{
if(checking) return;
checking=true; void input.authorize!().catch(reject).finally(()=>{checking=false;});
},100);
});
await Promise.race([signalled, timedOut,revoked]);
return await read();
} finally {
if (timer) clearTimeout(timer);
if (authorizationTimer) clearInterval(authorizationTimer);
input.signal?.removeEventListener("abort",abort);
unsubscribe();
}
}
export async function waitForLocalAgentReply(input: {
principal: string;
senderSessionId: string;
requestMessageId: string;
timeoutMs?: number;
signal?:AbortSignal;
authorize?:()=>Promise<void>;
}) {
input.signal?.throwIfAborted(); await input.authorize?.();
const request = await getLocalAgentSentMessage(
input.principal,
input.senderSessionId,
input.requestMessageId,
);
if (!request || request.intent !== "request" || !request.correlationId)
throw new Error("correlated local agent request not found for this session");
const timeoutMs = Math.max(0, Math.min(30_000, Math.trunc(input.timeoutMs ?? 5_000)));
const startedAt = Date.now();
while (true) {
input.signal?.throwIfAborted(); await input.authorize?.();
const reply = await findLocalAgentReply(input.principal, input.senderSessionId, request.id);
const target = (await listLocalAgents(input.principal, { includeOffline: true }))
.find((row) => row.id === request.targetSessionId) ?? null;
const elapsedMs = Date.now() - startedAt;
input.signal?.throwIfAborted(); await input.authorize?.();
if (reply) return { state: "replied" as const, elapsedMs, request, reply, target };
if (target && !target.actionable && ["offline", "ended"].includes(target.status))
return { state: "target_offline" as const, elapsedMs, request, reply: null, target };
if (elapsedMs >= timeoutMs) {
const state = target?.actionable === false
? "consumer_absent" as const
: "timeout" as const;
return { state, elapsedMs, request, reply: null, target };
}
await new Promise((resolve) =>
setTimeout(resolve, Math.min(100, Math.max(1, timeoutMs - elapsedMs))));
}
}