@terminai/core 0.21.0

package/dist/docs/termai-quickstart.md

@@ -0,0 +1,59 @@
+# TerminaI quickstart
+
+TerminaI is a terminal-first AI that ships as a wrapper on top of Gemini CLI. It
+runs the same engine with a Terminal AI system prompt by default.
+
+## Install
+
+### Option 1: npx (fastest)
+
+```bash
+npx termai
+```
+
+### Option 2: npm global install
+
+```bash
+npm install -g termai
+termai
+```
+
+### Option 3: from source
+
+```bash
+git clone https://github.com/Prof-Harita/terminaI.git
+cd terminaI
+npm ci
+npm run build
+npm link --workspace packages/termai
+termai
+```
+
+## Authenticate
+
+Pick one of the authentication methods when prompted on first run:
+
+- Google OAuth (recommended for most users)
+- Gemini API key
+- Vertex AI
+
+## First commands
+
+```text
+What's eating my CPU?
+How much disk do I have?
+Find all large files over 1 GB and summarize them.
+What's the weather in Austin right now?
+```
+
+## Override the system prompt (optional)
+
+```bash
+export TERMINAI_SYSTEM_MD=/path/to/your/system.md
+termai
+```
+
+## Troubleshooting
+
+If you hit permission prompts or tool denials, re-run the command and confirm
+explicitly. TerminaI will never bypass your confirmation policies.

package/dist/docs/termai-system.md

@@ -0,0 +1,64 @@
+# TerminaI System Prompt (Example)
+
+You are TerminaI, the AI that IS the user's terminal. You own this shell like a
+human operator — you can run commands, monitor processes, query system state,
+and handle any terminal task using your tools and the web.
+
+## Core Mandates
+
+- **System Awareness:** Treat yourself as system-aware. Use system insight
+  (CPU/RAM/disk/processes) to guide actions and answers.
+- **Process Control:** You can spawn, monitor, and manage processes (including
+  long-running tasks). Prefer safe, observable execution and confirm destructive
+  actions.
+- **Web Access:** Use web tools for real-time information (weather, news, docs)
+  when relevant.
+- **Not Just Coding:** You are a general terminal agent (operations, automation,
+  research, scripting), not limited to software engineering tasks.
+- **Proactiveness:** Fulfill the user's request thoroughly, including safe
+  verification steps when appropriate.
+- **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the
+  clear scope of the request without confirming with the user.
+- **Explaining Changes:** After completing a code modification or file
+  operation, do not provide summaries unless asked.
+- **Do Not revert changes:** Do not revert changes to the codebase unless asked
+  by the user.
+
+## Primary Workflows
+
+### General Terminal Tasks
+
+When requested to perform any terminal task, follow this sequence:
+
+1. **Understand:** Parse the user's ask. If system insight is needed, use the
+   shell tool to inspect (e.g., `ps`, `top`, `df`, `free`). Use web search for
+   real-time information (weather, news, docs).
+2. **Plan:** For complex tasks, briefly outline the approach. For simple tasks,
+   act directly.
+3. **Execute:** Use shell/file/web tools to complete the task.
+4. **Report:** Keep responses concise. In voice mode, keep spoken answers under
+   30 words.
+
+#### Example Tasks You Can Handle
+
+- **System Queries:** "What's eating my CPU?" "How much disk do I have?"
+- **Process Control:** "Start the dev server and tell me when it's ready." "Kill
+  PID 1234."
+- **Installation/Updates:** "Install htop." "Update my packages."
+- **Information:** "What's the weather in Austin?" "Latest news about Kubernetes
+  CVEs?"
+- **Automation:** "Every 5 minutes, check if the server is up."
+- **Agent Orchestration:** "Launch Claude and ask it to refactor auth."
+
+## Operational Guidelines
+
+- **Concise by default:** Prefer short, direct answers.
+- **Explain critical commands:** Before running commands that modify system
+  state, briefly explain what will happen and why.
+- **Tool usage:** Use `run_shell_command` for shell operations, file tools for
+  read/write/edits, and `google_web_search`/`web_fetch` for online info.
+- **Background processes:** Use background processes for commands unlikely to
+  stop on their own; ask the user if unsure.
+- **Memory:** Use `save_memory` only for explicit, user-specific preferences.
+- **Respect confirmations:** If a tool call is denied, do not retry unless the
+  user explicitly asks.

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

@@ -0,0 +1,268 @@
+# 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.
+
+### Search best practices (large repos)
+
+- Prefer `search_file_content` or `glob` for structured results and bounded
+  output.
+- Use `include` to narrow the search scope (for example, `"*.ts"` or
+  `"src/**/*.{ts,tsx}"`).
+- For very large repos, use `run_shell_command` with `rg` and quiet flags, and
+  consider redirecting output to a temp file to avoid huge responses.
+
+## 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.
+
+## 7. `file_ops` (FileOps)
+
+`file_ops` groups common file operations under a single tool. It is scoped to
+the current workspace and intended for safe organization tasks (mkdir, move,
+copy, delete, and directory tree listing).
+
+- **Tool name:** `file_ops`
+- **Display name:** FileOps
+- **File:** `file-ops.ts`
+- **Parameters:**
+  - `operation` (string, required): One of `mkdir`, `move`, `copy`, `delete`,
+    `list_tree`.
+  - `path` (string, optional): Path for `mkdir`, `delete`, `list_tree`.
+  - `from` (string, optional): Source path for `move`/`copy`.
+  - `to` (string, optional): Destination path for `move`/`copy`.
+  - `parents` (boolean, optional): Whether `mkdir` should create parent
+    directories.
+  - `overwrite` (boolean, optional): Whether `move`/`copy` can overwrite
+    existing destinations.
+  - `recursive` (boolean, optional): Required for directory `copy` and directory
+    `delete`.
+  - `maxDepth` (number, optional): Depth limit for `list_tree` (default 3).
+  - `maxEntries` (number, optional): Maximum entries for `list_tree` (default
+    200).
+- **Behavior:**
+  - Operations are restricted to workspace paths.
+  - `delete` and overwrite/recursive operations require confirmation.
+  - `list_tree` returns a bounded, depth-limited tree view.
+- **Output (`llmContent`):** A concise success message or a bounded tree
+  listing.
+- **Confirmation:** Yes for destructive or recursive operations.
+
+Example usage:
+
+```
+file_ops(operation="mkdir", path="build", parents=true)
+file_ops(operation="move", from="notes.txt", to="archive/notes.txt")
+file_ops(operation="copy", from="assets", to="backup/assets", recursive=true)
+file_ops(operation="delete", path="tmp", recursive=true)
+file_ops(operation="list_tree", path=".", maxDepth=2, maxEntries=200)
+```
+
+These file system tools provide a foundation for the Gemini CLI to understand
+and interact with your local project context.

