fluxflow-cli 1.0.1 → 1.0.2

package/TOOLS.md

@@ -0,0 +1,48 @@
+# 🧰 Agent Tools & Capabilities
+
+Flux Flow provides a robust set of tools that allow the AI to interact with the file system, execute code, and search the web. The availability of these tools depends on the active operating mode.
+
+## Tool Availability by Mode
+
+| Tool | Flux Mode (Dev) | Flow Mode (Chat) |
+| :--- | :---: | :---: |
+| **Web Search** | ✅ | ✅ |
+| **Web Scrape** | ✅ | ✅ |
+| **View/Read Files** | ✅ | ❌ |
+| **Write/Update Files** | ✅ | ❌ |
+| **Execute Commands** | ✅ | ❌ |
+
+---
+
+## Core Tools
+
+### 🌐 Web & Research
+- **`web_search`**: Uses DuckDuckGo to find up-to-date information on the internet. Crucial for answering questions about recent events or unlearned documentation.
+- **`web_scrape`**: Extracts the detailed text content from a specific URL, allowing the agent to read documentation or articles.
+
+### 📁 File System Operations
+- **`list_files`**: Lists the contents of a directory to help the agent understand the project structure.
+- **`read_folder`**: Provides detailed statistics and metadata about a directory's contents.
+- **`view_file`**: Reads the content of a file. Supports reading specific line ranges (`start_line`, `end_line`) to manage context size efficiently.
+
+### ✍️ Code Editing
+- **`write_file`**: Creates a new file or completely overwrites an existing one with new content.
+- **`update_file` (Smart Patching)**: Surgically replaces a specific block of text within a file. 
+  - *Diff Generation*: It returns a high-fidelity visual diff (Red/Green changes with context lines) to the UI, allowing the user to see exactly what the agent modified.
+
+### 💻 Terminal Execution
+- **`exec_command`**: Runs a shell command directly in the terminal using Node's `child_process.spawn`. 
+  - *Context Aware*: Runs in the current working directory.
+  - *Cross-Platform*: Uses `shell: true` to handle Windows `.cmd`/`.bat` files natively.
+
+---
+
+## Memory Management
+
+The memory tool (`memory.js`) is primarily used by the background **Janitor** model, but can be accessed by the main agent if necessary.
+
+- **Temporary Context (`action='temp'`)**: Saves a rolling summary of the current session to maintain conversational context without bloating the main prompt history.
+- **Persistent User Memory (`action='user'`)**: 
+  - The Janitor analyzes conversations to detect user preferences, hobbies, or instructions.
+  - It uses `add`, `update`, or `delete` methods to manage facts in the encrypted `memories.json` vault.
+  - These memories are injected into the system prompt of *future* sessions, allowing Flux Flow to learn and adapt to the user over time.

package/UI_FEATURES.md

@@ -0,0 +1,66 @@
+# 🎮 User Interface & Interaction Features
+
+Flux Flow is designed to be a high-performance terminal application. Beyond basic chat, it includes a variety of advanced UI features and human-in-the-loop controls to keep you in command of the agent.
+
+## ⌨️ Command System
+
+You can control the application using `/` commands directly in the chat input:
+
+- **/mode [flux|flow]**: Quickly switch between **Flux** (Dev) and **Flow** (Chat) modes. Using it without arguments opens the selection menu.
+- **/thinking [low|medium|high|max|show|hide]**: Adjust reasoning depth or toggle visibility of the thinking process. Using it without arguments opens the selection menu.
+- **/model [name]**: Choose which AI model to use for the main interaction.
+- **/key**: Open the API Key management view to update or remove your credentials.
+- **/settings**: Access the system configuration menu.
+- **/profile**: Update your name, nickname, and custom instructions.
+- **/memory**: View and manage the persistent memories extracted by the Janitor.
+- **/resume <chat-id>**: Switch back to a previous conversation.
+- **/help**: List all available commands.
+
+### Command Shortcuts
+
+For power users, several commands support direct arguments to skip the menus:
+- ` /mode flux ` or ` /mode flow `
+- ` /thinking low ` / ` /thinking medium ` / ` /thinking high ` / ` /thinking max `
+- ` /thinking show ` / ` /thinking hide ` (Toggles thinking process visibility)
+- ` /model gemini-3.1-pro-preview ` (Switches model directly)
+
+## 🧠 Thinking Levels & Visualization
+
+Flux Flow separates the model's "internal monologue" (reasoning) from its final response using `<think>` tags.
+
+- **Thinking Levels**: Depending on the mode, you can choose from **Low**, **Medium**, **High**, or **Max**. Higher levels allow the agent more "space" to reason through complex architecture or debugging problems.
+- **Show/Hide Thinking**: You can toggle the visibility of the thinking process using `/thinking show/hide`. 
+  - When **Hidden**, the agent doesn't just disappear; it provides a "minimalist" view showing only the core **Headings** and **Action Steps** (bolded lines) from its reasoning. This keeps you informed of its current "step" without cluttering the screen with detailed internal monologue.
+
+## 🛡️ Human-in-the-Loop (HITL) Verification
+
+Security and safety are paramount when an AI has access to your file system and terminal. Flux Flow implements several layers of verification:
+
+### Tool Approval
+By default, the agent **cannot** execute dangerous actions without your consent.
+- **Terminal Approval**: If the agent attempts to run a shell command (`exec_command`), a dedicated approval screen appears showing the exact command. You can **Allow** or **Deny** the execution.
+- **File Approval**: Similar to terminal commands, writing or updating files requires manual approval unless configured otherwise.
+- **Safe Commands**: Basic read-only commands (like `ls`, `git status`, `pwd`) are automatically allowed to minimize friction.
+
+### Auto-Execution (Advanced)
+For power users, **Auto-Exec** can be enabled in `/settings`. 
+- **⚠️ Warning**: This allows the agent to run any tool and execute any command autonomously.
+- **External Access**: You can also toggle whether the agent is allowed to access files outside of its current working directory.
+
+## 🔄 Steering & Resolution
+
+### Real-time Steering
+If you realize the agent is going down the wrong path *while* it is in an agentic loop, you can provide "Steering Hints." The system will inject your feedback into the next loop to course-correct the agent.
+
+### Resolution Modal
+If the agent finishes its task just as you send a steering hint, a **Resolution Modal** appears. It asks if you want to:
+- **Send Anyway**: Start a new loop with your feedback.
+- **Edit Prompt**: Refine your feedback before sending.
+
+## 📊 Status Bar & Feedback
+The bottom of the screen features a dynamic status bar showing:
+- **Active Mode** (Flux/Flow)
+- **Thinking Level**
+- **Token Usage**: Real-time tracking of tokens used in the current session.
+- **Agentic Loops**: Counters showing how many times the agent has "looped" to solve the current task.
+- **API Status**: Visual feedback when the model is thinking or executing a tool.

