ciscollm-cli 1.0.1 → 1.0.2

package/README.md

@@ -1,112 +1,181 @@
 # ciscollm-cli
 
-`ciscollm-cli` is a Cisco IOS automation agent CLI for configuration, troubleshooting, and simulation. It supports tool-calling with an LLM, safety guardrails, rollback handling, and a mock switch/router environment for offline testing.
-
-## Installation
-
-Install the published package globally:
+`ciscollm-cli` is a premium, autonomous Cisco IOS automation agent CLI designed for network configuration, troubleshooting, and simulation. By leveraging LLM tool-calling capabilities, it allows engineers to manage local, remote, or simulated Cisco hardware safely and efficiently.
+
+The CLI features an **Interactive Setup Wizard**, **Multi-Device Coordination**, **Safety Guardrails (Command Firewall)**, **Automatic Configuration Rollbacks**, **Mock Device Simulation**, and **Strict Command Reference Validation**.
+
+---
+
+## 🚀 Key Features
+
+### 1. ⚙️ Interactive Setup Wizard
+If `ciscollm run` is executed without a `--goal` parameter, the CLI automatically launches a step-by-step interactive setup wizard (using `inquirer`). The wizard guides the user through:
+* **LLM Provider Selection:** Local (Ollama / LM Studio) or Cloud (OpenRouter).
+* **Local LLM Settings:** Service type (Ollama/LM Studio), API endpoint URL, and model name.
+* **Cloud LLM Settings:** OpenRouter API Key, model name, and endpoint.
+* **Connection Protocol:** Serial (with automated COM port scanning), SSH, Telnet, or Mock simulation.
+* **Connection Details:** COM port and Baud rate (for serial), or Host target, Port, Username, and Password (for SSH/Telnet).
+* **Configuration Goal:** Prompting for the network task the agent needs to achieve.
+* **Configuration Summary:** Displays a summary of the setup and prompts for final confirmation before starting execution.
+
+### 2. 🔀 Multi-Device & Multi-Agent Coordination
+Manage configurations across multiple Cisco hardware devices simultaneously. The `--com` (for serial) and `--host` (for SSH/Telnet) flags accept comma-separated inputs (e.g. `--com COM3,COM4` or `--host 10.0.0.1,10.0.0.2`). The internal `MultiAgentCoordinator` manages all connections in parallel, tracks status, and handles clean disconnections upon exit.
+
+### 3. 🛡️ Command Firewall & Safety Guardrails
+To prevent accidental lockouts, service disruptions, or losing device access, the built-in `CommandFirewall` monitors all LLM-generated commands. 
+* **Blocked Operations:**
+  * Removing default static routes (`no ip route 0.0.0.0...`) which can break management access.
+  * Disabling AAA authentication (`no aaa new-model`) or zeroizing crypto keys (`crypto key zeroize`).
+  * Deleting access lists or access groups (`no access-list`, `no ip access-group`).
+  * Shutting down active protected interfaces (e.g. `GigabitEthernet0/0`, `GigabitEthernet0/1`, `GigabitEthernet1/0`, `Vlan1`).
+  * Removing configured IP addresses on protected interfaces (`no ip address`).
+* **Human-in-the-Loop Validation:** High-risk commands trigger a warning prompt, requiring the operator to manually authorize the execution.
+* **Non-Interactive Mode:** Running with `--non-interactive` (or setting environment variable `CISCOLLM_NON_INTERACTIVE=true`) automatically rejects all blocked/high-risk commands.
+
+### 4. 🔄 Transaction Rollback & Inversion Manager
+If a configuration step fails or the agent encounters command errors, the `TransactionManager` restores the device state:
+* **Atomic Backup:** Before modifying config, the agent attempts to back up the current running-config to `flash:backup-agent.cfg`.
+* **Atomic Configuration Replace:** Rollbacks prioritize replacing the configuration atomically using `configure replace flash:backup-agent.cfg force`.
+* **Command Inversion Fallback:** If flash storage is unreachable, it builds an inverse command sequence in reverse order (e.g. `ip address ...` -> `no ip address`, `shutdown` -> `no shutdown`, `no shutdown` -> `shutdown`, `description ...` -> `no description`) and executes them sequentially in their respective submodes.
+
+### 5. 📚 Strict Command Reference Validation
+Enforces compliance against an official Cisco IOS Command Reference index:
+* **Strict Validation Mode:** Enabled via `--strict-command-ref` (or setting `CISCOLLM_STRICT_COMMAND_REF=true`). The agent will block any command not listed in the command-reference index.
+* **PDF Command Indexer:** The engine reads `cf_command_ref.pdf`, extracts structural commands, and caches them in `.cache/cf_command_ref.index.json` to speed up startup times.
+* **Fuzzy Command Family Expansion:** Automatically expands shortened commands (e.g. `sh` -> `show`, `conf t` -> `configure terminal`, `int gig0/1` -> `interface GigabitEthernet0/1`) to check they match valid command families in the index.
+* **Reference Telemetry:** Telemetry logs detail the warmup time, source (PDF, cache, or memory), and matched command count. Can be disabled with `--no-ref-telemetry`.
+
+### 6. 🧪 Mock Device Simulation
+Mock mode (`--protocol mock`) provides a stateful simulation of a Cisco IOS device, allowing offline development and testing. It features:
+* **Stateful Database:** Maintains interfaces, VLANs, shell variables, shell functions, and static routing tables, saved locally under `.mock-state-<device>.json`.
+* **Interactive CLI Simulator:** Simulates user and privileged EXEC modes, configuration modes, VLAN databases, DHCP pools, OSPF routers, and IP routing tables.
+* **Output Filtering (Pipes):** Supports standard IOS output piping such as `| include`, `| grep`, `| exclude`, and `| begin`.
+* **Network Testing:** Simulates latency and ICMP ping responses.
+
+### 7. 🛡️ Pre-Execution Safety Validation (Dry-Run Check)
+Before executing any state-mutating command, the agent runs a dry-run check against the known network topology:
+* **Topology Awareness:** Analyzes active physical/logical links between core, distribution, and access segments.
+* **Accidental Disruption Prevention:** Detects and intercepts commands that could accidentally shut down critical uplink ports or neighbor nodes, ensuring continuous uptime.
+
+### 8. 📊 Live Configuration State Diff Engine
+Maintains deep visibility of system modifications:
+* **Before/After Snapshots:** Takes memory-efficient snapshots of device interfaces, IP addresses, subnets, routing tables, and active VLAN databases before and after executing any command.
+* **Visual Colorized Diffs:** Automatically outputs a structured difference report highlighting additions in green, removals in red, and updates/modifications in yellow.
+
+### 9. 🪵 Continuous Enterprise Audit Trails
+Ensures accountability for automated activities:
+* **Detailed Logs:** Generates structured records containing the timestamp, target device, active agent role, LLM reasoning thoughts, executed commands, and final output status.
+* **Local Audit Store:** Persists all interactions locally to `audit.log` for easy integration with standard security information and event management (SIEM) systems.
+
+### 10. 🔀 Hierarchical Network Swarms
+Supports role-specific command delegation and intelligence:
+* **Role Routing:** Multi-agent coordinator routes tasks to specialized personalities—**Core Agent**, **Distribution Agent**, and **Access Agent**—matching the logical tier of the configuration task.
+* **RBAC Constraints:** Restricts operations according to the `--rbac-role` parameter. The `read_only` role safely blocks any modifying actions and logs violations to the audit log.
+
+### 11. 🔌 NETCONF & CML Simulation Adapters
+Extends sandbox capabilities beyond local mock devices:
+* **Cisco Modeling Labs (CML):** Provides sessions to interact directly with digital twin network simulations.
+* **NETCONF XML Sessions:** Supports programmatic configuration using structured XML RPC calls and YANG schemas.
+
+---
+
+## 📦 Installation
+
+To install `ciscollm-cli` globally from npm:
 
 ```bash
 npm install -g ciscollm-cli
 ```
 