package/dist/docs/tools/index.md

@@ -0,0 +1,105 @@
+# Gemini CLI tools
+
+The Gemini CLI includes built-in tools that the Gemini model uses to interact
+with your local environment, access information, and perform actions. These
+tools enhance the CLI's capabilities, enabling it to go beyond text generation
+and assist with a wide range of tasks.
+
+## Overview of Gemini CLI tools
+
+In the context of the Gemini CLI, tools are specific functions or modules that
+the Gemini model can request to be executed. For example, if you ask Gemini to
+"Summarize the contents of `my_document.txt`," the model will likely identify
+the need to read that file and will request the execution of the `read_file`
+tool.
+
+The core component (`packages/core`) manages these tools, presents their
+definitions (schemas) to the Gemini model, executes them when requested, and
+returns the results to the model for further processing into a user-facing
+response.
+
+These tools provide the following capabilities:
+
+- **Access local information:** Tools allow Gemini to access your local file
+  system, read file contents, list directories, etc.
+- **Execute commands:** With tools like `run_shell_command`, Gemini can run
+  shell commands (with appropriate safety measures and user confirmation).
+- **Interact with the web:** Tools can fetch content from URLs.
+- **Take actions:** Tools can modify files, write new files, or perform other
+  actions on your system (again, typically with safeguards).
+- **Ground responses:** By using tools to fetch real-time or specific local
+  data, Gemini's responses can be more accurate, relevant, and grounded in your
+  actual context.
+
+## How to use Gemini CLI tools
+
+To use Gemini CLI tools, provide a prompt to the Gemini CLI. The process works
+as follows:
+
+1.  You provide a prompt to the Gemini CLI.
+2.  The CLI sends the prompt to the core.
+3.  The core, along with your prompt and conversation history, sends a list of
+    available tools and their descriptions/schemas to the Gemini API.
+4.  The Gemini model analyzes your request. If it determines that a tool is
+    needed, its response will include a request to execute a specific tool with
+    certain parameters.
+5.  The core receives this tool request, validates it, and (often after user
+    confirmation for sensitive operations) executes the tool.
+6.  The output from the tool is sent back to the Gemini model.
+7.  The Gemini model uses the tool's output to formulate its final answer, which
+    is then sent back through the core to the CLI and displayed to you.
+
+You will typically see messages in the CLI indicating when a tool is being
+called and whether it succeeded or failed.
+
+## Security and confirmation
+
+Many tools, especially those that can modify your file system or execute
+commands (`write_file`, `edit`, `run_shell_command`), are designed with safety
+in mind. The Gemini CLI will typically:
+
+- **Require confirmation:** Prompt you before executing potentially sensitive
+  operations, showing you what action is about to be taken.
+- **Utilize sandboxing:** All tools are subject to restrictions enforced by
+  sandboxing (see [Sandboxing in the Gemini CLI](../cli/sandbox.md)). This means
+  that when operating in a sandbox, any tools (including MCP servers) you wish
+  to use must be available _inside_ the sandbox environment. For example, to run
+  an MCP server through `npx`, the `npx` executable must be installed within the
+  sandbox's Docker image or be available in the `sandbox-exec` environment.
+
+It's important to always review confirmation prompts carefully before allowing a
+tool to proceed.
+
+## Learn more about Gemini CLI's tools
+
+Gemini CLI's built-in tools can be broadly categorized as follows:
+
+- **[File System Tools](./file-system.md):** For interacting with files and
+  directories (reading, writing, listing, searching, etc.).
+- **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell
+  commands.
+- **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content
+  from URLs.
+- **[Web Search Tool](./web-search.md) (`google_web_search`):** For searching
+  the web.
+- **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling
+  information across sessions.
+- **[Todo Tool](./todos.md) (`write_todos`):** For managing subtasks of complex
+  requests.
+
+Additionally, these tools incorporate:
+
+- **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the
+  Gemini model and your local environment or other services like APIs.
+- **[Sandboxing](../cli/sandbox.md)**: Sandboxing isolates the model and its
+  changes from your environment to reduce potential risk.
+
+## TerminaI-specific tools in this repo
+
+- **`file_ops`:** Safe file organization (mkdir/move/copy/delete/tree listing).
+  See [File System Tools](./file-system.md).
+- **`process_manager`:** Named long-running sessions with bounded output and
+  safe termination. See
+  [TerminaI process manager](../termai-process-manager.md).
+- **`agent_control`:** Supervises external agent CLIs as managed sessions (run,
+  send prompt, read output, stop).