@mmmbuto/gemini-cli-termux 0.22.6-termux → 0.24.0-termux

package/bundle/docs/termux-api/README.md

@@ -0,0 +1,416 @@
+# Termux-API Integration Plan
+
+**Project**: gemini-cli-termux **Version**: 0.22.0-termux **Author**: DioNanos
+**Date**: 2025-12-17 **Status**: Planning Phase
+
+---
+
+## Executive Summary
+
+This document describes the plan to integrate native Termux-API commands into
+the `gemini-cli-termux` fork, allowing Gemini CLI to leverage Android hardware
+and software APIs through Termux.
+
+## Table of Contents
+
+1. [Current Architecture](#current-architecture)
+2. [Termux-API Commands](#termux-api-commands)
+3. [Integration Approaches](#integration-approaches)
+4. [Recommendation](#recommendation)
+5. [Implementation Roadmap](#implementation-roadmap)
+6. [Reference Files](#reference-files)
+
+---
+
+## Current Architecture
+
+### Monorepo Structure
+
+```
+gemini-cli-termux/
+├── packages/
+│   ├── core/           # Logic core, tools, config
+│   │   └── src/
+│   │       ├── tools/  # Tool implementations
+│   │       ├── mcp/    # MCP support
+│   │       └── config/ # Configuration
+│   ├── cli/            # CLI interface
+│   ├── a2a-server/     # Agent-to-Agent server
+│   └── vscode-ide-companion/
+└── bundle/             # Built executable
+```
+
+### Tool System
+
+Tools in Gemini CLI follow a well-defined pattern:
+
+1. **BaseDeclarativeTool**: Base class for defining tools
+2. **BaseToolInvocation**: Class for tool execution
+3. **ToolRegistry**: Registers and manages all tools
+
+**Key files**:
+
+- `packages/core/src/tools/tools.ts` - Interfaces and base classes
+- `packages/core/src/tools/tool-registry.ts` - Tool registry
+- `packages/core/src/tools/shell.ts` - Example: ShellTool
+
+### Tool Call Flow
+
+```
+LLM → ToolRegistry.getTool() → DeclarativeTool.build() → ToolInvocation.execute()
+```
+
+### Discovery Mechanisms
+
+1. **Built-in Tools**: Manually registered in the registry
+2. **Discovered Tools**: Via `tool_discovery_command` in config
+3. **MCP Tools**: Via Model Context Protocol servers
+
+---
+
+## Termux-API Commands
+
+### Categorization by Functionality
+
+| Category           | Commands                                                                                                 | Complexity      |
+| ------------------ | -------------------------------------------------------------------------------------------------------- | --------------- |
+| **System Info**    | battery-status, audio-info, wifi-connectioninfo, wifi-scaninfo, telephony-deviceinfo, telephony-cellinfo | Low             |
+| **Notifications**  | notification, notification-remove, notification-list, toast                                              | Low             |
+| **Clipboard**      | clipboard-get, clipboard-set                                                                             | Low             |
+| **Media**          | camera-photo, camera-info, microphone-record, media-player, media-scan, tts-speak, speech-to-text        | Medium          |
+| **Location**       | location                                                                                                 | Medium          |
+| **Sensors**        | sensor, infrared-frequencies, infrared-transmit, torch, vibrate, brightness                              | Medium          |
+| **Communication**  | sms-send, sms-inbox, sms-list, telephony-call, call-log, contact-list                                    | High (privacy)  |
+| **Storage**        | storage-get, download, share, open, open-url, saf-\*                                                     | Medium          |
+| **Security**       | fingerprint, keystore                                                                                    | High (security) |
+| **System Control** | volume, wake-lock, wake-unlock, wallpaper, wifi-enable                                                   | Medium          |
+| **Dialogs**        | dialog                                                                                                   | Medium          |
+| **NFC**            | nfc                                                                                                      | High            |
+| **USB**            | usb                                                                                                      | High            |
+| **Job Scheduler**  | job-scheduler                                                                                            | Medium          |
+
+### Priority Commands (Phase 1)
+
+1. **termux-battery-status** - Battery info (JSON output)
+2. **termux-clipboard-get/set** - Clipboard operations
+3. **termux-toast** - Toast notifications
+4. **termux-notification** - Persistent notifications
+5. **termux-tts-speak** - Text-to-Speech
+6. **termux-vibrate** - Haptic feedback
+7. **termux-torch** - Flashlight control
+8. **termux-location** - GPS location
+9. **termux-wifi-connectioninfo** - Network info
+10. **termux-audio-info** - Audio info
+
+---
+
+## Integration Approaches
+
+### Approach A: Native Dedicated Tools
+
+**Description**: Create dedicated TypeScript classes for each category of Termux
+commands.
+
+**Proposed Structure**:
+
+```
+packages/core/src/tools/termux/
+├── index.ts
+├── termux-base.ts
+├── termux-system.ts      # battery, wifi, audio, telephony
+├── termux-notification.ts # toast, notification
+├── termux-clipboard.ts   # clipboard operations
+├── termux-media.ts       # camera, microphone, tts, speech
+├── termux-location.ts    # GPS
+├── termux-sensors.ts     # sensor, torch, vibrate
+└── termux-storage.ts     # download, share, open
+```
+
+**Pros**:
+
+- Deep integration with Gemini
+- Type-safe parameter validation
+- LLM-optimized descriptions
+- Specific error handling
+- Granular user confirmation
+
+**Cons**:
+
+- Much code to write (~50 tools)
+- Ongoing maintenance
+- Strong coupling
+
+**Estimated Effort**: High (2-3 weeks)
+
+---
+
+### Approach B: MCP Server for Termux-API
+
+**Description**: Create a standalone MCP server that exposes all Termux commands
+as MCP tools.
+
+**Proposed Structure**:
+
+```
+termux-mcp-server/
+├── package.json
+├── src/
+│   ├── index.ts          # MCP server entry
+│   ├── tools/            # Tool definitions
+│   └── utils/            # Helper functions
+└── README.md
+```
+
+**Configuration**:
+
+```json
+// settings.json
+{
+  "mcpServers": {
+    "termux": {
+      "command": "npx",
+      "args": ["@mmmbuto/termux-mcp-server"]
+    }
+  }
+}
+```
+
+**Pros**:
+
+- Reusable with other MCP clients
+- Separation of concerns
+- Easy to update independently
+- Widely supported MCP standard
+- Publishable to npm separately
+
+**Cons**:
+
+- Communication overhead
+- Separate process dependency
+- More complex debugging
+
+**Estimated Effort**: Medium (1-2 weeks)
+
+---
+
+### Approach C: Tool Discovery Script
+
+**Description**: Create a script that generates FunctionDeclarations for Termux
+commands, leveraging the existing tool discovery mechanism.
+
+**Implementation**:
+
+```bash
+# termux-tool-discovery.sh
+#!/bin/bash
+cat << 'EOF'
+[
+  {
+    "name": "termux_battery_status",
+    "description": "Get battery status including percentage, health, and charging state",
+    "parametersJsonSchema": {
+      "type": "object",
+      "properties": {}
+    }
+  },
+  ...
+]
+EOF
+```
+
+**Configuration**:
+
+```json
+// settings.json
+{
+  "tool_discovery_command": "bash ~/.config/gemini/termux-tool-discovery.sh",
+  "tool_call_command": "bash ~/.config/gemini/termux-tool-call.sh"
+}
+```
+
+**Pros**:
+
+- Leverages existing infrastructure
+- Zero core modifications
+- User configurable
+- Easy to extend
+
+**Cons**:
+
+- Less control over validation
+- Depends on external scripts
+- Limited error handling
+
+**Estimated Effort**: Low (3-5 days)
+
+---
+
+### Approach D: Shell Allowlist Extension
+
+**Description**: Extend shell permissions to auto-approve `termux-*` commands.
+
+**Implementation**:
+
+```typescript
+// packages/core/src/utils/shell-permissions.ts
+const TERMUX_COMMANDS = [
+  'termux-battery-status',
+  'termux-clipboard-get',
+  'termux-clipboard-set',
+  // ...
+];
+
+export function isTermuxCommand(command: string): boolean {
+  return TERMUX_COMMANDS.some((tc) => command.startsWith(tc));
+}
+```
+
+**Pros**:
+
+- Minimal code impact
+- Uses existing ShellTool
+- Quick win
+
+**Cons**:
+
+- No additional semantics
+- LLM must know the syntax
+- No parameter validation
+- No description for LLM
+
+**Estimated Effort**: Minimal (1-2 days)
+
+---
+
+### Approach E: Hybrid (Recommended)
+
+**Description**: Combine approaches B and C for maximum flexibility.
+
+**Phase 1**: Tool Discovery Script (quick win)
+
+- Generates declarations for all commands
+- Allows Gemini to use Termux immediately
+
+**Phase 2**: MCP Server (production)
+
+- Implements complete MCP server
+- Robust validation
+- Publishable to npm
+
+**Phase 3**: Native Tools (optional)
+
+- Only for critical/frequent commands
+- Optimized integration
+
+---
+
+## Recommendation
+
+**Recommended Approach: E (Hybrid)**
+
+### Rationale
+
+1. **Quick Win**: Tool Discovery allows starting immediately
+2. **Scalability**: MCP Server is the standard for extensions
+3. **Flexibility**: Native tools only where needed
+4. **Maintainability**: Each phase can be developed independently
+
+### Implementation Priority
+
+| Phase | Approach         | Commands                        | Priority |
+| ----- | ---------------- | ------------------------------- | -------- |
+| 1     | Discovery Script | All                             | High     |
+| 2     | MCP Server       | System, Clipboard, Notification | Medium   |
+| 3     | Native Tools     | TTS, Location                   | Low      |
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: Tool Discovery (Quick Win)
+
+**Files to create**:
+
+- `scripts/termux-tool-discovery.sh`
+- `scripts/termux-tool-call.sh`
+- `docs/termux-api/DISCOVERY_SETUP.md`
+
+**Tasks**:
+
+1. [ ] Create discovery script with all FunctionDeclarations
+2. [ ] Create call script with command dispatch
+3. [ ] Document user configuration
+4. [ ] Test on Termux
+5. [ ] Update README
+
+### Phase 2: MCP Server
+
+**Files to create**:
+
+- New package `packages/termux-mcp/`
+- Or separate repository `termux-mcp-server`
+
+**Tasks**:
+
+1. [ ] Scaffold MCP server
+2. [ ] Implement System tools (battery, wifi, audio)
+3. [ ] Implement Clipboard tools
+4. [ ] Implement Notification tools
+5. [ ] Implement Media tools
+6. [ ] Test integration
+7. [ ] Publish to npm
+
+### Phase 3: Native Tools (Optional)
+
+**Files to modify**:
+
+- `packages/core/src/tools/` - New tool files
+- `packages/core/src/index.ts` - Export tools
+
+**Tasks**:
+
+1. [ ] Implement TermuxTTSTool
+2. [ ] Implement TermuxLocationTool
+3. [ ] Implement TermuxClipboardTool
+4. [ ] Register tools in registry
+5. [ ] Test and documentation
+
+---
+
+## Reference Files
+
+### Core Architecture
+
+| File                                       | Description            |
+| ------------------------------------------ | ---------------------- |
+| `packages/core/src/tools/tools.ts`         | Base tool interfaces   |
+| `packages/core/src/tools/tool-registry.ts` | Registry and discovery |
+| `packages/core/src/tools/shell.ts`         | Example ShellTool      |
+| `packages/core/src/tools/mcp-tool.ts`      | MCP tool wrapper       |
+| `packages/core/src/tools/mcp-client.ts`    | MCP client             |
+
+### Configuration
+
+| File                                   | Description     |
+| -------------------------------------- | --------------- |
+| `packages/core/src/config/config.ts`   | Config loader   |
+| `packages/core/src/config/settings.ts` | Settings schema |
+
+### Existing Documentation
+
+| File             | Description      |
+| ---------------- | ---------------- |
+| `docs/TERMUX.md` | Setup Termux     |
+| `README.md`      | Project Overview |
+
+---
+
+## Appendices
+
+- [COMMANDS.md](./COMMANDS.md) - Termux-API commands detail
+- [DISCOVERY_SETUP.md](./DISCOVERY_SETUP.md) - Tool Discovery setup guide
+- [MCP_SERVER.md](./MCP_SERVER.md) - MCP Server specifications
+
+---
+
+_Author: DioNanos_

package/bundle/docs/tools/file-system.md

@@ -0,0 +1,217 @@
+# Gemini CLI file system tools
+
+The Gemini CLI provides a comprehensive suite of tools for interacting with the
+local file system. These tools allow the Gemini model to read from, write to,
+list, search, and modify files and directories, all under your control and
+typically with confirmation for sensitive operations.
+
+**Note:** All file system tools operate within a `rootDirectory` (usually the
+current working directory where you launched the CLI) for security. Paths that
+you provide to these tools are generally expected to be absolute or are resolved
+relative to this root directory.
+
+## 1. `list_directory` (ReadFolder)
+
+`list_directory` lists the names of files and subdirectories directly within a
+specified directory path. It can optionally ignore entries matching provided
+glob patterns.
+
+- **Tool name:** `list_directory`
+- **Display name:** ReadFolder
+- **File:** `ls.ts`
+- **Parameters:**
+  - `path` (string, required): The absolute path to the directory to list.
+  - `ignore` (array of strings, optional): A list of glob patterns to exclude
+    from the listing (e.g., `["*.log", ".git"]`).
+  - `respect_git_ignore` (boolean, optional): Whether to respect `.gitignore`
+    patterns when listing files. Defaults to `true`.
+- **Behavior:**
+  - Returns a list of file and directory names.
+  - Indicates whether each entry is a directory.
+  - Sorts entries with directories first, then alphabetically.
+- **Output (`llmContent`):** A string like:
+  `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png`
+- **Confirmation:** No.
+
+## 2. `read_file` (ReadFile)
+
+`read_file` reads and returns the content of a specified file. This tool handles
+text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC,
+OGG, FLAC), and PDF files. For text files, it can read specific line ranges.
+Other binary file types are generally skipped.
+
+- **Tool name:** `read_file`
+- **Display name:** ReadFile
+- **File:** `read-file.ts`
+- **Parameters:**
+  - `path` (string, required): The absolute path to the file to read.
+  - `offset` (number, optional): For text files, the 0-based line number to
+    start reading from. Requires `limit` to be set.
+  - `limit` (number, optional): For text files, the maximum number of lines to
+    read. If omitted, reads a default maximum (e.g., 2000 lines) or the entire
+    file if feasible.
+- **Behavior:**
+  - For text files: Returns the content. If `offset` and `limit` are used,
+    returns only that slice of lines. Indicates if content was truncated due to
+    line limits or line length limits.
+  - For image, audio, and PDF files: Returns the file content as a
+    base64-encoded data structure suitable for model consumption.
+  - For other binary files: Attempts to identify and skip them, returning a
+    message indicating it's a generic binary file.
+- **Output:** (`llmContent`):
+  - For text files: The file content, potentially prefixed with a truncation
+    message (e.g.,
+    `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`).
+  - For image/audio/PDF files: An object containing `inlineData` with `mimeType`
+    and base64 `data` (e.g.,
+    `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`).
+  - For other binary files: A message like
+    `Cannot display content of binary file: /path/to/data.bin`.
+- **Confirmation:** No.
+
+## 3. `write_file` (WriteFile)
+
+`write_file` writes content to a specified file. If the file exists, it will be
+overwritten. If the file doesn't exist, it (and any necessary parent
+directories) will be created.
+
+- **Tool name:** `write_file`
+- **Display name:** WriteFile
+- **File:** `write-file.ts`
+- **Parameters:**
+  - `file_path` (string, required): The absolute path to the file to write to.
+  - `content` (string, required): The content to write into the file.
+- **Behavior:**
+  - Writes the provided `content` to the `file_path`.
+  - Creates parent directories if they don't exist.
+- **Output (`llmContent`):** A success message, e.g.,
+  `Successfully overwrote file: /path/to/your/file.txt` or
+  `Successfully created and wrote to new file: /path/to/new/file.txt`.
+- **Confirmation:** Yes. Shows a diff of changes and asks for user approval
+  before writing.
+
+## 4. `glob` (FindFiles)
+
+`glob` finds files matching specific glob patterns (e.g., `src/**/*.ts`,
+`*.md`), returning absolute paths sorted by modification time (newest first).
+
+- **Tool name:** `glob`
+- **Display name:** FindFiles
+- **File:** `glob.ts`
+- **Parameters:**
+  - `pattern` (string, required): The glob pattern to match against (e.g.,
+    `"*.py"`, `"src/**/*.js"`).
+  - `path` (string, optional): The absolute path to the directory to search
+    within. If omitted, searches the tool's root directory.
+  - `case_sensitive` (boolean, optional): Whether the search should be
+    case-sensitive. Defaults to `false`.
+  - `respect_git_ignore` (boolean, optional): Whether to respect .gitignore
+    patterns when finding files. Defaults to `true`.
+- **Behavior:**
+  - Searches for files matching the glob pattern within the specified directory.
+  - Returns a list of absolute paths, sorted with the most recently modified
+    files first.
+  - Ignores common nuisance directories like `node_modules` and `.git` by
+    default.
+- **Output (`llmContent`):** A message like:
+  `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...`
+- **Confirmation:** No.
+
+## 5. `search_file_content` (SearchText)
+
+`search_file_content` searches for a regular expression pattern within the
+content of files in a specified directory. Can filter files by a glob pattern.
+Returns the lines containing matches, along with their file paths and line
+numbers.
+
+- **Tool name:** `search_file_content`
+- **Display name:** SearchText
+- **File:** `grep.ts`
+- **Parameters:**
+  - `pattern` (string, required): The regular expression (regex) to search for
+    (e.g., `"function\s+myFunction"`).
+  - `path` (string, optional): The absolute path to the directory to search
+    within. Defaults to the current working directory.
+  - `include` (string, optional): A glob pattern to filter which files are
+    searched (e.g., `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted, searches most
+    files (respecting common ignores).
+- **Behavior:**
+  - Uses `git grep` if available in a Git repository for speed; otherwise, falls
+    back to system `grep` or a JavaScript-based search.
+  - Returns a list of matching lines, each prefixed with its file path (relative
+    to the search directory) and line number.
+- **Output (`llmContent`):** A formatted string of matches, e.g.:
+  ```
+  Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
+  ---
+  File: src/utils.ts
+  L15: export function myFunction() {
+  L22:   myFunction.call();
+  ---
+  File: src/index.ts
+  L5: import { myFunction } from './utils';
+  ---
+  ```
+- **Confirmation:** No.
+
+## 6. `replace` (Edit)
+
+`replace` replaces text within a file. By default, replaces a single occurrence,
+but can replace multiple occurrences when `expected_replacements` is specified.
+This tool is designed for precise, targeted changes and requires significant
+context around the `old_string` to ensure it modifies the correct location.
+
+- **Tool name:** `replace`
+- **Display name:** Edit
+- **File:** `edit.ts`
+- **Parameters:**
+  - `file_path` (string, required): The absolute path to the file to modify.
+  - `old_string` (string, required): The exact literal text to replace.
+
+    **CRITICAL:** This string must uniquely identify the single instance to
+    change. It should include at least 3 lines of context _before_ and _after_
+    the target text, matching whitespace and indentation precisely. If
+    `old_string` is empty, the tool attempts to create a new file at `file_path`
+    with `new_string` as content.
+
+  - `new_string` (string, required): The exact literal text to replace
+    `old_string` with.
+  - `expected_replacements` (number, optional): The number of occurrences to
+    replace. Defaults to `1`.
+
+- **Behavior:**
+  - If `old_string` is empty and `file_path` does not exist, creates a new file
+    with `new_string` as content.
+  - If `old_string` is provided, it reads the `file_path` and attempts to find
+    exactly one occurrence of `old_string`.
+  - If one occurrence is found, it replaces it with `new_string`.
+  - **Enhanced reliability (multi-stage edit correction):** To significantly
+    improve the success rate of edits, especially when the model-provided
+    `old_string` might not be perfectly precise, the tool incorporates a
+    multi-stage edit correction mechanism.
+    - If the initial `old_string` isn't found or matches multiple locations, the
+      tool can leverage the Gemini model to iteratively refine `old_string` (and
+      potentially `new_string`).
+    - This self-correction process attempts to identify the unique segment the
+      model intended to modify, making the `replace` operation more robust even
+      with slightly imperfect initial context.
+- **Failure conditions:** Despite the correction mechanism, the tool will fail
+  if:
+  - `file_path` is not absolute or is outside the root directory.
+  - `old_string` is not empty, but the `file_path` does not exist.
+  - `old_string` is empty, but the `file_path` already exists.
+  - `old_string` is not found in the file after attempts to correct it.
+  - `old_string` is found multiple times, and the self-correction mechanism
+    cannot resolve it to a single, unambiguous match.
+- **Output (`llmContent`):**
+  - On success:
+    `Successfully modified file: /path/to/file.txt (1 replacements).` or
+    `Created new file: /path/to/new_file.txt with provided content.`
+  - On failure: An error message explaining the reason (e.g.,
+    `Failed to edit, 0 occurrences found...`,
+    `Failed to edit, expected 1 occurrences but found 2...`).
+- **Confirmation:** Yes. Shows a diff of the proposed changes and asks for user
+  approval before writing to the file.
+
+These file system tools provide a foundation for the Gemini CLI to understand
+and interact with your local project context.