-After installation, the `ciscollm` command becomes available in your terminal.
+Once installed, the global executable `ciscollm` becomes available.
 
-## Quick Start
+---
 
-Show the available commands and flags:
+## 🛠️ CLI Usage & Options
 
 ```bash
-ciscollm run --help
+ciscollm run [options]
 ```
 
-Run the agent in mock mode for a safe offline simulation:
-
+### Options Table
+
+| Option / Flag | Alias | Description | Default Value |
+|---|---|---|---|
+| `-g, --goal <intent>` | - | The goal of the configuration/troubleshooting task. If not specified, launches the Interactive Setup Wizard. | - |
+| `--protocol <type>` | - | Connection protocol (`serial`, `ssh`, `telnet`, `mock`, `netconf`, `cml`). | `serial` |
+| `--provider <type>` | - | LLM provider mode (`local`, `cloud`). | `local` |
+| `--local-type <type>` | - | Local LLM server flavor (`ollama`, `lmstudio`). | `ollama` |
+| `--model <name>` | - | Name of the LLM model to compile. | - |
+| `--endpoint <url>` | - | The LLM API endpoint URL. | - |
+| `--api-key <key>` | - | API key for the cloud provider (OpenRouter). | - |
+| `-c, --com <ports>` | - | COM Port(s), comma-separated (e.g., `COM3` or `COM3,COM4`). | - |
+| `-b, --baud <rate>` | - | Serial transmission baud rate. | `9600` |
+| `--host <address>` | - | Target IP address or hostname (comma-separated for multi-device). | - |
+| `--port <port>` | - | Target connection port. | - |
+| `-u, --username <name>` | - | Device login username. | - |
+| `-p, --password <pass>` | - | Device login password. | - |
+| `--strict-command-ref` | - | Block commands not found in the `cf_command_ref.pdf` index. | `false` |
+| `--no-ref-telemetry` | - | Disable command-reference warmup telemetry logs. | `false` |
+| `--non-interactive` | - | Run without interactive prompts (auto-rejects dangerous commands). | `false` |
+| `--rbac-role <role>` | - | Specify the Active Agent RBAC authorization role (`admin`, `read_only`). | `admin` |
+
+---
+
+## 💡 Usage Examples
+
+### 1. Launching the Interactive Setup Wizard
+Start the interactive CLI configuration process:
 ```bash
-ciscollm run --protocol mock --goal "Review LAN IP allocation for 192.168.1.0/24"
+ciscollm run
 ```
 
