terminal

A terminal dock panel for the engine's emulated Unix shell (shell.run — the same shell the MCP bash tool drives: POSIX builtins over the virtual filesystem, with pipes, redirects, variables, and control flow). The user types a command, it runs synchronously against the shared shell session, and the command plus its stdout/stderr/exit code become a scrollback entry. Each command runs to completion; persistent scrollback, a persistent working directory, and command history are what "terminal" means here.

The shell owns its own working directory: cd mutates the shared session's cwd and persists across shell.run calls. The prompt mirrors that cwd by reading pwd after each command, so it always shows the shell's real cwd. Scrollback is capped at ~200 entries and lives under state.terminal (the dock host state).

Exports

• M.label — the dock tab label ("Terminal").
• M.run(state, command) -> entry — run a shell command and append the result to scrollback. Returns the entry { command, cwd, stdout, stderr, exitCode, ok }.
• M.build(state) -> widget — build the Terminal tab widget tree (a Z.panel).
• M.onCallback(callbackId, data, state) -> boolean — handle a widget callback (input change, run, clear). Returns true when consumed.

The host calls M.build on markDirty and M.onCallback on widget events; there is no refresh (the panel only changes when the user runs a command).

Usage

local Terminal = require("modules.api.editor.system_tools.tabs.terminal")
local e = Terminal.run(state, "ls /zero/source")