Bash Refactor Requirements
Problem
The current uvilo-shell MCP server (Python) implements a blocking permission system that contradicts the environment trust model stated in FORGE.md (“Treat environment as trusted unless an action is explicitly destructive or irreversible”). In practice, agents almost always override or bypass the ⚠️ PERMISSION REQUIRED prompt, making it security theater that wastes tokens and adds latency with every round-trip. The permission system is also porous — always-allowed commands like sed and awk can execute arbitrary shell commands, so it provides no real security boundary.
This project will rewrite the tool as forge-bash in TypeScript, removing the blocking permission system entirely and replacing it with a non-blocking audit log, while preserving the core execution and LLM-presentation layers. It will also evaluate and lay groundwork for migrating all Forge MCP tools from Python to TypeScript.
Background
The uvilo-shell tool was built early in Uvilo OS with a two-layer architecture: Layer 1 (Unix execution) and Layer 2 (LLM output formatting). The permission layer was added as a precaution but has proven to add more friction than protection given the trusted-environment model and the agent’s behavioral tendency to always seek permission grants. The environment can be quickly restored from a Railway image + the uvilo-os repo, making recovery from destructive operations inexpensive.
Prerequisites
- The LibreChat environment has migrated to a debian-slim base image (no longer Alpine).
- There is no distinction between dev and production environments in the LibreChat deployment. It is a living project that is used as it is being developed.
Requirements
R1: Remove blocking permission system
The blocking permission system — including the pre-execution permission scan, the ⚠️ PERMISSION REQUIRED output, the grant parameter, and the session config file (/tmp/uvilo-shell-session.yaml) — must be removed from forge-bash. Commands must execute immediately without user approval. This eliminates the token overhead and latency of the permission round-trip.
Note: The permanent config files (shell-permissions.yaml) are NOT removed — uvilo-shell still requires them during the coexistence period. They will be trashed when uvilo-shell is retired (out of scope).
R2: Non-blocking audit log
Every executed command must be logged to a persistent audit file with timestamp, the full command string, and the exit code. This provides post-hoc visibility into what the agent executed without blocking or delaying execution.
R3: Always block rm to enforce uvilo-trash
The rm command must be unconditionally blocked. This forces the agent to use the uvilo-trash MCP tool instead, which moves files to .trash/ with a timestamp suffix rather than permanently deleting them. This is a single, targeted guard — not a general permission system.
R4: Rewrite in TypeScript
The tool must be rewritten in TypeScript rather than Python. This aligns with the goal of migrating all Forge MCP tools to a single language, reducing cognitive overhead and dependency management across the codebase.
R5: New tool name: forge-bash
The new tool must be named forge-bash (both as the MCP server name and the tool name) to allow staged migration. Both uvilo-shell (Python) and forge-bash (TypeScript) can coexist during the transition period, and the old tool can be retired once the new one is validated.
R6: Preserve core execution and LLM-presentation layers
The two-layer architecture must be preserved. Layer 1 (Unix execution) must support the same shell operators (|, &&, ||, ;) and pass commands verbatim to the shell. Layer 2 (LLM presentation) must preserve: binary output detection (null bytes / high control-char ratio), overflow truncation (200 lines / 50 KB with full output written to /tmp/forge-bash/), stderr attachment on failure, and the [exit:N | Xms] metadata footer.
R7: Evaluate TypeScript for all Forge MCP tools
The project must evaluate the feasibility and trade-offs of migrating all Forge MCP tools (currently Python) to TypeScript. This evaluation should cover: available TypeScript MCP SDK support, dependency implications, build/packaging approach, and any tool-specific migration concerns.
R8: Create Write_Typescript skill
A new skill called Write_Typescript must be created. This skill captures the conventions, rules, and patterns for writing TypeScript code in the Uvilo OS context — ensuring consistency across the codebase as tools are migrated and new ones are created.
R9: Update FORGE.md and related references
All references to the removed permission system must be cleaned up: the PERMISSION RULE in FORGE.md, the /end-session step that checks for uncommitted shell-permissions.yaml changes, and any agent instructions or tool docstrings that reference the grant parameter or permission protocol.
R10: Activate forge-bash via Update Agents
The /update-agents command must be run to sync the master agent config to all LibreChat variants, making forge-bash the active shell tool in the running instance. Without this step, forge-bash is registered in librechat.yaml and the master agent instructions reference it, but the running agents still use the old uvilo-shell instructions.
Success Criteria
| # | Criterion | Measured by |
|---|---|---|
| V1 | Commands execute without any permission prompt or grant parameter | No ⚠️ PERMISSION REQUIRED output appears; no grant parameter in tool schema |
| V2 | Every executed command is recorded in an audit log with timestamp, command, and exit code | Audit log file exists and contains entries matching executed commands |
| V3 | rm is blocked and the agent receives a clear message directing it to use uvilo-trash | Running rm returns a blocked message; uvilo-trash works as alternative |
| V4 | The tool is written in TypeScript and runs as forge-bash | Source files are .ts; MCP server registers as forge-bash |
| V5 | Both uvilo-shell and forge-bash can coexist | Both tools appear in MCP config; no conflicts |
| V6 | Shell operators, overflow handling, binary guard, stderr attachment, and metadata footer work identically to uvilo-shell | Functional parity on all Layer 1 and Layer 2 features |
| V7 | TypeScript migration evaluation is documented | Written evaluation covers SDK, dependencies, packaging, and per-tool concerns |
| V8 | Write_Typescript skill exists with conventions and rules | Skill is in Forge/Skills/Write_Typescript/SKILL.md and follows the skill format |
| V9 | No stale references to permissions remain in FORGE.md, agent instructions, or tool docstrings | Grep for “PERMISSION REQUIRED”, “grant”, “shell-permissions” returns no hits outside the project docs |
| V10 | forge-bash is the active shell tool in the running LibreChat instance | /update-agents has been run to sync the master agent config to all variants |
Out Of Scope
- Retiring
uvilo-shell(that happens after validation in a separate step) - Rewriting other MCP tools in TypeScript (this project only creates the evaluation and the skill)
- Changes to
uvilo-trashMCP server - Changes to the Railway deployment image or Docker configuration
- Modifying the agent’s behavioral instructions beyond cleaning up permission-related references