-## What It Does
-
-The CLI takes a user goal, sends it to the selected LLM provider, and lets the agent choose Cisco IOS tool calls step by step.
-
-It can:
-- inspect and modify Cisco-style configuration
-- validate commands with guardrails
-- roll back failed configuration changes
-- simulate interfaces, IP addresses, shell commands, and ping checks in mock mode
-
-## Common Usage
-
-Start a mock session for learning or testing:
-
+### 2. Running a Quick Mock Simulation
 ```bash
-ciscollm run --protocol mock --goal "Configure 192.168.1.1/24 on LAN A for 25 hosts"
+ciscollm run --protocol mock --goal "Configure GigabitEthernet0/1 with IP 192.168.2.1/24 and interface description 'LAN B'"
 ```
 
-Use a local LLM endpoint:
-
+### 3. Local Model (Ollama)
 ```bash
-ciscollm run --provider local --local-type lmstudio --endpoint http://127.0.0.1:1234/v1 --protocol mock --goal "Open privileged exec and review IP design"
+ciscollm run --provider local --local-type ollama --endpoint http://127.0.0.1:11434/v1 --model qwen3.5-4b --protocol mock --goal "Show IP routing table"
 ```
 
-Use cloud inference with an API key:
-
+### 4. Cloud Inference via OpenRouter
 ```bash
-ciscollm run --provider cloud --api-key YOUR_OPENROUTER_KEY --protocol mock --goal "Check interface status"
+ciscollm run --provider cloud --api-key YOUR_OPENROUTER_API_KEY --protocol mock --goal "Verify interface states"
 ```
 
-Enable strict command-reference enforcement:
-
-```bash
-ciscollm run --strict-command-ref --protocol mock --goal "Review LAN design"
-```
-
-Disable startup telemetry if you want quieter output:
-
+### 5. Enforcing Strict Validation Mode
 ```bash
-ciscollm run --no-ref-telemetry --protocol mock --goal "Review LAN design"
+ciscollm run --strict-command-ref --protocol mock --goal "Configure router ospf 1 and advertise network 192.168.1.0/24"
 ```
 
-## Command Options
+---
 
-- `--protocol <type>`: Selects the device connection mode. Supported values: `serial`, `ssh`, `telnet`, `mock`.
-- `--provider <type>`: Selects the LLM provider. Supported values: `local`, `cloud`.
-- `--local-type <type>`: Chooses the local LLM server flavor. Supported values: `ollama`, `lmstudio`.
-- `--endpoint <url>`: Sets the LLM API endpoint.
-- `--model <name>`: Sets the model name to use.
-- `--strict-command-ref`: Blocks commands that are not found in the command-reference index.
-- `--no-ref-telemetry`: Turns off command-reference startup telemetry.
-- `--goal <intent>`: Describes the configuration or troubleshooting task.
+## 💻 Development & Contribution
 
