ft-scout 1.0.8 → 1.1.0

package/README.md

@@ -1,32 +1,482 @@
-# ft-scout
-
-FrontTerrain — The Onboarding Co-Pilot for New Codebases.
-
-## Installation
-
-Install globally using npm:
-
-```bash
-npm install -g ft-scout
-```
-
-## Usage
-
-Once installed, you can use the `ft` or `ft-scout` commands.
-
-```bash
-# Initialize learning on a local repository
-ft init [repoUrl]
-
-# Print a brief, AI-powered onboarding summary
-ft brief
-
-# Show knowledge holders of a specific directory or file
-ft owners <path>
-
-# Show a code fragility map based on churn and hotfixes
-ft risky
-
-# Diagnose local setup, missing .env files, and runtime mismatches
-ft setup
-```
+# scout (FrontTerrain CLI v1.1.0)
+
+**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 ft-scout@latest
+```
+
+---
+
+## Quick Start & Commands
+
+Once installed, use `scout` or `ft` 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 <path>
+
+# 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/<taskId>.json               │
+                  │   • Structured Memory: AgentWorkspace & Intent Gates   │
+                  │   • Resume Support: scout agent --resume <taskId>      │
+                  └──────────────────────────┬─────────────────────────────┘
+                                             │
+                       ┌─────────────────────┴─────────────────────┐
+                       ▼                                           ▼
+            ┌─────────────────────┐                     ┌─────────────────────┐
+            │   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/<taskId>.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 <taskId>`.
+
+### 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 `<select>` menus by value or visible text | Pro / Enterprise |
+| `browser_scroll` | Scroll webpage up or down to load lazy-loaded elements | Pro / Enterprise |
+| `browser_content` | Extract clean, structured visible text and tabular data from page | Pro / Enterprise |
+| `browser_screenshot` | Capture visual viewport image of active browser page | Pro / Enterprise |
+| `browser_download` | Automatically download web files, invoices, PDFs to workspace `downloads/` | Pro / Enterprise |
+
+### Cognitive Scratchpad & Reasoning Tools
+| Tool | Description | Tier Availability |
+|---|---|:---:|
+| `scratchpad` | Private working memory for multi-step plans, hypotheses, and state (`write`, `read`, `append`, `clear`) | Pro / Enterprise |
+
+### Workspace & Engineering Tools (Developer Baseline)
+| Tool | Description | Tier Availability |
+|---|---|:---:|
+| `read_file` | Read content & line ranges of workspace files | All Tiers (Free, Pro, Enterprise) |
+| `write_file` | Create new files or overwrite existing source code | All Tiers (Free, Pro, Enterprise) |
+| `edit_file` | Search & replace exact target code snippets | All Tiers (Free, Pro, Enterprise) |
+| `multi_edit_file` | Apply batch snippet replacements in a single atomic tool call | All Tiers (Free, Pro, Enterprise) |
+| `run_command` | Execute live terminal commands (`npm test`, `tsc`, `pytest`) | All Tiers (Free, Pro, Enterprise) |
+| `list_dir` | List contents of workspace directories | All Tiers (Free, Pro, Enterprise) |
+| `tree_view` | Generate visual ASCII directory tree structures for workspace paths | All Tiers (Free, Pro, Enterprise) |
+| `file_info` | Get file metadata, exact line counts, size, & modification timestamps | All Tiers (Free, Pro, Enterprise) |
+| `grep_search` | String/regex pattern search across entire codebase | All Tiers (Free, Pro, Enterprise) |
+| `glob_search` | Filter workspace files by file glob patterns | All Tiers (Free, Pro, Enterprise) |
+| `fetch_url` | Fetch web API documentation, specs, or external web URLs | All Tiers (Free, Pro, Enterprise) |
+| `git_diff` | Query uncommitted workspace git diff directly inside execution loop | All Tiers (Free, Pro, Enterprise) |
+| `ask_user` | Request missing secret credentials or API keys | All Tiers (Free, Pro, Enterprise) |
+| `speak_text` | Read text phrases out loud via ElevenLabs AI Human Voice (Pro/Enterprise) or Windows SAPI5 (Free) | All Tiers (Free, Pro, Enterprise) |
+| `task_completed` | Conclude autonomous goal execution with verification and report | All Tiers (Free, Pro, Enterprise) |
+
+### Dynamic External MCP Tools
+| Tool Namespace | Description | Tier Availability |
+|---|---|:---:|
+| `<server>__<tool_name>` | Dynamically discovered from connected MCP servers (GitHub, Figma, Notion, Slack, Motion, or custom servers), normalized to OpenAI function schemas, and routed to agent context | All Tiers (Free, Pro, Enterprise) |
+
+---
+
+## Multi-Provider LLM Resilience & Fallback Engine
+
+Scout is built for uninterrupted autonomy across multiple LLM providers:
+
+- **Multi-Provider Routing**: Seamlessly routes and fails over across **NVIDIA NIM** (Nemotron, DeepSeek R1/V3), **Groq** (Llama 3.3 70B), **Google Gemini**, and **OpenAI** (GPT-4o).
+- **Universal Tool-Calling Fallback**: For reasoning models or providers that do not natively support OpenAI tool/function calling (e.g., Nemotron, DeepSeek reasoning models), Scout automatically injects structured JSON schema instructions and robustly parses tool invocations.
+- **Adaptive Timeout Handling**: Extended 90-second execution window for deep reasoning models on NVIDIA NIM.
+- **Instant Model Failover**: Automatically detects timeouts (`ETIMEDOUT`, `ECONNABORTED`, `408`, `AbortError`), payload errors, and tool-definition errors, instantly switching to fallback models without wasting retry cycles.
+
+---
+
+## Conversational Voice Co-Pilot & Audio Engine
+
+When starting interactive sessions in `scout agent` (`-V` or `--voice`), `scout init` (ask mode), or `scout search`, Scout presents full two-way audio dialogue:
+
+1. **Native C# High-Performance Audio Capture**: Built-in standalone Win32 `waveIn` audio recording engine (`scout_audio_recorder.exe`) compiled directly via native Windows toolchain without requiring Python or external heavy runtime dependencies.
+2. **Real-Time Voice Activity Detection (VAD)**: Intelligent RMS audio power monitoring with a 2.5-second silence debounce cutoff, allowing developers to speak natural multi-sentence thoughts without mid-sentence interruptions.
+3. **Groq Whisper STT with Developer Vocabulary Hints**: Lightning-fast speech-to-text powered by `whisper-large-v3-turbo` with technical prompt biasing (e.g., *Scout, Chrome, Notepad, VS Code, TypeScript, Python*) to prevent mishearing developer commands.
+4. **Ultra-Realistic ElevenLabs Human Voice TTS**:
+   - **Pro & Enterprise Tiers**: Full access to **ElevenLabs AI Voice Synthesis** (`eleven_turbo_v2_5`, PCM 24kHz / WAV container) delivering human-quality, natural speech dialogue.
+   - **Developer Free Tier**: Fully supported with local Windows SAPI5 speech synthesis (zero API billing cost).
+5. **Conversational Co-Pilot Persona**: Instant spoken acknowledgment (e.g., *"On it! Opening Chrome for you."*) and warm conversational completion summaries rather than dry robotic execution logs.
+
+---
+
+## Interactive Slash Commands in Session
+
+Inside an active `scout agent` interactive session, type any slash command to trigger agent actions:
+
+- `/help`  Display comprehensive guide to all 15 tools and interactive slash commands.
+- `/voice`  Activate microphone Speech-to-Text (STT) listener to speak your prompt into CLI.
+- `/speak <text>`  Read entered text out loud via ElevenLabs AI (Pro/Enterprise) or SAPI5 (Free).
+- `/tree [dir]`  Render an interactive visual directory tree of any workspace folder.
+- `/status` or `/stats`  View real-time session telemetry (steps executed, tool call count, modified files, elapsed time, branch info).
+- `/test [cmd]`  Auto-detect and run project verification test suite directly inside session context.
+- `/explain <file>`  Request a deep architectural breakdown and code explanation of a specific file.
+- `/export` or `/save-session`  Export full session report and action history to `.ft/session-<timestamp>.md`.
+- `/diff`  Display colorized git diff of uncommitted workspace changes.
+- `/clear` or `/compact`  Clear session conversation context window.
+- `/undo`  Instant 1-command revert of file modifications applied by Scout.
+- `/history`  View recent Scout action logs.
+- `/exit`  Quit Scout Agent session gracefully.
+
+---
+
+## What's New in v1.1.0
+- **Ultra-Realistic ElevenLabs AI Voice Engine**: Integrated human-grade voice synthesis via ElevenLabs for Pro and Enterprise subscribers, bringing lifelike conversational audio feedback directly to the CLI co-pilot.
+- **Native C# Audio Recorder with Real-Time VAD**: Standalone Win32 `waveIn` audio recording binary (`scout_audio_recorder.exe`) with RMS energy detection and 2.5s silence debounce cutoff.
+- **Zero-Latency Groq Whisper STT**: Integrated Groq `whisper-large-v3-turbo` with specialized developer vocabulary hints to eliminate speech recognition errors.
+- **Intelligent Single-Step App Intent Engine (`checkSimpleAppAction`)**: Natural language comprehension for desktop app commands across English and Hinglish (e.g., *"open chrome"*, *"chrome open kar do"*, *"launch vscode"*), terminating immediately on Step 1 without unnecessary repository file exploration.
+- **Autonomous Computer-Use & Desktop App Operator**: Native desktop application control (Notepad, Excel, VS Code, Browser) with full mouse, keyboard, hotkey, and window focus management across Windows, macOS, and Linux powered by the native `scout_driver.exe` engine.
+- **Autonomous Browser Automation & Document Download Engine**: Fully automated web browsing (`browser_navigate`, `browser_inspect`, `browser_click`, `browser_type`, `browser_select`, `browser_scroll`, `browser_content`, `browser_screenshot`, `browser_download`) with DOM extraction and automatic file downloads to `downloads/`.
+- **Cognitive Scratchpad & Working Memory (`scratchpad`)**: Long-horizon multi-step reasoning memory (`write`, `read`, `append`, `clear`) saved to `.ft/scratchpad.md`, keeping model context concise and focused.
+- **Strict Execution Intent Alignment (`USER INTENT > TOOL CONVENIENCE`)**: Differentiates between outcome and execution requirements; strictly blocks silent filesystem shortcuts when application interaction is requested.
+- **Bounded Computer Recovery Loop**: Structured action feedback (`{ success, action, error, recoverable }`) with automated re-observation, window refocusing, and retries.
+- **Action Verifier & Anti-Substitute Path Rejection**: Verifies true destination (resolving Windows OneDrive/Desktop and `~/Desktop`) and rejects substitute files created in the workspace root.
+- **Interactive Web Dashboard & Sync Server (`scout dashboard`)**: Launch a local web GUI to visually inspect repository maps, audit logs, plan details, live agent controls, and subscription tiers.
+- **Developer Authentication Guard (`scout login` / `signup` / `auth`)**: Unified account management with Firebase and Holosene token authentication, securing command execution and session persistence.
+- **Quota & Subscription Management (`scout quota` / `plan`)**: Easily inspect real-time usage quotas, track billing renewal cycles, switch between tiers, or configure BYOK (Bring-Your-Own-Key) access.
+- **Automated Model Benchmark Suite (`scout benchmark`)**: Run live end-to-end latency and throughput benchmarks (tokens/sec) across all configured LLM providers (Nemotron, Qwen, Gemini, GPT).
+- **Nemotron & DeepSeek Fallback Tool-Calling**: Smart JSON prompt formatting and fallback parser for models lacking native function-calling.
+- **Extended 90s LLM Timeout & Instant Failover**: Extended execution window for deep reasoning models and immediate failover upon timeout or connection abort.
+- **First-Class Model Context Protocol (MCP) Ecosystem**: Connect, discover, monitor, and autonomously invoke tools across external MCP servers (Motion, Higgsfield, GitHub, Figma, Notion, Slack, or any custom server) over streamable HTTP/SSE or local stdio processes.
+- **AES-256-GCM Encrypted Credential Vault (`~/.ft/mcp_credentials.enc`)**: Machine-keyed zero-plaintext credential storage protecting API keys and bearer tokens at rest and across all UI/CLI interfaces.
+- **Intelligent Context-Window Tool Router**: Semantic relevance ranking dynamically selects and injects external MCP tools up to a strict ceiling of 10 tools per prompt, eliminating LLM context window bloat.
+- **Granular Server & Tool Safety Permissions**: Fine-grained access control with per-tool enable/disable switches, destruction prevention guards, and bounded recovery.
+- **Observable MCP Audit Trail & Web Control Plane**: Append-only redacted telemetry (`~/.ft/mcp_activity.json`) and a dedicated Web Dashboard management interface (`scout dashboard`) for visual server and tool orchestration.
+
+---
+
+## Overhauled Features & Performance
+
+- **Autonomous Multi-Step Computer-Use**: Decompose complex tasks into structured steps, verify outcomes, and self-heal from failures.
+- **Strict Intent Governance**: Preserves required applications and target paths without unauthorized tool substitutions.
+- **Task State Persistence (`.ft/tasks/`)**: Maintains checkpointed task states across execution sessions.
+- **Safety & Human Approval**: Automatic risk rating with human-in-the-loop intervention for high-risk operations.
+- **In-Terminal Native STT & TTS Voice Engine**: Direct in-terminal microphone voice input and OS native speech synthesis with zero browser popups.
+- **Multi-Model Provider Resilience**: Intelligent automatic routing and failover across NVIDIA NIM, Groq, Gemini, and OpenAI with universal JSON tool-call fallback.
+- **High-Agency Multi-File Scaffolding**: Automatically creates, implements, tests, and verifies multi-file codebases from scratch.
+- **Atomic Multi-Snippet Editing (`multi_edit_file`)**: Executes multiple code replacements in a single turn for complex multi-point refactoring.
+- **Session Telemetry & Analytics**: Live step counter, tool call counter, and elapsed time estimation during ReAct loop execution.
+- **Automated Verification & Self-Healing**: Validates JS, TS, Python, Rust, Go, JSON, and embedded `<script>` HTML tags. Auto-diagnoses compiler errors and applies self-healing code fixes before finishing.
+- **Post-Execution Review Menu**: Choose from **Keep Changes**, **Run Verification Tests**, **Create Pull Request**, **Export Session Report**, or **Revert Changes** after goal completion.
+- **1-Command Rollback (`scout undo`)**: Every file modification is backed up with timestamped history for zero-risk experimentation.
+- **Universal MCP Host & Orchestrator**: Synchronized MCP connection state, tool routing, and permission controls shared seamlessly across the Scout CLI, autonomous Agent Runtime, and Web Dashboard.
+
+---
+
+## License
+
+ISC © [FrontTerrain](https://npmjs.com/package/ft-scout)
+
+**For any question or concern contact**
+[FrontTerrain support](https://frontterrain.com/support)
+
+**Made with ❤️ by FrontTerrain**
+

package/bin/ft.js

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
+process.env.CHARSET = 'utf8';
+process.env.DOTENV_CONFIG_QUIET = 'true';
 import('./src/index.js');

package/bin/src/commands/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["agent.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;CACvB;AA2CD,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,QAKpD;AAED,wBAAgB,cAAc,IAAI,YAAY,EAAE,CAO/C;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACpC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAsDlE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3E;AAED,MAAM,WAAW,gBAAgB;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IACvE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACtC;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAoF5F;AAED,wBAAgB,yBAAyB,CACrC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,EAAE,MAAM,EAAE,GACpB,MAAM,EAAE,CAgGV;AAED,wBAAsB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAMxF;AAED,wBAAsB,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,iBA8oC3E"}