fluxflow-cli 1.8.19 → 1.8.21

package/ARCHITECTURE.md

@@ -1,65 +1,65 @@
-# 🏛️ Architecture & Design
-
-Flux Flow is built on a modern, reactive stack that brings web-like development paradigms to the terminal. It utilizes a custom agentic loop for reasoning and a unique dual-model system for background processing.
-
-## UI Layer: React & Ink
-
-The entire terminal interface is built using **React** via the [Ink](https://github.com/vadimdemedes/ink) renderer.
-- **Component-Based**: The UI is composed of isolated, reusable React components (`ChatLayout`, `StatusBar`, `CommandMenu`, `TerminalBox`, `ProfileForm`).
-- **Reactive State**: The application uses React hooks (`useState`, `useEffect`) to manage user input, application mode, model selection, and the terminal's resizing events.
-- **Zero-Render Overheads**: Critical performance trackers, like the session start time, are kept outside the React render cycle to maintain terminal responsiveness during high-speed AI text streaming.
-
-## The Agentic Loop
-
-The core intelligence of Flux Flow resides in `src/utils/ai.js`. It does not rely on opaque third-party agent frameworks; instead, it uses a custom, highly transparent string-based protocol powered by an asynchronous generator (`async function*`). This approach allows for real-time UI updates while managing complex multi-step reasoning.
-
-The execution flow of a single user prompt follows this loop:
-
-1. **Context Assembly**: The user's prompt is combined with the system instructions, temporary session context, persistent user memories, and the current chat history. If the history gets too large (e.g., >128k tokens) and compression is disabled, it is gracefully truncated.
-2. **Stream Processing**: The main loop initiates a streaming request to the Gemini API (`client.models.generateContentStream`). It yields chunks of text and status updates directly back to the React UI as they arrive.
-3. **Detection & Tool Execution**: Once the stream completes for a given turn, the entire response is scanned for tool calls using a custom regex and bracket-balancing parser (looking for `tool:functions.tool_name(args...)`).
-   - If tools are found, the loop pauses.
-   - Each tool is dispatched to its respective handler in `src/tools/`.
-   - Tool outputs are collected and appended to the context as `[TOOL_RESULT]: ...`.
-4. **Security Governance**: During tool execution, the loop enforces security checks (e.g., blocking `exec_command` from accessing system root drives if "External Workspace Access" is off) and pauses for Human-in-the-Loop (HITL) approval if necessary.
-5. **Turn Management & Continuation**: The model is instructed to append `[turn: finish]` if its goal is complete, or `[turn: continue]` if it expects tool results.
-   - If tools were called or `[turn: continue]` is present, the loop increments and re-prompts the model with the newly gathered `[TOOL_RESULT]` data.
-   - If `[turn: finish]` is detected and no further tools were called, the main loop terminates, passing the final synthesized context to the background Janitor process.
-6. **Loop Limits & Resilience**: To prevent infinite loops or excessive API usage, **Flux mode** is capped at 50 iterations per user prompt, while **Flow mode** is capped at 5.
-   - **Multi-Stage Failover**: The loop features a sophisticated 8-attempt retry engine with random backoff (800ms - 2s).
-   - **Critical Fallback Pivot**: If the primary model fails 5 consecutive times, the agent surgically pivots to a lighter, high-concurrency fallback model (`gemini-3.1-flash-lite-preview`) for the final 3 attempts to ensure session navigation through API congestion.
-
-## Multimodal Pipeline
-
-Flux Flow implements a native multimodal processing engine in `src/tools/view_file.js`. This allows the agent to move beyond text-based reasoning and analyze visual assets directly.
-
-- **Binary Detection**: The pipeline uses `is-binary-path` to distinguish between text and binary files.
-- **Visual Encoding**: If an image or PDF is detected, the engine reads the raw bytes and converts them into base64-encoded `InlineData` objects.
-- **PDF Extraction**: For PDF documents, the engine extracts visual representation of pages to provide the model with high-fidelity spatial and textual context simultaneously.
-- **Context Injection**: These multimodal assets are injected directly into the Gemini model's multimodal part array, allowing the model to "see" the file as if it were looking at a screenshot.
-
-## The Dual-Model System
-
-To maintain a fast, snappy UI while still performing complex data management, Flux Flow employs two separate AI models for every interaction:
-
-### 1. The Main Agent
-- **Responsibility**: Direct user interaction, reasoning, and tool execution.
-- **Behavior**: Streams text directly to the UI. It focuses entirely on solving the user's immediate problem or answering their question.
-
-### 2. The Janitor (Background Process)
-- **Responsibility**: System maintenance, long-term memory extraction, and chat summarization.
-- **Behavior**: After the Main Agent finishes its loop, the entire context (User Prompt + Agent Raws) is sent to the Janitor model.
-- **Headless Operation**: The Janitor is explicitly instructed to be a "silent background system process" with "no mouth." It *only* outputs valid tool calls (e.g., updating the chat title or saving a new user preference to the persistent memory vault).
-
-## Data Persistence & Safety
-
-- **High-Fidelity Lock**: Because both the UI and the Janitor model may attempt to write to the `history.json` file simultaneously, a Promise-based `WRITE_LOCK` (`src/utils/history.js`) is utilized. This prevents race conditions and ensures data integrity.
-- **Encryption**: User secrets and persistent memories (`secret/memories.json`) are handled by `src/utils/crypto.js` to ensure local privacy.
-
-## Redirection & The Anchor Strategy
-
-To support data portability (e.g., storing all app data on an external encrypted drive), Flux Flow utilizes a synchronous "Anchor" strategy in `src/utils/paths.js`.
-
-- **Synchronous Pivot**: Because many core modules (History, Secrets, Usage) initialize their file paths as constants during module loading, the application must determine the "Actual" data root before anything else.
-- **Boot-Sequence Priority**: On every launch, `paths.js` performs a synchronous file system check for `~/.fluxflow/settings.json`. If a redirection path is found (`useExternalData: true`), it immediately overrides the global `DATA_DIR` constant for the entire process.
-- **Sub-Coordinate Resolution**: All secondary directories (`LOGS_DIR`, `SECRET_DIR`) are derived dynamically from the redirected `DATA_DIR`, ensuring that all session data flows to the external sanctuary without requiring individual configuration updates across the codebase.
+# 🏛️ Architecture & Design
+
+Flux Flow is built on a modern, reactive stack that brings web-like development paradigms to the terminal. It utilizes a custom agentic loop for reasoning and a unique dual-model system for background processing.
+
+## UI Layer: React & Ink
+
+The entire terminal interface is built using **React** via the [Ink](https://github.com/vadimdemedes/ink) renderer.
+- **Component-Based**: The UI is composed of isolated, reusable React components (`ChatLayout`, `StatusBar`, `CommandMenu`, `TerminalBox`, `ProfileForm`).
+- **Reactive State**: The application uses React hooks (`useState`, `useEffect`) to manage user input, application mode, model selection, and the terminal's resizing events.
+- **Zero-Render Overheads**: Critical performance trackers, like the session start time, are kept outside the React render cycle to maintain terminal responsiveness during high-speed AI text streaming.
+
+## The Agentic Loop
+
+The core intelligence of Flux Flow resides in `src/utils/ai.js`. It does not rely on opaque third-party agent frameworks; instead, it uses a custom, highly transparent string-based protocol powered by an asynchronous generator (`async function*`). This approach allows for real-time UI updates while managing complex multi-step reasoning.
+
+The execution flow of a single user prompt follows this loop:
+
+1. **Context Assembly**: The user's prompt is combined with the system instructions, temporary session context, persistent user memories, and the current chat history. If the history gets too large (e.g., >128k tokens) and compression is disabled, it is gracefully truncated.
+2. **Stream Processing**: The main loop initiates a streaming request to the Gemini API (`client.models.generateContentStream`). It yields chunks of text and status updates directly back to the React UI as they arrive.
+3. **Detection & Tool Execution**: Once the stream completes for a given turn, the entire response is scanned for tool calls using a custom regex and bracket-balancing parser (looking for `tool:functions.tool_name(args...)`).
+   - If tools are found, the loop pauses.
+   - Each tool is dispatched to its respective handler in `src/tools/`.
+   - Tool outputs are collected and appended to the context as `[TOOL_RESULT]: ...`.
+4. **Security Governance**: During tool execution, the loop enforces security checks (e.g., blocking `exec_command` from accessing system root drives if "External Workspace Access" is off) and pauses for Human-in-the-Loop (HITL) approval if necessary.
+5. **Turn Management & Continuation**: The model is instructed to append `[turn: finish]` if its goal is complete, or `[turn: continue]` if it expects tool results.
+   - If tools were called or `[turn: continue]` is present, the loop increments and re-prompts the model with the newly gathered `[TOOL_RESULT]` data.
+   - If `[turn: finish]` is detected and no further tools were called, the main loop terminates, passing the final synthesized context to the background Janitor process.
+6. **Loop Limits & Resilience**: To prevent infinite loops or excessive API usage, **Flux mode** is capped at 50 iterations per user prompt, while **Flow mode** is capped at 5.
+   - **Multi-Stage Failover**: The loop features a sophisticated 8-attempt retry engine with random backoff (800ms - 2s).
+   - **Critical Fallback Pivot**: If the primary model fails 5 consecutive times, the agent surgically pivots to a lighter, high-concurrency fallback model (`gemini-3.1-flash-lite-preview`) for the final 3 attempts to ensure session navigation through API congestion.
+
+## Multimodal Pipeline
+
+Flux Flow implements a native multimodal processing engine in `src/tools/view_file.js`. This allows the agent to move beyond text-based reasoning and analyze visual assets directly.
+
+- **Binary Detection**: The pipeline uses `is-binary-path` to distinguish between text and binary files.
+- **Visual Encoding**: If an image or PDF is detected, the engine reads the raw bytes and converts them into base64-encoded `InlineData` objects.
+- **PDF Extraction**: For PDF documents, the engine extracts visual representation of pages to provide the model with high-fidelity spatial and textual context simultaneously.
+- **Context Injection**: These multimodal assets are injected directly into the Gemini model's multimodal part array, allowing the model to "see" the file as if it were looking at a screenshot.
+
+## The Dual-Model System
+
+To maintain a fast, snappy UI while still performing complex data management, Flux Flow employs two separate AI models for every interaction:
+
+### 1. The Main Agent
+- **Responsibility**: Direct user interaction, reasoning, and tool execution.
+- **Behavior**: Streams text directly to the UI. It focuses entirely on solving the user's immediate problem or answering their question.
+
+### 2. The Janitor (Background Process)
+- **Responsibility**: System maintenance, long-term memory extraction, and chat summarization.
+- **Behavior**: After the Main Agent finishes its loop, the entire context (User Prompt + Agent Raws) is sent to the Janitor model.
+- **Headless Operation**: The Janitor is explicitly instructed to be a "silent background system process" with "no mouth." It *only* outputs valid tool calls (e.g., updating the chat title or saving a new user preference to the persistent memory vault).
+
+## Data Persistence & Safety
+
+- **High-Fidelity Lock**: Because both the UI and the Janitor model may attempt to write to the `history.json` file simultaneously, a Promise-based `WRITE_LOCK` (`src/utils/history.js`) is utilized. This prevents race conditions and ensures data integrity.
+- **Encryption**: User secrets and persistent memories (`secret/memories.json`) are handled by `src/utils/crypto.js` to ensure local privacy.
+
+## Redirection & The Anchor Strategy
+
+To support data portability (e.g., storing all app data on an external encrypted drive), Flux Flow utilizes a synchronous "Anchor" strategy in `src/utils/paths.js`.
+
+- **Synchronous Pivot**: Because many core modules (History, Secrets, Usage) initialize their file paths as constants during module loading, the application must determine the "Actual" data root before anything else.
+- **Boot-Sequence Priority**: On every launch, `paths.js` performs a synchronous file system check for `~/.fluxflow/settings.json`. If a redirection path is found (`useExternalData: true`), it immediately overrides the global `DATA_DIR` constant for the entire process.
+- **Sub-Coordinate Resolution**: All secondary directories (`LOGS_DIR`, `SECRET_DIR`) are derived dynamically from the redirected `DATA_DIR`, ensuring that all session data flows to the external sanctuary without requiring individual configuration updates across the codebase.

package/dist/fluxflow.js

@@ -833,7 +833,7 @@ If you see a [STEERING HINT] from user, give that prompt priority for the task a
 -- START THINKING INSTRUCTIONS --
 ${thinkingConfig}
 
-BEFORE USING ANY TOOL THINKING IS **MANDATORY** WITH TOOL RULES. ALWAYS PRIORITIZE THINKING FIRST BEFORE RESPONDING. YOU ARE **FORBIDDEN** TO JUMP TO RESPONSES FIRST.
+BEFORE USING ANY TOOL THINKING IS **MANDATORY** WITH TOOL RULES. ALWAYS PRIORITIZE THINKING FIRST BEFORE RESPONDING. YOU ARE **FORBIDDEN** TO JUMP TO RESPONSES FIRST. THINKING IS REQUIRED EVEN WITH CONVERSATIONAL RESPONSES.
 -- END THINKING INSTRUCTIONS --
 
 ${TOOL_PROTOCOL(mode)}
@@ -1890,13 +1890,18 @@ var init_update_file = __esm({
           diffText += `-${startLine + i}|${line}
 `;
         });
-        fullNewLines.forEach((line, i) => {
-          diffText += `+${startLine + i}|${line}
+        let currentNewLine = startLine;
+        fullNewLines.forEach((line) => {
+          diffText += `+${currentNewLine}|${line}
 `;
+          currentNewLine++;
         });
-        for (let i = endLine; i < Math.min(allOriginalLines.length, endLine + 15); i++) {
-          diffText += `[UI_CONTEXT]  ${i + 1}|${allOriginalLines[i]}
+        const linesAffected = fullOldLines.length;
+        const originalContextIdx = startLine + linesAffected - 1;
+        for (let i = originalContextIdx; i < Math.min(allOriginalLines.length, originalContextIdx + 15); i++) {
+          diffText += `[UI_CONTEXT]  ${currentNewLine}|${allOriginalLines[i]}
 `;
+          currentNewLine++;
         }
         diffText += `[DIFF_END]`;
         return diffText;
@@ -3064,27 +3069,29 @@ ${boxBottom}
             if (turnText.trim().length > 0) {
               if (inStreamRetryCount <= MAX_RETRIES) {
                 inStreamRetryCount++;
-                const waitTime = Math.floor(Math.random() * (3e3 - 1e3 + 1)) + 1e3;
+                const waitTime = Math.min(1e3 * Math.pow(2, inStreamRetryCount - 1), 12e3);
                 modifiedHistory.push({ role: "agent", text: turnText });
                 if (toolResults.length > 0) {
                   toolResults.forEach((tr) => modifiedHistory.push(tr));
                 }
                 modifiedHistory.push({ role: "user", text: "[SYSTEM] Response got cut for internal error, continue from checkpoint seamlessly and DON'T repeat what you already said!" });
                 accumulatedContext += turnText;
-                yield { type: "status", content: `Error Occured. Recovering Stream (${inStreamRetryCount}/${MAX_RETRIES})...` };
+                yield { type: "status", content: `Error Occured. Recovering Stream (${inStreamRetryCount}/${MAX_RETRIES}) [${(waitTime / 1e3).toFixed(0)}s]...` };
                 await new Promise((resolve) => setTimeout(resolve, waitTime));
               } else {
+                yield { type: "status", content: `Error Occured. Recovering Stream...` };
                 throw new Error(`Stream collapsed too many times. (Failed to resolve ${MAX_RETRIES} times)
 Error Log can be found in ${path16.join(LOGS_DIR, "agent", "error.log")}`);
               }
             } else {
               if (retryCount <= MAX_RETRIES) {
                 retryCount++;
-                const waitTime = Math.floor(Math.random() * (3e3 - 1e3 + 1)) + 1e3;
+                const waitTime = Math.min(1e3 * Math.pow(2, retryCount - 1), 12e3);
                 isInitialAttempt = true;
-                yield { type: "status", content: `Retrying Connection (${retryCount}/${MAX_RETRIES})...` };
+                yield { type: "status", content: `Retrying Connection (${retryCount}/${MAX_RETRIES}) [${(waitTime / 1e3).toFixed(0)}s]...` };
                 await new Promise((resolve) => setTimeout(resolve, waitTime));
               } else {
+                yield { type: "status", content: `Retrying Connection...` };
                 throw new Error(`Model cannot be reached. (Failed ${MAX_RETRIES} times)
 Error Log can be found in ${path16.join(LOGS_DIR, "agent", "error.log")}`);
               }
@@ -5202,7 +5209,7 @@ var init_app = __esm({
     init_text();
     SESSION_START_TIME = Date.now();
     CHANGELOG_URL = "https://fluxflow-cli.onrender.com/changelog.html";
-    versionFluxflow = "1.8.19";
+    versionFluxflow = "1.8.21";
     updatedOn = "2026-05-10";
     ResolutionModal = ({ data, onResolve, onEdit }) => /* @__PURE__ */ React10.createElement(Box10, { flexDirection: "column", borderStyle: "round", borderColor: "magenta", paddingX: 2, paddingY: 1, width: "100%" }, /* @__PURE__ */ React10.createElement(Text10, { color: "magenta", bold: true, underline: true }, "\u{1F7E3} STEERING HINT RESOLUTION"), /* @__PURE__ */ React10.createElement(Text10, { marginTop: 1 }, "The agent already finished the task before your hint was consumed."), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1, backgroundColor: "#222", paddingX: 1, width: "100%" }, /* @__PURE__ */ React10.createElement(Text10, { italic: true, color: "gray" }, '"', data, '"')), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1 }, /* @__PURE__ */ React10.createElement(Text10, { color: "cyan" }, "How would you like to proceed?")), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1 }, /* @__PURE__ */ React10.createElement(
       CommandMenu,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "fluxflow-cli",
-	"version": "1.8.19",
+	"version": "1.8.21",
 	"description": "A high-fidelity agentic terminal assistant for the Flux Era.",
 	"keywords": [
 		"ai",