-## Local LLM Notes
+Follow these steps to set up the project locally for development:
 
-If you use a local provider, make sure the endpoint is already running before starting the CLI.
-
-- Ollama usually listens on `http://127.0.0.1:11434/v1`
-- LM Studio usually listens on `http://127.0.0.1:1234/v1`
-
-If the endpoint is unavailable, the CLI will stop early with a clear preflight error.
-
-## Mock Mode
-
-Mock mode is designed for safe offline testing.
-
-It simulates:
-- device connection and prompt modes
-- interface configuration
-- ping behavior
-- command parsing errors
-- shell variable and function behavior
-
-This is the recommended mode when you want to test agent behavior without hardware.
-
-## Troubleshooting
+### 1. Clone & Install Dependencies
+```bash
+git clone https://github.com/ThemeHackers/ciscollm-cli.git
+cd ciscollm-cli
+npm install
+```
 
-- If you see `ENEEDAUTH`, you are not logged into npm with an account that can publish or access the package.
-- If the CLI says the LLM endpoint is unreachable, start the local server or update `--endpoint`.
-- If a command is blocked in strict mode, it was not matched in the command-reference index.
+### 2. Build the Project
+Compile the TypeScript code to target JavaScript inside `dist/`:
+```bash
+npm run build
+```
 
-## Package Name
+### 3. Run Development Build
+Run the CLI locally from source code:
+```bash
+npm start -- run --protocol mock --goal "Show running config"
+```
 
-The package name on npm is `ciscollm-cli`, and it exposes the `ciscollm` executable through the package `bin` entry.
+### 4. Run Unit Tests
+Validate features including the Command Firewall, Transaction Manager, and Error Analyzer:
+```bash
+npm run test
+```

package/dist/cli/ui/ui.d.ts

@@ -6,5 +6,6 @@ export declare const logger: {
     error: (msg: string) => void;
     critical: (msg: string) => void;
     heading: (msg: string) => void;
+    reasoning: (msg: string) => void;
 };
 export declare function createSpinner(text: string): ora.Ora;

package/dist/cli/ui/ui.js