package/dist/{index.js → fluxflow.js}

@@ -194,7 +194,7 @@ function StatusBar({ mode, thinkingLevel, tokens = "0.0k", chatId = "NEW-SESSION
     },
     /* @__PURE__ */ React3.createElement(Box3, null, /* @__PURE__ */ React3.createElement(Text3, { color: modeColor, bold: true }, modeIcon, " ", mode.toUpperCase()), /* @__PURE__ */ React3.createElement(Text3, { color: "gray" }, " \u2502 "), /* @__PURE__ */ React3.createElement(Text3, { color: "magenta" }, "\u{1F9E0} ", thinkingLevel)),
     /* @__PURE__ */ React3.createElement(Box3, { flexGrow: 1, justifyContent: "center", paddingX: 2 }, /* @__PURE__ */ React3.createElement(Text3, { color: "gray", dimColor: true }, "\u{1F4C1} "), /* @__PURE__ */ React3.createElement(Text3, { color: "blue", dimColor: true, italic: true }, process.cwd())),
-    /* @__PURE__ */ React3.createElement(Box3, null, /* @__PURE__ */ React3.createElement(Text3, { color: "gray" }, "MEM: "), /* @__PURE__ */ React3.createElement(Text3, { color: memStatus === "ON" ? "green" : "red" }, memStatus), /* @__PURE__ */ React3.createElement(Text3, { color: "gray" }, " \u2502 "), /* @__PURE__ */ React3.createElement(Text3, { color: "blue" }, " Tokens ", tokens > 1e3 ? `${(tokens / 1e3).toFixed(1)}k` : tokens, " (", Math.round(tokens / 128e3 * 100), "%)"), /* @__PURE__ */ React3.createElement(Text3, { color: "gray" }, " \u2502 "), /* @__PURE__ */ React3.createElement(Text3, { color: "dim" }, "ID: ", chatId, " "))
+    /* @__PURE__ */ React3.createElement(Box3, null, /* @__PURE__ */ React3.createElement(Text3, { color: "gray" }, "MEM: "), /* @__PURE__ */ React3.createElement(Text3, { color: memStatus === "ON" ? "green" : "red" }, memStatus), /* @__PURE__ */ React3.createElement(Text3, { color: "gray" }, " \u2502 "), /* @__PURE__ */ React3.createElement(Text3, { color: "blue" }, " Tokens ", tokens > 1e3 ? `${(tokens / 1e3).toFixed(1)}k` : tokens, " (", Math.round(tokens / 196e3 * 100), "%)"), /* @__PURE__ */ React3.createElement(Text3, { color: "gray" }, " \u2502 "), /* @__PURE__ */ React3.createElement(Text3, { color: "dim" }, "ID: ", chatId, " "))
   );
 }
 
