Skip to content

armgit / mso

Public Imported from GitHub
0

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.

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.md
index 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 it
diff --git a/scripts/mso-agent-cmd-terminal.mjs b/scripts/mso-agent-cmd-terminal.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.ts
new file mode 100644
index 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);
+ });
+});