@@ -8,12 +8,27 @@ exports.createSpinner = createSpinner;
 const chalk_1 = __importDefault(require("chalk"));
 const ora_1 = __importDefault(require("ora"));
 exports.logger = {
-    info: (msg) => console.log(chalk_1.default.blue('ℹ ') + msg),
-    success: (msg) => console.log(chalk_1.default.green('✔ ') + chalk_1.default.bold(msg)),
+    info: (msg) => console.log(chalk_1.default.cyan('ℹ ') + msg),
+    success: (msg) => console.log(chalk_1.default.green('✔ ') + chalk_1.default.bold.green(msg)),
     warn: (msg) => console.warn(chalk_1.default.yellow('⚠ ') + chalk_1.default.yellow(msg)),
     error: (msg) => console.error(chalk_1.default.red('✖ ') + chalk_1.default.red.bold(msg)),
-    critical: (msg) => console.error(chalk_1.default.bgRed.white.bold(' CRITICAL ') + ' ' + chalk_1.default.red(msg)),
-    heading: (msg) => console.log('\n' + chalk_1.default.cyan.bold.underline(msg) + '\n')
+    critical: (msg) => {
+        console.error('\n' + chalk_1.default.bgRed.black.bold(' ⚡ CRITICAL ERROR ') + ' ' + chalk_1.default.red.bold(msg) + '\n');
+    },
+    heading: (msg) => {
+        const line = '━'.repeat(msg.length + 6);
+        console.log('\n' + chalk_1.default.magenta.bold(`  ┏${line}┓`));
+        console.log(chalk_1.default.magenta.bold(`  ┃  ${chalk_1.default.white.bold(msg)}  ┃`));
+        console.log(chalk_1.default.magenta.bold(`  ┗${line}┛`) + '\n');
+    },
+    reasoning: (msg) => {
+        const border = chalk_1.default.blue('│');
+        console.log('\n' + chalk_1.default.blue('┌─── 🤖 Agent Reasoning Thought Process ───────────────────────'));
+        msg.trim().split('\n').forEach(line => {
+            console.log(`${border}  ${chalk_1.default.gray.italic(line)}`);
+        });
+        console.log(chalk_1.default.blue('└─────────────────────────────────────────────────────────────') + '\n');
+    }
 };
 function createSpinner(text) {
     return (0, ora_1.default)({

package/dist/cli/ui/ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../../src/cli/ui/ui.ts"],"names":[],"mappings":";;;;;;AAYA,sCAMC;AAlBD,kDAA0B;AAC1B,8CAAsB;AAET,QAAA,MAAM,GAAG;IAClB,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;IAC1D,OAAO,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,eAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1E,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,eAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,eAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3E,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,eAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5E,QAAQ,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,GAAG,GAAG,eAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrG,OAAO,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,eAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;CACtF,CAAC;AAEF,SAAgB,aAAa,CAAC,IAAY;IACtC,OAAO,IAAA,aAAG,EAAC;QACP,IAAI;QACJ,KAAK,EAAE,MAAM;QACb,OAAO,EAAE,MAAM;KAClB,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../../src/cli/ui/ui.ts"],"names":[],"mappings":";;;;;;AA2BA,sCAMC;AAjCD,kDAA0B;AAC1B,8CAAsB;AAET,QAAA,MAAM,GAAG;IAClB,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;IAC1D,OAAO,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,eAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChF,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,eAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,eAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3E,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,eAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5E,QAAQ,EAAE,CAAC,GAAW,EAAE,EAAE;QACtB,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,eAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,GAAG,GAAG,eAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,EAAE,CAAC,GAAW,EAAE,EAAE;QACrB,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,eAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,eAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;QACpE,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1D,CAAC;IACD,SAAS,EAAE,CAAC,GAAW,EAAE,EAAE;QACvB,MAAM,MAAM,GAAG,eAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,eAAK,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC,CAAC;QAClG,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;YAClC,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,KAAK,eAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,gEAAgE,CAAC,GAAG,IAAI,CAAC,CAAC;IACrG,CAAC;CACJ,CAAC;AAEF,SAAgB,aAAa,CAAC,IAAY;IACtC,OAAO,IAAA,aAAG,EAAC;QACP,IAAI;QACJ,KAAK,EAAE,MAAM;QACb,OAAO,EAAE,MAAM;KAClB,CAAC,CAAC;AACP,CAAC"}

package/dist/core/agent/AgentLoop.d.ts

@@ -3,6 +3,7 @@ import { MultiAgentCoordinator } from './MultiAgentCoordinator';
 type AgentLoopOptions = {
     strictReferenceMode?: boolean;
     referenceTelemetry?: boolean;
+    rbacRole?: string;
 };
 export declare class CiscoAgentLoop {
     private llmClient;
@@ -15,17 +16,22 @@ export declare class CiscoAgentLoop {
     private commandReferenceEngine;
     private strictReferenceMode;
     private referenceTelemetry;
+    private rbacRole;
     private options;
     private validationNudgeCount;
+    private lastTopologyDiscoveryAt;
+    private readonly topologyRefreshIntervalMs;
     constructor(llmClient: LLMClient, coordinator: MultiAgentCoordinator, options?: AgentLoopOptions);
     private applyOptions;
     run(userGoal: string): Promise<void>;
+    private buildTopologyInfoString;
     private triggerAutomaticValidationPing;
     private resolveValidationDestination;
     private buildStateInfoString;
     private findLastMutatedDevice;
     private resolveTargetDevice;
     private handleExecuteCommandCall;
+    private captureDeviceSnapshot;
     private handleEnableIosShellCall;
     private handleDefineShellVariableCall;
     private handleExecuteShellLoopCall;

package/dist/core/agent/AgentLoop.js

@@ -13,6 +13,10 @@ const ToolDefinitions_1 = require("../../infrastructure/llm/ToolDefinitions");
 const child_process_1 = require("child_process");
 const ui_1 = require("../../cli/ui/ui");
 const chalk_1 = __importDefault(require("chalk"));
+const PreExecutionValidator_1 = require("../guardrails/PreExecutionValidator");
+const AuditLogger_1 = require("../guardrails/AuditLogger");
+const HierarchicalAgentManager_1 = require("./HierarchicalAgentManager");
+const StateDiff_1 = require("../rollback/StateDiff");
 class CiscoAgentLoop {
     llmClient;
     coordinator;
@@ -24,8 +28,11 @@ class CiscoAgentLoop {
     commandReferenceEngine = CommandReferenceEngine_1.CommandReferenceEngine.getInstance();
     strictReferenceMode = false;
     referenceTelemetry = true;
+    rbacRole = 'admin';
     options;
     validationNudgeCount = 0;
+    lastTopologyDiscoveryAt = 0;
+    topologyRefreshIntervalMs = 15000;
     constructor(llmClient, coordinator, options = {}) {
         this.llmClient = llmClient;
         this.coordinator = coordinator;
@@ -39,6 +46,9 @@ class CiscoAgentLoop {
         if (typeof options.strictReferenceMode === 'boolean') {
             this.commandReferenceEngine.setStrictMode(options.strictReferenceMode);
         }
+        if (options.rbacRole) {
+            this.rbacRole = options.rbacRole.toLowerCase();
+        }
     }
     async run(userGoal) {
         const backupSpinner = (0, ui_1.createSpinner)('Initializing device configuration backups to flash...').start();
@@ -72,9 +82,10 @@ class CiscoAgentLoop {
             refSpinner.warn('Cisco command reference hints unavailable. Continuing with base policy.');
         }
         const stateInfo = this.buildStateInfoString();
+        const topologyInfo = await this.buildTopologyInfoString();
         this.messages.push({
             role: 'system',
-            content: PromptEngine_1.PromptEngine.getSystemPrompt(stateInfo, this.commandHints, this.strictReferenceMode)
+            content: PromptEngine_1.PromptEngine.getSystemPrompt(stateInfo, this.commandHints, this.strictReferenceMode, topologyInfo)
         });
         this.messages.push({ role: 'user', content: userGoal });
         let dynamicLoopActive = true;
@@ -83,9 +94,10 @@ class CiscoAgentLoop {
         while (dynamicLoopActive && executionDepth < MAX_STEPS) {
             executionDepth++;
             const updatedStateInfo = this.buildStateInfoString();
+            const updatedTopologyInfo = await this.buildTopologyInfoString();
             this.messages[0] = {
                 role: 'system',
-                content: PromptEngine_1.PromptEngine.getSystemPrompt(updatedStateInfo, this.commandHints, this.strictReferenceMode)
+                content: PromptEngine_1.PromptEngine.getSystemPrompt(updatedStateInfo, this.commandHints, this.strictReferenceMode, updatedTopologyInfo)
             };
             let shellEnabled = false;
             for (const session of this.coordinator.getSessions().values()) {
@@ -109,11 +121,7 @@ class CiscoAgentLoop {
                 modelSpinner.succeed(`[Step ${executionDepth}/${MAX_STEPS}] Thinking complete.`);
                 const thoughts = response.reasoning_content || response.content;
                 if (thoughts && thoughts.trim()) {
-                    console.log(chalk_1.default.gray('  ' + '─'.repeat(40)));
-                    thoughts.trim().split('\n').forEach(line => {
-                        console.log(chalk_1.default.dim(`  | ${line}`));
-                    });
-                    console.log(chalk_1.default.gray('  ' + '─'.repeat(40)));
+                    ui_1.logger.reasoning(thoughts);
                 }
             }
             catch (err) {
@@ -173,6 +181,21 @@ class CiscoAgentLoop {
             ui_1.logger.warn('Maximum loop steps limit reached.');
         }
     }
+    async buildTopologyInfoString() {
+        const now = Date.now();
+        if (now - this.lastTopologyDiscoveryAt > this.topologyRefreshIntervalMs) {
+            await this.coordinator.discoverTopology();
+            this.lastTopologyDiscoveryAt = now;
+        }
+        const topology = this.coordinator.getTopology();
+        if (topology.links.length === 0) {
+            return `Discovered at: ${topology.discoveredAt}\nNodes: ${topology.nodes.join(', ') || '(none)'}\nLinks: none`;
+        }
+        const links = topology.links
+            .map(link => `- ${link.localDeviceId} [${link.localInterface}] <-> ${link.remoteDeviceId} [${link.remoteInterface}] via ${link.protocol.toUpperCase()}`)
+            .join('\n');
+        return `Discovered at: ${topology.discoveredAt}\nNodes: ${topology.nodes.join(', ')}\n${links}`;
+    }
     async triggerAutomaticValidationPing(deviceId) {
         const destination = await this.resolveValidationDestination(deviceId);
         const fallbackCall = {
@@ -206,7 +229,6 @@ class CiscoAgentLoop {
             }
         }
         catch {
-            // Fall through to safe default.
         }
         return '127.0.0.1';
     }
@@ -257,6 +279,26 @@ class CiscoAgentLoop {
         const targetCommand = args.command;
         const requestedDevice = args.device;
         const cleanCommand = targetCommand.trim();
+        const assignedRole = HierarchicalAgentManager_1.HierarchicalAgentManager.routeCommand(cleanCommand);
+        if (this.rbacRole === 'read_only') {
+            const lower = cleanCommand.toLowerCase();
+            const allowedReadOnlyPatterns = [/^show\s+/i, /^ping\s+/i, /^dir\s+/i, /^terminal\s+/i, /^exit$/i, /^end$/i];
+            const isAllowedReadOnly = allowedReadOnlyPatterns.some(p => p.test(lower));
+            if (!isAllowedReadOnly) {
+                ui_1.logger.warn(`[RBAC BLOCK] Read-Only role blocked command: "${cleanCommand}"`);
+                this.injectToolResponse(call.id, 'execute_ios_command', `CRITICAL ERROR: RBAC policy violation. Your current role is READ_ONLY and you are blocked from executing modifying command "${cleanCommand}".`);
+                AuditLogger_1.AuditLogger.log({
+                    timestamp: new Date().toISOString(),
+                    deviceId: requestedDevice || 'unknown',
+                    role: this.rbacRole,
+                    thought: this.messages[this.messages.length - 1]?.content || '',
+                    command: cleanCommand,
+                    status: 'BLOCKED',
+                    reason: 'RBAC role is READ_ONLY'
+                });
+                return;
+            }
+        }
         const commandValidation = await this.commandReferenceEngine.validateCommand(cleanCommand);
         if (this.strictReferenceMode && !commandValidation.allowed) {
             const suggestions = commandValidation.suggestions.length
@@ -273,6 +315,26 @@ class CiscoAgentLoop {
             this.injectToolResponse(call.id, 'execute_ios_command', `Error: ${err.message}`);
             return;
         }
+        const tx = this.transactions.get(targetDeviceId);
+        const currentInterface = tx ? tx.targetInterface : null;
+        const dryRunCheck = PreExecutionValidator_1.PreExecutionValidator.validateCommand(cleanCommand, targetDeviceId, this.coordinator.getTopology(), currentInterface);
+        if (dryRunCheck.warnLevel === 'CRITICAL' || !dryRunCheck.safe) {
+            ui_1.logger.warn(`[PRE-EXECUTION WARNING] Critical risk detected: ${dryRunCheck.reason}`);
+            const allowed = await this.firewall.verifyWithHuman(cleanCommand, dryRunCheck.reason || 'High risk context');
+            if (!allowed) {
+                this.injectToolResponse(call.id, 'execute_ios_command', `CRITICAL ERROR: Pre-execution validation blocked this command. Reason: ${dryRunCheck.reason}`);
+                AuditLogger_1.AuditLogger.log({
+                    timestamp: new Date().toISOString(),
+                    deviceId: targetDeviceId,
+                    role: this.rbacRole,
+                    thought: this.messages[this.messages.length - 1]?.content || '',
+                    command: cleanCommand,
+                    status: 'BLOCKED',
+                    reason: dryRunCheck.reason
+                });
+                return;
+            }
+        }
         const lastCmdInfo = this.lastCommandPerDevice[targetDeviceId];
         if (lastCmdInfo && lastCmdInfo.command === cleanCommand) {
             lastCmdInfo.count++;
@@ -285,8 +347,6 @@ class CiscoAgentLoop {
             this.injectToolResponse(call.id, 'execute_ios_command', `CRITICAL ERROR: Loop check block. You have run "${cleanCommand}" multiple times with errors. Re-verify your settings before retrying.`);
             return;
         }
-        const tx = this.transactions.get(targetDeviceId);
-        const currentInterface = tx ? tx.targetInterface : null;
         const firewallResult = this.firewall.checkCommand(cleanCommand, currentInterface);
         if (firewallResult.dangerous) {
             const allowed = await this.firewall.verifyWithHuman(cleanCommand, firewallResult.reason || 'High-risk token');
@@ -298,10 +358,10 @@ class CiscoAgentLoop {
         if (tx) {
             tx.trackMutation(cleanCommand);
         }
-        const cmdSpinner = (0, ui_1.createSpinner)(`[${targetDeviceId}] Executing command: "${cleanCommand}"...`).start();
+        const snapshotA = await this.captureDeviceSnapshot(targetDeviceId);
+        const cmdSpinner = (0, ui_1.createSpinner)(`[${targetDeviceId}] [Agent: ${assignedRole}] Executing command: "${cleanCommand}"...`).start();
         try {
             const session = this.coordinator.getSession(targetDeviceId);
-            // Normalize context for read-only inspection commands to avoid mode-related failures.
             const state = session.getState();
             if (/^show\s+/i.test(cleanCommand) && (state.currentMode === 'GLOBAL_CONFIG' || state.currentMode === 'INTERFACE_CONFIG')) {
                 await session.execute('end');
@@ -317,11 +377,38 @@ class CiscoAgentLoop {
                     rollbackLogs = await tx.executeRollback(session);
                 }
                 rbSpinner.succeed(`[${targetDeviceId}] Rollback execution complete.`);
+                AuditLogger_1.AuditLogger.log({
+                    timestamp: new Date().toISOString(),
+                    deviceId: targetDeviceId,
+                    role: this.rbacRole,
+                    thought: this.messages[this.messages.length - 2]?.content || '',
+                    command: cleanCommand,
+                    status: 'ROLLBACK',
+                    reason: `Rollback triggered by error ${verification.errorType}. Reverted state successfully.`
+                });
                 this.injectToolResponse(call.id, 'execute_ios_command', `IOS Error [${verification.errorType}]:\n${processedOutput}\n\nAutomated configuration rollback executed:\n${rollbackLogs}`);
             }
             else {
                 cmdSpinner.succeed(`[${targetDeviceId}] Command completed: "${cleanCommand}"`);
-                this.injectToolResponse(call.id, 'execute_ios_command', processedOutput);
+                const snapshotB = await this.captureDeviceSnapshot(targetDeviceId);
+                let diffSummary = '';
+                if (snapshotA && snapshotB) {
+                    const diffResult = StateDiff_1.StateDiff.diff(snapshotA, snapshotB);
+                    diffSummary = StateDiff_1.StateDiff.renderDiff(diffResult);
+                    if (diffSummary && diffSummary !== 'No configuration differences detected.') {
+                        ui_1.logger.info(`[State Diff for ${targetDeviceId}]:\n${diffSummary}`);
+                    }
+                }
+                AuditLogger_1.AuditLogger.log({
+                    timestamp: new Date().toISOString(),
+                    deviceId: targetDeviceId,
+                    role: this.rbacRole,
+                    thought: this.messages[this.messages.length - 2]?.content || '',
+                    command: cleanCommand,
+                    status: 'SUCCESS',
+                    outputSnippet: `${processedOutput}${diffSummary ? `\nState Changes:\n${diffSummary}` : ''}`
+                });
+                this.injectToolResponse(call.id, 'execute_ios_command', processedOutput + (diffSummary ? `\n\n[State Diff Configured]:\n${diffSummary}` : ''));
             }
         }
         catch (error) {
@@ -329,6 +416,41 @@ class CiscoAgentLoop {
             this.injectToolResponse(call.id, 'execute_ios_command', `Hardware Session Fault: ${error.message}`);
         }
     }
+    async captureDeviceSnapshot(deviceId) {
+        const session = this.coordinator.getSession(deviceId);
+        if (!session)
+            return null;
+        if (typeof session.interfaces !== 'undefined') {
+            const mock = session;
+            const interfaceList = [];
+            for (const [name, conf] of mock.interfaces.entries()) {
+                interfaceList.push({
+                    name,
+                    ip: conf.ip,
+                    subnet: conf.subnet,
+                    adminShutdown: conf.adminShutdown,
+                    lineProtocolUp: conf.lineProtocolUp,
+                    description: conf.description
+                });
+            }
+            return {
+                deviceId,
+                timestamp: new Date().toISOString(),
+                sessionState: session.getState(),
+                interfaces: interfaceList,
+                routes: [...mock.routes],
+                vlans: Array.from(mock.vlans)
+            };
+        }
+        return {
+            deviceId,
+            timestamp: new Date().toISOString(),
+            sessionState: session.getState(),
+            interfaces: [],
+            routes: [],
+            vlans: []
+        };
+    }
     async handleEnableIosShellCall(call) {
         let args;
         try {
@@ -523,8 +645,8 @@ class CiscoAgentLoop {
     async pingFromHost(destination) {
         return new Promise((resolve) => {
             const isWindows = process.platform === 'win32';
-            const cmd = isWindows ? `ping -n 4 ${destination}` : `ping -c 4 ${destination}`;
-            (0, child_process_1.exec)(cmd, (error, stdout, stderr) => {
+            const pingArgs = isWindows ? ['-n', '4', destination] : ['-c', '4', destination];
+            (0, child_process_1.execFile)('ping', pingArgs, (error, stdout, stderr) => {
                 if (error) {
                     resolve(`PING FAILED:\n${stdout || stderr || error.message}`);
                     return;