# scout (FrontTerrain CLI v9.4.7) **FrontTerrain (`scout`)** The Autonomous AI Principal Software Engineer & Codebase Co-Pilot in your terminal. Scout executes autonomous multi-step engineering loops, builds complete projects from scratch, edits and refactors existing codebases, controls external desktop/browser applications, self-heals syntax/build/test errors, runs terminal commands with AI error diagnostics, and provides an interactive agent session built for high-agency developer productivity. --- ## Installation Install globally using npm: ```bash npm install -g scout@latest ``` --- ## Quick Start & Commands Once installed, use `scout` in any project directory: ### Autonomous Computer-Use Operator & AI Agent Sessions ```bash # Autonomous Multi-Step AI Agent (Direct goal execution, context inspection, automated test/build verification) scout agent "Open Notepad, type 'Autonomous test note', and save to Desktop" scout agent "Build a responsive snake game in HTML and JS with smooth animations" scout task "Fix typescript build errors in src/utils" -v "npm run build" scout goal "Refactor database query logic" -y ### Interactive Scout Agent Session (Persistent operator loop with Slash Commands & full tool execution) scout agent # Optional voice interaction flags: scout agent -V # Launch with Audio Voice mode (STT + TTS) scout agent --voice # Inside session: # Slash commands: /help /voice /speak /tree /stats /test /explain /export /diff /undo /clear /history /exit # Generate and create a new source code file scout agent --create src/utils/math.ts "Create helper functions for sum, average, and array chunking" # Run terminal/shell commands with automated AI error diagnosis & self-healing scout agent --run npm test scout agent --run tsc # Feasibility roadmap & bug scan scout agent --scan scout agent --plan "Add rate limiting to API endpoints" # Revert Scout's last action & restore backed-up file contents scout undo ``` ### Codebase Understanding & Due-Diligence ```bash # Initialize understanding map of a local or remote repository scout init [repoUrl] # Multilingual AI teardowns & onboarding summaries (e.g. spanish, hindi, french, japanese, etc.) scout init [repoUrl] --lang spanish scout init [repoUrl] -l hi # Human-readable onboarding summary (the "week-one explainer") scout brief # Bug & code quality scan report (read-only) scout risky # Security & dependency / supply-chain audit scout audit # Architecture, performance, and DSA-level suggestions scout recommend # Show knowledge holders of a specific directory or file (from git history) scout owners # Live internet search for live web context & up-to-date documentation scout search "Next.js 15 App Router" scout web "Tailwind CSS v4" --ask --lang french # History log of everything Scout has done in this repository scout history # Check for updates and auto-upgrade Scout scout upgrade ``` ### Account Authentication & Session Management ```bash # Create a new Scout developer account scout signup # Log into your FrontTerrain / Holosene account scout login # Check active session status and user credentials scout auth # Terminate active session scout logout ``` ### Interactive Web Dashboard & Local GUI ```bash # Launch the Scout Web Dashboard sync server scout dashboard # Launch and automatically open browser to the local UI scout dashboard --open ``` ### Quota, Usage & Subscription Plans ```bash # Check credit balance, renewal status, and BYOK mode scout quota # Manage subscription tier, view pricing, and upgrade quota scout plan ``` ### Model Latency & Performance Benchmark ```bash # Measure latency and tokens/second across configured models (Nemotron, Qwen, Gemini, GPT) scout benchmark ``` ### Model Context Protocol (MCP) Ecosystem ```bash # List all configured MCP connections with live status and tool counts scout mcp list # Connect an external MCP server over HTTP/SSE with bearer token scout mcp add "GitHub" --transport http --endpoint "https://api.github.com/mcp" --token "$GITHUB_PAT" # Connect a local stdio MCP server (child process) scout mcp add "Filesystem" --transport stdio --command "npx" --args "-y @modelcontextprotocol/server-filesystem /path/to/dir" # Deep inspection of server capabilities, transport, and permissions scout mcp inspect GitHub # View discovered tools and schemas from an MCP server scout mcp tools GitHub # Manually trigger protocol handshake / reconnect scout mcp connect GitHub scout mcp disconnect GitHub # Remove an MCP connection and securely wipe encrypted credentials scout mcp rm GitHub # Probe latency, error count, and health across all MCP servers scout mcp health ``` --- ## Autonomous Computer-Use Agent Architecture Scout is built as a high-agency autonomous operator capable of operating external desktop applications, browsers, operating systems, and terminal workspaces while strictly preserving user intent: ``` ┌────────────────────────────────────────────────────────┐ │ User Goal / Objective │ └──────────────────────────┬─────────────────────────────┘ │ ▼ ┌────────────────────┐ │ Task Planner │ ◄─── Goal Decomposition & Dependencies └──────────┬─────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ Execution Intent Engine │ │ • Inferred Intent: Computer / Browser / Code / Mixed │ │ • Required Apps: [Notepad, Excel, Chrome, ...] │ │ • Destination: Desktop / Downloads / Repository Root │ │ • Constraint: USER INTENT > TOOL CONVENIENCE │ └──────────────────────────┬─────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ Task State Manager │ │ • Checkpoints: .ft/tasks/.json │ │ • Structured Memory: AgentWorkspace & Intent Gates │ │ • Resume Support: scout agent --resume │ └──────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────┴─────────────────────┐ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ │ Risk Classifier │ │ Approval Manager │ │ • LOW / MEDIUM │ │ • Human-in-the-loop│ │ • HIGH / CRITICAL │ ──────────────────► │ approval queue │ └──────────┬──────────┘ └──────────┬──────────┘ │ Safe / Approved │ Approved └─────────────────────┬─────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ Tool Execution Guard │ │ • Strictly blocks direct filesystem shortcuts when │ │ application interaction was requested │ │ • Native Computer Controller (PowerShell, AppleScript) │ │ • Semantic Browser Engine & Core Codebase Tools │ └──────────────────────────┬─────────────────────────────┘ │ ▼ ┌────────────────────┐ │ Action Verifier │ │ • File existence │ │ • Desktop vs repo │ ◄── Rejects substitute paths │ • Window active │ │ • Content check │ └──────────┬─────────┘ │ ┌─────────────────────┴─────────────────────┐ │ Success │ Failure (Structured Error) ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ │ Next Step / │ │ Bounded Recovery │ │ Completion │ │ • OBSERVE (capture) │ │ │ │ • REFOCUS WINDOW │ └─────────────────────┘ │ • RETRY COMPUTER OP │ └─────────────────────┘ ``` ### 1. Execution Intent Preservation (`USER INTENT > TOOL CONVENIENCE`) - **Outcome vs. Execution Requirements**: Scout clearly differentiates between outcome tasks (*"Create file X"*) and execution tasks (*"Open Notepad, type X, and save to Desktop"*). - **Anti-Substitution Gating**: When a user specifies desktop application interaction, Scout strictly prevents silent shortcuts (such as invoking direct filesystem APIs) and executes the requested workflow through the application interface. - **True Desktop Path Resolution**: Automatically discovers and targets the user's actual Desktop path (including Windows OneDrive/Desktop and `~/Desktop`), rejecting accidental substitutions into repository roots. ### 2. Native Computer & Desktop Application Control - **Cross-Platform System Controller**: Native mouse movement, clicking (`left`, `right`, `double`), text typing (`SendWait`), keyboard combinations (`Ctrl+S`, `Alt+F4`), window activation, and UI inspection across Windows (PowerShell `-EncodedCommand`), macOS (AppleScript), and Linux (`xdotool`). - **Active Application State Tracking**: Continuously monitors `expectedApplication`, `activeApplication`, and `activeWindow` before and after UI actions. - **Bounded Error Recovery Loop**: When an action fails (e.g. lost foreground focus), Scout returns structured feedback `{ success: false, action, error, recoverable: true }` and executes a bounded recovery cycle (`OBSERVE ➔ REFOCUS ➔ RETRY`) instead of abandoning the interface. ### 3. Task State Persistence & Resumability - **Checkpointed Task Architecture**: Real-time step progress, observations, artifacts, and execution intents are continuously persisted to `.ft/tasks/.json`. - **Operational Memory Compaction**: Context summarization prevents unbounded transcript growth during long multi-step workflows while keeping active goals and variables visible to the model. - **Task Resumption**: Re-attach to any paused or interrupted session with `scout agent --resume `. ### 4. Safety Guardrails & Human-in-the-Loop Approvals - **Risk Classification**: Classifies every action as `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`. - **Approval Gate**: Pauses and queues high-impact operations (destructive file deletes, system commands, credential requests) for explicit human authorization. --- ## Model Context Protocol (MCP) Ecosystem Architecture Scout implements a production-grade, standard-compliant **Model Context Protocol (MCP)** host and client runtime. It enables Scout to connect to, discover, manage, monitor, and autonomously use external MCP servers across the **CLI**, **Agent Runtime**, and **Web Dashboard** without hardcoding integrations for individual vendors. ```mermaid graph TD CLI["Scout CLI (scout mcp)"] --> Manager["MCPManager (Singleton Orchestrator)"] Web["Web Dashboard (REST API)"] --> Manager Runtime["Agent Runtime & Engine"] --> Manager Manager --> Persistence["Persistence & AES-256 Vault"] Manager --> Permissions["MCPPermissionManager"] Manager --> Router["MCPToolRouter (Max 10 / Prompt)"] Manager --> Telemetry["MCPTelemetry (~/.ft/mcp_activity.json)"] Manager --> Health["MCPHealthMonitor & Recovery"] Manager --> Client["MCPClient Instance(s)"] Client --> HTTPTransport["HttpMcpTransport (SSE / POST Streamable)"] Client --> StdioTransport["StdioMcpTransport (Subprocess JSON-RPC)"] HTTPTransport --> RemoteServers["External MCP Servers (Motion, GitHub, Figma, etc.)"] StdioTransport --> LocalServers["Local MCP Servers (Filesystem, Postgres, etc.)"] ``` ### 1. Standard-Compliant Transports & Protocol Handshake - **Streamable HTTP / SSE / POST (`HttpMcpTransport`)**: Implements standard HTTP transport with JSON-RPC 2.0 request/response framing, server-sent events for streaming, custom authorization headers, and ping keep-alives. - **Local Subprocess Stdio (`StdioMcpTransport`)**: Spawns local CLI tools as child processes with newline-delimited JSON-RPC message framing, robust stdout/stderr stream isolation, and clean termination. - **Protocol Handshake & Discovery**: Automatically performs `initialize` and `notifications/initialized` handshakes, measures roundtrip ping latency, and fetches paginated tool definitions via `tools/list`. ### 2. Zero Plaintext Secrets & AES-256-GCM Credential Vault - **Encrypted Vault (`~/.ft/mcp_credentials.enc`)**: Bearer tokens and API keys are strictly encrypted at rest using **AES-256-GCM** with PBKDF2 machine-keyed derivation and random initialization vectors (IV). - **Public Config Sanitization (`~/.ft/mcp_servers.json`)**: Server configuration files store endpoints, transport modes, and permission settings while stripping all sensitive keys (`token`, `key`, `password`, `secret`). - **UI & Log Safety**: No plaintext secret is ever emitted in CLI outputs, REST API responses, web dashboard templates, or audit logs. ### 3. Dynamic Capability Routing & Context-Window Protection - **Semantic Relevance Ranking**: External tools are dynamically evaluated against the active user prompt and goal using semantic keyword matching and capability scoring. - **Strict 10-Tool Maximum**: Scout enforces an autonomous ceiling of **10 tools per completion** to prevent LLM context-window bloating and ensure focused reasoning. - **System Prompt Capability Summaries**: Injects a compact summary of available external servers and active tool categories into the agent's system prompt without overwhelming prompt tokens. ### 4. Granular Permissions & Safety Controls - **Server-Level Controls**: Entire external servers can be enabled, disabled, or set to require confirmation. - **Per-Tool Enable/Disable Toggles**: Individual tools can be switched on or off dynamically from the CLI or Web Dashboard. - **Safety Classification**: Discovered tools are classified into permission levels: `read`, `write`, `destructive`, or `admin`. Destructive tools (e.g., delete repository, drop table) require explicit human confirmation. ### 5. Observable Telemetry & Redacted Audit Logs - **Structured Activity Trail (`~/.ft/mcp_activity.json`)**: Every MCP tool execution is logged with timestamp, server ID, tool name, execution duration (ms), outcome, and recovery metadata. - **Deep Redaction**: Sensitive parameter keys and values are automatically masked with `[REDACTED]` prior to logging. - **Health Probing**: Continuous background health checks monitor server status, tracking latency and failure counts. ### 6. Universal Control Plane The same synchronized MCP state is shared across: 1. **Scout CLI (`scout mcp`)**: Terminal management, manual testing, inspection, and health probes. 2. **Scout Agent Runtime**: Autonomous execution and function calling during multi-step tasks. 3. **Scout Web Dashboard**: Visual management UI with live KPI counters, server cards, per-tool toggle switches, and a real-time audit trail. --- ## Scout Autonomous Tool Registry > 📘 **Full Architecture & Specifications**: For complete deep-dive documentation, flowcharts, and schemas, see [AUTONOMOUS_FEATURES.md](./AUTONOMOUS_FEATURES.md). ### Desktop & Computer-Use Control Tools | Tool | Description | Tier Availability | |---|---|:---:| | `computer` | Unified multi-action desktop dispatcher (click, drag, type, hotkey, open, etc.) | Pro / Enterprise | | `computer_screenshot` | Capture display screen image and inspect active foreground window | Pro / Enterprise | | `computer_click` | Move cursor and click mouse at coordinate (left, right, middle) | Pro / Enterprise | | `computer_double_click` | Double-click mouse at specified screen coordinate | Pro / Enterprise | | `computer_right_click` | Right-click mouse at screen coordinate to open context menus | Pro / Enterprise | | `computer_mouse_move` | Move mouse cursor to specific display (x, y) coordinates | Pro / Enterprise | | `computer_mouse_down` | Hold down mouse button for drag operations | Pro / Enterprise | | `computer_mouse_up` | Release mouse button | Pro / Enterprise | | `computer_drag` | Drag mouse cursor from `(fromX, fromY)` to `(toX, toY)` | Pro / Enterprise | | `computer_scroll` | Scroll vertical or horizontal mouse wheel deltas | Pro / Enterprise | | `computer_type` | Ensure target window focus and type text keystrokes via OS keyboard | Pro / Enterprise | | `computer_key_press` | Press individual keyboard key (`enter`, `tab`, `escape`, `backspace`) | Pro / Enterprise | | `computer_hotkey` | Trigger key combination (`["ctrl", "s"]`, `["alt", "f4"]`, `["alt", "tab"]`) | Pro / Enterprise | | `computer_open_app` | Launch desktop application (Notepad, Excel, Chrome, Terminal) and focus window | Pro / Enterprise | | `computer_close_app` | Gracefully close application or window by title/executable | Pro / Enterprise | | `computer_switch_window` | Switch foreground active window to target application | Pro / Enterprise | | `computer_inspect_ui` | Inspect active window coordinates, title, and UI state | Pro / Enterprise | | `computer_wait` | Pause execution to allow desktop applications or animations to settle | Pro / Enterprise | | `computer_diagnostic` | Retrieve system display resolution, DPI scaling, and Scout driver health | Pro / Enterprise | ### Browser Automation & Web Scraping Tools | Tool | Description | Tier Availability | |---|---|:---:| | `browser_navigate` | Open URL, handle navigation history, and construct semantic DOM tree | Pro / Enterprise | | `browser_inspect` | Inspect clickable buttons, links, inputs, and assign element ref IDs (`[ref=1]`) | Pro / Enterprise | | `browser_click` | Click element by CSS selector, visible label text, or ref ID | Pro / Enterprise | | `browser_type` | Type text strings into active form fields and search inputs | Pro / Enterprise | | `browser_select` | Choose option from dropdown `