@@ -795,7 +795,7 @@ var memory = async (rawArgs, context = {}) => {
     if (!content) return "ERROR: Missing 'content' for temp memory.";
     const tempStorage = readEncryptedJson(TEMP_MEM_PATH, {});
     if (!tempStorage[chatId]) tempStorage[chatId] = [];
-    const MAX_CHARS = 4e3 * 4;
+    const MAX_CHARS = 3e3 * 4;
     let currentTotalLength = tempStorage[chatId].reduce((acc, m) => acc + m.length, 0);
     while (tempStorage[chatId].length > 0 && currentTotalLength + content.length > MAX_CHARS) {
       const removed = tempStorage[chatId].shift();
@@ -809,7 +809,7 @@ var memory = async (rawArgs, context = {}) => {
     const memories = readEncryptedJson(MEMORIES_PATH, []);
     if (method === "add") {
       if (!content) return "ERROR: Missing 'content' for memory addition.";
-      const MAX_CHARS = 3e3 * 4;
+      const MAX_CHARS = 2e3 * 4;
       let currentTotalLength = memories.reduce((acc, m) => acc + (m.memory?.length || 0), 0);
       while (memories.length > 0 && currentTotalLength + content.length > MAX_CHARS) {
         const removed = memories.shift();
@@ -1285,7 +1285,7 @@ var getAIStream = async function* (modelName, history, settings, steeringCallbac
   const needTitle = isFirstPrompt || hasTitleSignal;
   const agentText = originalText.replace(/\[TITLE-UPDATE\]/g, "").trim();
   let modifiedHistory = [...history.slice(0, -1)];
-  if (systemSettings?.compression === 0 && (sessionStats?.tokens || 0) > 128e3) {
+  if (systemSettings?.compression === 0 && (sessionStats?.tokens || 0) > 196e3) {
     modifiedHistory = getTruncatedHistory(modifiedHistory, 4);
   }
   const tempStorage = readEncryptedJson(TEMP_MEM_PATH2, {});
@@ -1394,7 +1394,17 @@ USER_PROMPT: ${agentText}`.trim();
           const url = parseArgs(toolCall.args).url || "...";
           label = `\u{1F4D6} READING SITE: ${url}`.toUpperCase();
         } else if (toolCall.toolName === "view_file") {
-          label = `\u{1F4C4} READING FILE: ${parseArgs(toolCall.args).path || "..."}`.toUpperCase();
+          const { path: targetPath2, start_line = 1, end_line = 500 } = parseArgs(toolCall.args);
+          let totalLines = "...";
+          try {
+            const absPath = path13.resolve(process.cwd(), targetPath2);
+            if (fs12.existsSync(absPath)) {
+              const content = fs12.readFileSync(absPath, "utf8");
+              totalLines = content.split("\n").length;
+            }
+          } catch (e) {
+          }
+          label = `\u{1F4C4} READING FILE: ${targetPath2}. LINES ${start_line} - ${end_line} FROM ${totalLines}`.toUpperCase();
         } else if (toolCall.toolName === "list_files" || toolCall.toolName === "read_folder") {
           const action = toolCall.toolName === "list_files" ? "LISTING" : "DISCOVERING";
           label = `\u{1F4C2} ${action} DIRECTORY: ${parseArgs(toolCall.args).path || "."}`.toUpperCase();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "fluxflow-cli",
-	"version": "1.0.1",
+	"version": "1.0.2",
 	"description": "A high-fidelity agentic terminal assistant for the Flux Era.",
 	"keywords": [
 		"ai",
@@ -23,15 +23,18 @@
 		"dist",
 		"README.md",
 		"package.json",
-		"ARCHITECTURE.md"
+		"ARCHITECTURE.md",
+		"TOOLS.md",
+		"UI_FEATURES.md"
 	],
 	"type": "module",
 	"bin": {
-		"fluxflow-cli": "dist/index.js"
+		"fluxflow-cli": "dist/fluxflow.js",
+		"fluxflow": "dist/fluxflow.js"
 	},
 	"scripts": {
 		"start": "tsx ./src/cli.jsx",
-		"build": "esbuild ./src/cli.jsx --bundle --platform=node --format=esm --outfile=./dist/index.js --external:react --external:ink --external:chalk --external:fs-extra --external:gradient-string --external:ink-text-input --external:ink-select-input --external:ink-spinner --external:ink-multiline-input --external:@google/genai --external:zod --external:duck-duck-scrape --external:nanoid --external:cuimp"
+		"build": "esbuild ./src/cli.jsx --bundle --platform=node --format=esm --outfile=./dist/fluxflow.js --external:react --external:ink --external:chalk --external:fs-extra --external:gradient-string --external:ink-text-input --external:ink-select-input --external:ink-spinner --external:ink-multiline-input --external:@google/genai --external:zod --external:duck-duck-scrape --external:nanoid --external:cuimp"
 	},
 	"dependencies": {
 		"@google/genai": "^1.50.1",