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
feat(tui): /terminal hands the real terminal to a shell or a one-shot command (#224)
Abdurrahman Fakhrul98b22531c3ed
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 2c4998cf..82d36c31 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -8,13 +8,14 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh**Added**+- `tui` /terminal hands the real terminal to a shell or a one-shot command- `skills` add mso-agent-fleet for Orca + OpenCode fan-out (#217)- `ci` three security scanners that actually run, and lanes that fail closed (#210)- `tui` the panel is the default, and the banner lives in the transcript (#209)**Fixed**-- `tui` let the composer reservation shrink, so Esc really closes the menu+- `tui` let the composer reservation shrink, so Esc really closes the menu (#223)- `tui` stop the panel erasing the slash menu, and keep the banner ASCII art (#221)- `security` validate the model half of a provider/model ref- `security` read only .message from a caught error, never stringify itdiff --git a/scripts/mso-agent-cmd-terminal.mjs b/scripts/mso-agent-cmd-terminal.mjsnew file mode 100644index 00000000..7c2769a6--- /dev/null+++ b/scripts/mso-agent-cmd-terminal.mjs@@ -0,0 +1,63 @@+import { spawnSync } from "node:child_process";+import process from "node:process";+import { withPanelSuspended } from "./mso-agent-turn-print.mjs";+import { createPrinter } from "./mso-agent-print.mjs";++/**+ * Suspends the alternate-screen panel and yields the terminal to a child shell process.+ * When called with no arguments, spawns an interactive user shell ($SHELL or /bin/sh).+ * When called with command arguments, runs the command once via -c and reports non-zero exit status.+ *+ * @param {object} ctx - Execution context containing session and optional printer.+ * @param {string[]} [args] - Arguments passed after /terminal.+ * @param {object} [options] - Optional overrides for spawn, env, and shell (used in tests).+ * @returns {Promise<string>} Slash command outcome ("handled").+ */+export async function handleTerminalCommand(ctx, args = [], options = {}) {+ const session = ctx?.session;+ const loop = ctx?.screenLoop || session?.screenLoop;+ const printer = ctx?.printer || createPrinter(ctx);++ const env = options.env || ctx?.env || session?.env || process.env;+ const shell = options.shell || ctx?.shell || session?.shell || env.SHELL || "/bin/sh";+ const spawn = options.spawn || ctx?.spawn || session?.spawn || spawnSync;++ const cmdArgs = Array.isArray(args) ? args : [args].filter(Boolean);+ const hasCommand = cmdArgs.length > 0;+ // Interactive shells require an empty argv array, while commands run through shell -c.+ const argv = hasCommand ? ["-c", cmdArgs.join(" ")] : [];++ let result = null;+ let spawnError = null;++ // withPanelSuspended ensures the alternate screen is exited and mouse reporting disabled+ // before the child process takes over stdio, and guarantees resume even if spawn throws.+ await withPanelSuspended(loop, () => {+ try {+ result = spawn(shell, argv, { stdio: "inherit", env });+ } catch (err) {+ spawnError = err;+ }+ });++ // Spawn failures (such as missing shell executable) are reported to the transcript.+ if (spawnError) {+ const message = spawnError instanceof Error ? spawnError.message : String(spawnError);+ printer.print(`terminal: ${message}`);+ return "handled";+ }++ if (result?.error) {+ const message = result.error instanceof Error ? result.error.message : String(result.error);+ printer.print(`terminal: ${message}`);+ return "handled";+ }++ // Non-zero exit status is reported to the transcript so failures are not swallowed.+ const status = result?.status ?? (result?.signal ? 1 : 0);+ if (status !== 0) {+ printer.print(`terminal: exit ${status}`);+ }++ return "handled";+}diff --git a/scripts/mso-agent-commands.mjs b/scripts/mso-agent-commands.mjsindex 80024ee7..eccf06c1 100644--- a/scripts/mso-agent-commands.mjs+++ b/scripts/mso-agent-commands.mjs@@ -18,6 +18,7 @@ import {import { handleInspectCommand } from "./mso-agent-cmd-inspect.mjs";import { handleSessionCommand } from "./mso-agent-cmd-session.mjs";import { handleJobsCommand } from "./mso-agent-jobs.mjs";+import { handleTerminalCommand } from "./mso-agent-cmd-terminal.mjs";import { createPrinter } from "./mso-agent-print.mjs";export { SHARE_UNAVAILABLE_MESSAGE, buildExportArgv };@@ -103,6 +104,7 @@ export async function handleSlash(rl, line, session, { runTurn, runSubagent }) {if (parityOutcome !== null) return parityOutcome;if (cmd === "/jobs") return handleJobsCommand(ctx, args);+ if (cmd === "/terminal" || cmd === "/term") return handleTerminalCommand(ctx, args);switch (cmd) {case "/help":diff --git a/scripts/mso-agent-help.mjs b/scripts/mso-agent-help.mjsindex 06bc5f4f..472591d6 100644--- a/scripts/mso-agent-help.mjs+++ b/scripts/mso-agent-help.mjs@@ -36,6 +36,7 @@ export const HELP_LINES = [" /delegate <target> <job> correlated local task; else remote A2A peer"," /spawn [--name N] [--scope S] <job> run foreground isolated subagent in this session"," /jobs [id|cancel <id>] list background subagent jobs, inspect, or cancel",+ " /terminal [cmd] open shell or run command in real terminal"," /inbox show native local agent messages for this session"," /skills [query] browse available slash skills"," /skill <id> [prompt] select exact skill id (ambiguity escape hatch)",diff --git a/scripts/mso-agent-terminal-command.test.ts b/scripts/mso-agent-terminal-command.test.tsnew file mode 100644index 00000000..9f1cd980--- /dev/null+++ b/scripts/mso-agent-terminal-command.test.ts@@ -0,0 +1,194 @@+import { describe, expect, it, vi } from "vitest";+import { handleTerminalCommand } from "./mso-agent-cmd-terminal.mjs";+import { handleSlash } from "./mso-agent-commands.mjs";++function createMockLoop() {+ let suspended = false;+ const suspend = vi.fn(() => {+ suspended = true;+ });+ const resume = vi.fn(() => {+ suspended = false;+ });+ return {+ active: true,+ suspend,+ resume,+ isSuspended: () => suspended,+ };+}++describe("/terminal slash command", () => {+ it("1. suspends panel, spawns $SHELL, resumes, and adds no exit line on exit code 0", async () => {+ const loop = createMockLoop();+ const session = { screenLoop: loop };+ const printer = { print: vi.fn() };+ const spawn = vi.fn(() => ({ status: 0, signal: null }));++ const outcome = await handleTerminalCommand(+ { session, printer },+ [],+ { spawn, env: { SHELL: "/bin/zsh" } },+ );++ expect(outcome).toBe("handled");+ // Verifies that panel alternate screen was released and resumed.+ expect(loop.suspend).toHaveBeenCalledTimes(1);+ expect(loop.resume).toHaveBeenCalledTimes(1);+ expect(loop.isSuspended()).toBe(false);++ // Verifies that bare /terminal spawns $SHELL with an empty argv array.+ expect(spawn).toHaveBeenCalledTimes(1);+ expect(spawn).toHaveBeenCalledWith("/bin/zsh", [], {+ stdio: "inherit",+ env: { SHELL: "/bin/zsh" },+ });++ // Clean exit in interactive shell adds no noise to transcript.+ expect(printer.print).not.toHaveBeenCalled();+ });++ it("2. /terminal git status spawns with -c and exact argv, and adds one transcript line with exit code on non-zero", async () => {+ const loop = createMockLoop();+ const session = { screenLoop: loop };+ const printer = { print: vi.fn() };+ const spawn = vi.fn(() => ({ status: 128, signal: null }));++ const outcome = await handleTerminalCommand(+ { session, printer },+ ["git", "status"],+ { spawn, env: { SHELL: "/bin/bash" } },+ );++ expect(outcome).toBe("handled");+ expect(loop.suspend).toHaveBeenCalledTimes(1);+ expect(loop.resume).toHaveBeenCalledTimes(1);++ // Verifies command is passed through shell -c with the joined command string.+ expect(spawn).toHaveBeenCalledWith(+ "/bin/bash",+ ["-c", "git status"],+ expect.objectContaining({ stdio: "inherit" }),+ );++ // Non-zero exit code must be reported to the transcript.+ expect(printer.print).toHaveBeenCalledTimes(1);+ expect(printer.print).toHaveBeenCalledWith(expect.stringContaining("128"));+ });++ it("3. a spawn failure (throw or error field) reports one line and still resumes, never leaving the panel suspended", async () => {+ // Case A: spawn throws an exception (e.g. process error).+ const loopThrow = createMockLoop();+ const sessionThrow = { screenLoop: loopThrow };+ const printerThrow = { print: vi.fn() };+ const spawnThrow = vi.fn(() => {+ throw new Error("spawn failed: permission denied");+ });++ await handleTerminalCommand(+ { session: sessionThrow, printer: printerThrow },+ [],+ { spawn: spawnThrow },+ );++ expect(loopThrow.suspend).toHaveBeenCalledTimes(1);+ expect(loopThrow.resume).toHaveBeenCalledTimes(1);+ expect(loopThrow.isSuspended()).toBe(false);+ expect(printerThrow.print).toHaveBeenCalledTimes(1);+ expect(printerThrow.print).toHaveBeenCalledWith(+ expect.stringContaining("permission denied"),+ );++ // Case B: spawn returns an object containing an error property.+ const loopError = createMockLoop();+ const sessionError = { screenLoop: loopError };+ const printerError = { print: vi.fn() };+ const spawnError = vi.fn(() => ({+ error: new Error("spawn ENOENT"),+ status: null,+ }));++ await handleTerminalCommand(+ { session: sessionError, printer: printerError },+ [],+ { spawn: spawnError },+ );++ expect(loopError.suspend).toHaveBeenCalledTimes(1);+ expect(loopError.resume).toHaveBeenCalledTimes(1);+ expect(loopError.isSuspended()).toBe(false);+ expect(printerError.print).toHaveBeenCalledTimes(1);+ expect(printerError.print).toHaveBeenCalledWith(+ expect.stringContaining("spawn ENOENT"),+ );+ });++ it("4. inline mode (no panel) runs the command without any suspend call", async () => {+ // When screenLoop is absent or inactive, no suspend/resume methods exist to call.+ const loop = {+ active: false,+ suspend: vi.fn(),+ resume: vi.fn(),+ };+ const session = { screenLoop: loop };+ const printer = { print: vi.fn() };+ const spawn = vi.fn(() => ({ status: 0 }));++ const outcome = await handleTerminalCommand(+ { session, printer },+ ["git", "status"],+ { spawn },+ );++ expect(outcome).toBe("handled");+ expect(loop.suspend).not.toHaveBeenCalled();+ expect(loop.resume).not.toHaveBeenCalled();+ expect(spawn).toHaveBeenCalledTimes(1);+ });++ it("5. the argv array never contains a joined string when the command had no spaces to preserve; assert the exact argv shape for a simple command", async () => {+ let capturedArgv: string[] = [];+ const spawn = vi.fn((_shell: string, argv: string[]) => {+ capturedArgv = argv;+ return { status: 0 };+ });++ // Test a single-word command with no spaces.+ await handleTerminalCommand(+ {},+ ["status"],+ { spawn },+ );++ expect(capturedArgv).toEqual(["-c", "status"]);+ // Neither element should contain whitespace or accidental concatenation.+ expect(capturedArgv[0]).toBe("-c");+ expect(capturedArgv[1]).toBe("status");+ expect(capturedArgv[1]).not.toContain(" ");+ });++ it("dispatches through handleSlash router for /terminal and alias /term", async () => {+ const loop = createMockLoop();+ const spawn = vi.fn(() => ({ status: 0 }));+ const session = {+ screenLoop: loop,+ spawn,+ state: { skills: { skills: [] } },+ history: [],+ printSink: vi.fn(),+ };++ const outcome = await handleSlash(+ null,+ "/terminal",+ session,+ {+ runTurn: async () => {},+ runSubagent: async () => {},+ },+ );++ expect(outcome).toBe("handled");+ expect(spawn).toHaveBeenCalledTimes(1);+ });+});