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 process from "node:process";
import { canonicalAgentApproval } from "../lib/agent/approval.mjs";
import { requestExactToolApproval } from "./mso-agent-approval-ui.mjs";
import { AgentMutationUncertainError, isAgentApiError, isRecoverableInteractionError, recoverableErrorLines, recoverableHistoryRow, recoverableTurnState } from "./mso-agent-errors.mjs";
import { printSection, sectionDivider } from "./mso-agent-layout.mjs";
import { AgentActivity } from "./mso-agent-activity.mjs";
import { beginSkillInvocation, endSkillInvocation } from "./mso-agent-skills.mjs";
import { isAbortError } from "./mso-agent-interrupt.mjs";
import { approvesTool } from "./mso-agent-permissions.mjs";
import { api, C, streamTurn } from "./mso-agent-runtime.mjs";
import { completedReceipt } from "./mso-agent-ui.mjs";
import { compactConsumedReadToolResults } from "./mso-agent-context.mjs";
import { addUsage } from "./mso-agent-status.mjs";
import { oneShotApproves } from "./mso-agent-oneshot.mjs";
import { reasoningLine } from "./mso-agent-reasoning.mjs";
import { parseEditResult, printEditDiff } from "./mso-agent-edit-diff.mjs";
import { parseTodoCall, printTodoBlock, rememberTodos } from "./mso-agent-todos.mjs";
import { turnActivity, turnPrinter } from "./mso-agent-turn-print.mjs";
function lazyAssistantOutput(session, options = {}) {
if (options.quiet) return null;
// The alternate-screen panel installs a sink so streamed text lands in the viewport buffer
// instead of being appended to scrollback that is not visible.
if (session?.streamSink) return session.streamSink;
let opened = false;
return {
write(value) {
if (!opened) {
opened = true;
options.activity?.clear();
printSection("assistant", { detail: `@${session?.agentSession?.name || "agent"}`, colors: C });
}
return process.stdout.write(String(value ?? ""));
},
};
}
/** Rounds (stream → tools → stream) one turn may run. The historical cap was a
* hard-coded 10; now `OS_AGENT_MAX_ROUNDS` (default 1000 = no practical cap). */
export function agentRoundLimit() {
const configured = Number(process.env.OS_AGENT_MAX_ROUNDS);
return Number.isFinite(configured) && configured > 0 ? Math.trunc(configured) : 1000;
}
export async function executeTool(rl, tool, call, agentSession, permission = "ask", signal = undefined, onInterrupt = null, options = {}) {
if (!tool) return { ok: false, result: `unknown tool requested by model: ${call.name}` };
const needsApprovalDigest = tool.scope !== "read";
let approval = null;
if (needsApprovalDigest) {
try { approval = canonicalAgentApproval(tool.name, call.input || {}); }
catch (error) { return { ok: false, result: `cannot safely approve tool call: ${error instanceof Error ? error.message : String(error)}` }; }
}
let approved = options.approvalScope ? oneShotApproves(options.approvalScope, tool.scope) : approvesTool(permission, tool.scope);
if (!approved) {
if (options.approvalScope) return { ok: false, result: "denied by user" };
const approvalState = options.approvalState || null;
if (approvalState) approvalState.pendingApproval = { tool: tool.name, scope: tool.scope, digest: approval?.digest || null, createdAt: new Date().toISOString() };
try {
const screenLoop = options.screenLoop || approvalState?.screenLoop;
approved = await requestExactToolApproval(rl, { tool, input: call.input || {}, approval, onCancel: onInterrupt, signal, colors: C, screenLoop });
if (approvalState) approvalState.pendingApproval = null;
} catch (error) {
if (signal?.aborted || isAbortError(error)) { if (approvalState) approvalState.pendingApproval = null; }
throw error;
}
} else if (needsApprovalDigest && !options.quiet && !options.approvalScope) {
if (options.activity) options.activity.label(tool);
else (options.print || console.log)(`${C.c}${C.bold}[${tool.scope}]${C.reset} ${tool.name}`);
}
if (!approved) return { ok: false, result: "denied by user" };
if (!options.quiet) {
if (options.activity) options.activity.toolStart(tool);
else process.stdout.write(`${C.dim} ↳ ${tool.name}…${C.reset}`);
}
const request = options.apiRequest || api;
try {
const input = approval ? approval.payload.input : (call.input || {});
const out = await request("/api/v1/agent-tools", {
method: "POST",
body: JSON.stringify({
name: tool.name,
input,
sessionId: agentSession.id,
...(tool.scope === "read" ? {} : { approved: true, approvalDigest: approval.digest }),
}),
signal,
});
if (!options.quiet) {
if (options.activity) options.activity.toolEnd(tool, true);
else process.stdout.write(`\r${C.c} ✓ ${tool.name}${C.reset}\n`);
if (tool.name === "fs_edit") printEditDiff(parseEditResult(out.result), { colors: C, activity: options.activity });
if (tool.name === "todo_write") printTodoBlock(rememberTodos(parseTodoCall(input, out.result)), { colors: C, activity: options.activity });
}
if (!out.ok) return { ok: false, result: out.result || "tool failed" };
return { ok: true, result: String(out.result ?? "ok") };
} catch (error) {
if (signal?.aborted || isAbortError(error)) throw error;
if (!options.quiet) {
if (options.activity) options.activity.toolEnd(tool, false);
else process.stdout.write(`\r${C.err} ✗ ${tool.name}${C.reset}\n`);
}
if (tool.scope !== "read" && isAgentApiError(error)) throw new AgentMutationUncertainError(tool.name, error);
return { ok: false, result: (error instanceof Error ? error.message : String(error)).slice(0, 2000) };
}
}
export async function agentRound(rl, session, skillContext = null, signal = undefined, onInterrupt = null, options = {}) {
const startedAt = Date.now();
const historyCheckpoint = Math.max(0, session.history.length - 1);
const calls = [];
let finalText = "", rounds = 0;
const agentName = session?.agentSession?.name || "agent";
const activity = options.quiet ? null : turnActivity({ session, options, Activity: AgentActivity, fallbackColors: C });
const roundLimit = agentRoundLimit();
beginSkillInvocation(session, skillContext, C);
const print = options.print || turnPrinter(session);
const turnStream = options.streamTurn || streamTurn;
const toolExecutor = options.executeTool || executeTool;
const toolOptions = { ...options, activity, print, screenLoop: options.screenLoop || session?.screenLoop };
let workSectionPrinted = false;
try {
for (let turn = 0; turn < roundLimit; turn++) {
rounds = turn + 1;
// Live row while the first token is in flight: a provider wait reads as work.
activity?.waiting("thinking");
const scoped = options.toolFilter ? session.state.tools.filter(options.toolFilter) : session.state.tools;
const result = await turnStream(
session.history, scoped, session.agentSession, skillContext, signal, session.state.modelMeta?.context, lazyAssistantOutput(session, toolOptions),
);
// The current model round has consumed all prior read-tool payloads that were
// still inside its projected context. Persist only bounded replay envelopes
// afterwards; write/exec receipts remain untouched.
compactConsumedReadToolResults(session.history, session.state.tools);
if (skillContext) session.lastInvokedSkill = skillContext;
finalText = result.text;
session.usage = addUsage(session.usage, result.usage);
session.lastRouting = result.routing || null;
session.lastElapsedMs = Date.now() - startedAt;
if (!options.quiet && session.showReasoning !== false) {
const line = reasoningLine(result.usage);
if (line) print(`${C.dim}${line}${C.reset}`);
}
session.history.push({ role: "assistant", text: result.text, toolUses: result.toolUses });
if (!result.toolUses.length) {
activity?.finish(completedReceipt(calls, session.lastElapsedMs));
return { text: finalText, calls, rounds, usage: session.usage, elapsedMs: session.lastElapsedMs };
}
activity?.clear();
// One `Agent work` section per turn; the live row below carries tool progress.
if (!options.quiet && !workSectionPrinted) {
workSectionPrinted = true;
printSection("work", { detail: `@${agentName}`, colors: C });
}
activity?.setToolTotal(result.toolUses.length);
const results = [];
for (const call of result.toolUses) {
const tool = session.state.tools.find((row) => row.name === call.name);
const outcome = await toolExecutor(rl, tool, call, session.agentSession, session.permission, signal, onInterrupt, { ...toolOptions, approvalState: options.approvalState || session });
calls.push({ name: call.name, scope: tool?.scope || "unknown", ok: outcome.ok });
results.push({ id: call.id, content: outcome.result, isError: !outcome.ok });
}
session.history.push({ role: "tool", results });
}
activity?.finish(completedReceipt(calls, session.lastElapsedMs));
if (!options.quiet) print(`${C.warn}turn limit reached; ask to continue if needed.${C.reset}`);
return { text: finalText, calls, rounds, usage: session.usage, elapsedMs: session.lastElapsedMs, turnLimitReached: true };
} catch (error) {
if (signal?.aborted || isAbortError(error)) session.history.splice(historyCheckpoint);
else if (error && typeof error === "object" && !error.turnJournal) error.turnJournal = { calls: [...calls] };
throw error;
} finally {
activity?.stop();
endSkillInvocation(session, skillContext);
}
}
export function renderInteractionFailure(error, session, journal = {}, colors = C, print = console.log) {
const state = recoverableTurnState(error, journal);
print(sectionDivider("error", { detail: `@${session?.agentSession?.name || "agent"}`, colors }));
for (const line of recoverableErrorLines(state)) print(`${colors.err || ""}${line}${colors.reset || ""}`);
return state;
}
// Bookkeeping write persists turn lifecycle markers without failing the round if offline.
async function persistTurnActive(session, turnStartedAt) {
if (!session?.agentSession?.id) return;
if (turnStartedAt) session.agentSession.turnStartedAt = turnStartedAt;
else delete session.agentSession.turnStartedAt;
try {
const body = { action: "update", id: session.agentSession.id, history: session.history, cwd: process.cwd(), turnStartedAt };
if (session.titleOverride) body.title = session.titleOverride;
const out = await api("/api/v1/agent-sessions", { method: "POST", body: JSON.stringify(body) });
if (out?.session) session.agentSession = { ...session.agentSession, ...out.session };
} catch { /* Bookkeeping write failure should never abort an interactive round. */ }
}
export async function runInteractiveRound(rl, session, skillContext, interrupts, localBridge = null, roundOptions = {}) {
const signal = interrupts.beginTurn();
await localBridge?.setState("busy");
let roundResult = null;
const print = turnPrinter(session);
// Persist turn start timestamp so session list reflects active work immediately.
await persistTurnActive(session, new Date().toISOString());
try {
roundResult = await agentRound(rl, session, skillContext, signal, () => interrupts.interruptCurrent(), { print, ...roundOptions });
} catch (error) {
if (signal.aborted || isAbortError(error)) print(`${C.dim}turn interrupted.${C.reset}`);
else {
const journal = error?.turnJournal || { calls: roundResult?.calls || [] };
const state = renderInteractionFailure(error, session, journal, C, print);
if (isRecoverableInteractionError(error)) session.history.push(recoverableHistoryRow(state));
}
} finally {
// Clear turn marker in finally block so aborted or crashed turns never stick in working state.
await persistTurnActive(session, null);
interrupts.endTurn(signal);
await localBridge?.setState("idle");
}
}