@didim365/agent-cli-core 0.1.0 → 0.1.2

package/dist/docs/cli/gemini-md.md

@@ -1,108 +0,0 @@
-# Provide context with GEMINI.md files
-
-Context files, which use the default name `GEMINI.md`, are a powerful feature
-for providing instructional context to the Gemini model. You can use these files
-to give project-specific instructions, define a persona, or provide coding style
-guides to make the AI's responses more accurate and tailored to your needs.
-
-Instead of repeating instructions in every prompt, you can define them once in a
-context file.
-
-## Understand the context hierarchy
-
-The CLI uses a hierarchical system to source context. It loads various context
-files from several locations, concatenates the contents of all found files, and
-sends them to the model with every prompt. The CLI loads files in the following
-order:
-
-1.  **Global context file:**
-    - **Location:** `~/.gemini/GEMINI.md` (in your user home directory).
-    - **Scope:** Provides default instructions for all your projects.
-
-2.  **Project root and ancestor context files:**
-    - **Location:** The CLI searches for a `GEMINI.md` file in your current
-      working directory and then in each parent directory up to the project root
-      (identified by a `.git` folder).
-    - **Scope:** Provides context relevant to the entire project.
-
-3.  **Sub-directory context files:**
-    - **Location:** The CLI also scans for `GEMINI.md` files in subdirectories
-      below your current working directory. It respects rules in `.gitignore`
-      and `.geminiignore`.
-    - **Scope:** Lets you write highly specific instructions for a particular
-      component or module.
-
-The CLI footer displays the number of loaded context files, which gives you a
-quick visual cue of the active instructional context.
-
-### Example `GEMINI.md` file
-
-Here is an example of what you can include in a `GEMINI.md` file at the root of
-a TypeScript project:
-
-```markdown
-# Project: My TypeScript Library
-
-## General Instructions
-
-- When you generate new TypeScript code, follow the existing coding style.
-- Ensure all new functions and classes have JSDoc comments.
-- Prefer functional programming paradigms where appropriate.
-
-## Coding Style
-
-- Use 2 spaces for indentation.
-- Prefix interface names with `I` (for example, `IUserService`).
-- Always use strict equality (`===` and `!==`).
-```
-
-## Manage context with the `/memory` command
-
-You can interact with the loaded context files by using the `/memory` command.
-
-- **`/memory show`**: Displays the full, concatenated content of the current
-  hierarchical memory. This lets you inspect the exact instructional context
-  being provided to the model.
-- **`/memory refresh`**: Forces a re-scan and reload of all `GEMINI.md` files
-  from all configured locations.
-- **`/memory add <text>`**: Appends your text to your global
-  `~/.gemini/GEMINI.md` file. This lets you add persistent memories on the fly.
-
-## Modularize context with imports
-
-You can break down large `GEMINI.md` files into smaller, more manageable
-components by importing content from other files using the `@file.md` syntax.
-This feature supports both relative and absolute paths.
-
-**Example `GEMINI.md` with imports:**
-
-```markdown
-# Main GEMINI.md file
-
-This is the main content.
-
-@./components/instructions.md
-
-More content here.
-
-@../shared/style-guide.md
-```
-
-For more details, see the [Memory Import Processor](../core/memport.md)
-documentation.
-
-## Customize the context file name
-
-While `GEMINI.md` is the default filename, you can configure this in your
-`settings.json` file. To specify a different name or a list of names, use the
-`context.fileName` property.
-
-**Example `settings.json`:**
-
-```json
-{
-  "context": {
-    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
-  }
-}
-```

package/dist/docs/cli/generation-settings.md

@@ -1,210 +0,0 @@
-# Advanced Model Configuration
-
-This guide details the Model Configuration system within the Gemini CLI.
-Designed for researchers, AI quality engineers, and advanced users, this system
-provides a rigorous framework for managing generative model hyperparameters and
-behaviors.
-
-> **Warning**: This is a power-user feature. Configuration values are passed
-> directly to the model provider with minimal validation. Incorrect settings
-> (e.g., incompatible parameter combinations) may result in runtime errors from
-> the API.
-
-## 1. System Overview
-
-The Model Configuration system (`ModelConfigService`) enables deterministic
-control over model generation. It decouples the requested model identifier
-(e.g., a CLI flag or agent request) from the underlying API configuration. This
-allows for:
-
-- **Precise Hyperparameter Tuning**: Direct control over `temperature`, `topP`,
-  `thinkingBudget`, and other SDK-level parameters.
-- **Environment-Specific Behavior**: Distinct configurations for different
-  operating contexts (e.g., testing vs. production).
-- **Agent-Scoped Customization**: Applying specific settings only when a
-  particular agent is active.
-
-The system operates on two core primitives: **Aliases** and **Overrides**.
-
-## 2. Configuration Primitives
-
-These settings are located under the `modelConfigs` key in your configuration
-file.
-
-### Aliases (`customAliases`)
-
-Aliases are named, reusable configuration presets. Users should define their own
-aliases (or override system defaults) in the `customAliases` map.
-
-- **Inheritance**: An alias can `extends` another alias (including system
-  defaults like `chat-base`), inheriting its `modelConfig`. Child aliases can
-  overwrite or augment inherited settings.
-- **Abstract Aliases**: An alias is not required to specify a concrete `model`
-  if it serves purely as a base for other aliases.
-
-**Example Hierarchy**:
-
-```json
-"modelConfigs": {
-  "customAliases": {
-    "base": {
-      "modelConfig": {
-        "generateContentConfig": { "temperature": 0.0 }
-      }
-    },
-    "chat-base": {
-      "extends": "base",
-      "modelConfig": {
-        "generateContentConfig": { "temperature": 0.7 }
-      }
-    }
-  }
-}
-```
-
-### Overrides (`overrides`)
-
-Overrides are conditional rules that inject configuration based on the runtime
-context. They are evaluated dynamically for each model request.
-
-- **Match Criteria**: Overrides apply when the request context matches the
-  specified `match` properties.
-  - `model`: Matches the requested model name or alias.
-  - `overrideScope`: Matches the distinct scope of the request (typically the
-    agent name, e.g., `codebaseInvestigator`).
-
-**Example Override**:
-
-```json
-"modelConfigs": {
-  "overrides": [
-    {
-      "match": {
-        "overrideScope": "codebaseInvestigator"
-      },
-      "modelConfig": {
-        "generateContentConfig": { "temperature": 0.1 }
-      }
-    }
-  ]
-}
-```
-
-## 3. Resolution Strategy
-
-The `ModelConfigService` resolves the final configuration through a two-step
-process:
-
-### Step 1: Alias Resolution
-
-The requested model string is looked up in the merged map of system `aliases`
-and user `customAliases`.
-
-1.  If found, the system recursively resolves the `extends` chain.
-2.  Settings are merged from parent to child (child wins).
-3.  This results in a base `ResolvedModelConfig`.
-4.  If not found, the requested string is treated as the raw model name.
-
-### Step 2: Override Application
-
-The system evaluates the `overrides` list against the request context (`model`
-and `overrideScope`).
-
-1.  **Filtering**: All matching overrides are identified.
-2.  **Sorting**: Matches are prioritized by **specificity** (the number of
-    matched keys in the `match` object).
-    - Specific matches (e.g., `model` + `overrideScope`) override broad matches
-      (e.g., `model` only).
-    - Tie-breaking: If specificity is equal, the order of definition in the
-      `overrides` array is preserved (last one wins).
-3.  **Merging**: The configurations from the sorted overrides are merged
-    sequentially onto the base configuration.
-
-## 4. Configuration Reference
-
-The configuration follows the `ModelConfigServiceConfig` interface.
-
-### `ModelConfig` Object
-
-Defines the actual parameters for the model.
-
-| Property                | Type     | Description                                                        |
-| :---------------------- | :------- | :----------------------------------------------------------------- |
-| `model`                 | `string` | The identifier of the model to be called (e.g., `gemini-2.5-pro`). |
-| `generateContentConfig` | `object` | The configuration object passed to the `@google/genai` SDK.        |
-
-### `GenerateContentConfig` (Common Parameters)
-
-Directly maps to the SDK's `GenerateContentConfig`. Common parameters include:
-
-- **`temperature`**: (`number`) Controls output randomness. Lower values (0.0)
-  are deterministic; higher values (>0.7) are creative.
-- **`topP`**: (`number`) Nucleus sampling probability.
-- **`maxOutputTokens`**: (`number`) Limit on generated response length.
-- **`thinkingConfig`**: (`object`) Configuration for models with reasoning
-  capabilities (e.g., `thinkingBudget`, `includeThoughts`).
-
-## 5. Practical Examples
-
-### Defining a Deterministic Baseline
-
-Create an alias for tasks requiring high precision, extending the standard chat
-configuration but enforcing zero temperature.
-
-```json
-"modelConfigs": {
-  "customAliases": {
-    "precise-mode": {
-      "extends": "chat-base",
-      "modelConfig": {
-        "generateContentConfig": {
-          "temperature": 0.0,
-          "topP": 1.0
-        }
-      }
-    }
-  }
-}
-```
-
-### Agent-Specific Parameter Injection
-
-Enforce extended thinking budgets for a specific agent without altering the
-global default, e.g. for the `codebaseInvestigator`.
-
-```json
-"modelConfigs": {
-  "overrides": [
-    {
-      "match": {
-        "overrideScope": "codebaseInvestigator"
-      },
-      "modelConfig": {
-        "generateContentConfig": {
-          "thinkingConfig": { "thinkingBudget": 4096 }
-        }
-      }
-    }
-  ]
-}
-```
-
-### Experimental Model Evaluation
-
-Route traffic for a specific alias to a preview model for A/B testing, without
-changing client code.
-
-```json
-"modelConfigs": {
-  "overrides": [
-    {
-      "match": {
-        "model": "gemini-2.5-pro"
-      },
-      "modelConfig": {
-        "model": "gemini-2.5-pro-experimental-001"
-      }
-    }
-  ]
-}
-```

package/dist/docs/cli/headless.md

@@ -1,388 +0,0 @@
-# Headless mode
-
-Headless mode allows you to run Gemini CLI programmatically from command line
-scripts and automation tools without any interactive UI. This is ideal for
-scripting, automation, CI/CD pipelines, and building AI-powered tools.
-
-- [Headless Mode](#headless-mode)
-  - [Overview](#overview)
-  - [Basic Usage](#basic-usage)
-    - [Direct Prompts](#direct-prompts)
-    - [Stdin Input](#stdin-input)
-    - [Combining with File Input](#combining-with-file-input)
-  - [Output Formats](#output-formats)
-    - [Text Output (Default)](#text-output-default)
-    - [JSON Output](#json-output)
-      - [Response Schema](#response-schema)
-      - [Example Usage](#example-usage)
-    - [Streaming JSON Output](#streaming-json-output)
-      - [When to Use Streaming JSON](#when-to-use-streaming-json)
-      - [Event Types](#event-types)
-      - [Basic Usage](#basic-usage)
-      - [Example Output](#example-output)
-      - [Processing Stream Events](#processing-stream-events)
-      - [Real-World Examples](#real-world-examples)
-    - [File Redirection](#file-redirection)
-  - [Configuration Options](#configuration-options)
-  - [Examples](#examples)
-    - [Code review](#code-review)
-    - [Generate commit messages](#generate-commit-messages)
-    - [API documentation](#api-documentation)
-    - [Batch code analysis](#batch-code-analysis)
-    - [Code review](#code-review-1)
-    - [Log analysis](#log-analysis)
-    - [Release notes generation](#release-notes-generation)
-    - [Model and tool usage tracking](#model-and-tool-usage-tracking)
-  - [Resources](#resources)
-
-## Overview
-
-The headless mode provides a headless interface to Gemini CLI that:
-
-- Accepts prompts via command line arguments or stdin
-- Returns structured output (text or JSON)
-- Supports file redirection and piping
-- Enables automation and scripting workflows
-- Provides consistent exit codes for error handling
-
-## Basic usage
-
-### Direct prompts
-
-Use the `--prompt` (or `-p`) flag to run in headless mode:
-
-```bash
-gemini --prompt "What is machine learning?"
-```
-
-### Stdin input
-
-Pipe input to Gemini CLI from your terminal:
-
-```bash
-echo "Explain this code" | gemini
-```
-
-### Combining with file input
-
-Read from files and process with Gemini:
-
-```bash
-cat README.md | gemini --prompt "Summarize this documentation"
-```
-
-## Output formats
-
-### Text output (default)
-
-Standard human-readable output:
-
-```bash
-gemini -p "What is the capital of France?"
-```
-
-Response format:
-
-```
-The capital of France is Paris.
-```
-
-### JSON output
-
-Returns structured data including response, statistics, and metadata. This
-format is ideal for programmatic processing and automation scripts.
-
-#### Response schema
-
-The JSON output follows this high-level structure:
-
-```json
-{
-  "response": "string", // The main AI-generated content answering your prompt
-  "stats": {
-    // Usage metrics and performance data
-    "models": {
-      // Per-model API and token usage statistics
-      "[model-name]": {
-        "api": {
-          /* request counts, errors, latency */
-        },
-        "tokens": {
-          /* prompt, response, cached, total counts */
-        }
-      }
-    },
-    "tools": {
-      // Tool execution statistics
-      "totalCalls": "number",
-      "totalSuccess": "number",
-      "totalFail": "number",
-      "totalDurationMs": "number",
-      "totalDecisions": {
-        /* accept, reject, modify, auto_accept counts */
-      },
-      "byName": {
-        /* per-tool detailed stats */
-      }
-    },
-    "files": {
-      // File modification statistics
-      "totalLinesAdded": "number",
-      "totalLinesRemoved": "number"
-    }
-  },
-  "error": {
-    // Present only when an error occurred
-    "type": "string", // Error type (e.g., "ApiError", "AuthError")
-    "message": "string", // Human-readable error description
-    "code": "number" // Optional error code
-  }
-}
-```
-
-#### Example usage
-
-```bash
-gemini -p "What is the capital of France?" --output-format json
-```
-
-Response:
-
-```json
-{
-  "response": "The capital of France is Paris.",
-  "stats": {
-    "models": {
-      "gemini-2.5-pro": {
-        "api": {
-          "totalRequests": 2,
-          "totalErrors": 0,
-          "totalLatencyMs": 5053
-        },
-        "tokens": {
-          "prompt": 24939,
-          "candidates": 20,
-          "total": 25113,
-          "cached": 21263,
-          "thoughts": 154,
-          "tool": 0
-        }
-      },
-      "gemini-2.5-flash": {
-        "api": {
-          "totalRequests": 1,
-          "totalErrors": 0,
-          "totalLatencyMs": 1879
-        },
-        "tokens": {
-          "prompt": 8965,
-          "candidates": 10,
-          "total": 9033,
-          "cached": 0,
-          "thoughts": 30,
-          "tool": 28
-        }
-      }
-    },
-    "tools": {
-      "totalCalls": 1,
-      "totalSuccess": 1,
-      "totalFail": 0,
-      "totalDurationMs": 1881,
-      "totalDecisions": {
-        "accept": 0,
-        "reject": 0,
-        "modify": 0,
-        "auto_accept": 1
-      },
-      "byName": {
-        "google_web_search": {
-          "count": 1,
-          "success": 1,
-          "fail": 0,
-          "durationMs": 1881,
-          "decisions": {
-            "accept": 0,
-            "reject": 0,
-            "modify": 0,
-            "auto_accept": 1
-          }
-        }
-      }
-    },
-    "files": {
-      "totalLinesAdded": 0,
-      "totalLinesRemoved": 0
-    }
-  }
-}
-```
-
-### Streaming JSON output
-
-Returns real-time events as newline-delimited JSON (JSONL). Each significant
-action (initialization, messages, tool calls, results) emits immediately as it
-occurs. This format is ideal for monitoring long-running operations, building
-UIs with live progress, and creating automation pipelines that react to events.
-
-#### When to use streaming JSON
-
-Use `--output-format stream-json` when you need:
-
-- **Real-time progress monitoring** - See tool calls and responses as they
-  happen
-- **Event-driven automation** - React to specific events (e.g., tool failures)
-- **Live UI updates** - Build interfaces showing AI agent activity in real-time
-- **Detailed execution logs** - Capture complete interaction history with
-  timestamps
-- **Pipeline integration** - Stream events to logging/monitoring systems
-
-#### Event types
-
-The streaming format emits 6 event types:
-
-1. **`init`** - Session starts (includes session_id, model)
-2. **`message`** - User prompts and assistant responses
-3. **`tool_use`** - Tool call requests with parameters
-4. **`tool_result`** - Tool execution results (success/error)
-5. **`error`** - Non-fatal errors and warnings
-6. **`result`** - Final session outcome with aggregated stats
-
-#### Basic usage
-
-```bash
-# Stream events to console
-gemini --output-format stream-json --prompt "What is 2+2?"
-
-# Save event stream to file
-gemini --output-format stream-json --prompt "Analyze this code" > events.jsonl
-
-# Parse with jq
-gemini --output-format stream-json --prompt "List files" | jq -r '.type'
-```
-
-#### Example output
-
-Each line is a complete JSON event:
-
-```jsonl
-{"type":"init","timestamp":"2025-10-10T12:00:00.000Z","session_id":"abc123","model":"gemini-2.0-flash-exp"}
-{"type":"message","role":"user","content":"List files in current directory","timestamp":"2025-10-10T12:00:01.000Z"}
-{"type":"tool_use","tool_name":"Bash","tool_id":"bash-123","parameters":{"command":"ls -la"},"timestamp":"2025-10-10T12:00:02.000Z"}
-{"type":"tool_result","tool_id":"bash-123","status":"success","output":"file1.txt\nfile2.txt","timestamp":"2025-10-10T12:00:03.000Z"}
-{"type":"message","role":"assistant","content":"Here are the files...","delta":true,"timestamp":"2025-10-10T12:00:04.000Z"}
-{"type":"result","status":"success","stats":{"total_tokens":250,"input_tokens":50,"output_tokens":200,"duration_ms":3000,"tool_calls":1},"timestamp":"2025-10-10T12:00:05.000Z"}
-```
-
-### File redirection
-
-Save output to files or pipe to other commands:
-
-```bash
-# Save to file
-gemini -p "Explain Docker" > docker-explanation.txt
-gemini -p "Explain Docker" --output-format json > docker-explanation.json
-
-# Append to file
-gemini -p "Add more details" >> docker-explanation.txt
-
-# Pipe to other tools
-gemini -p "What is Kubernetes?" --output-format json | jq '.response'
-gemini -p "Explain microservices" | wc -w
-gemini -p "List programming languages" | grep -i "python"
-```
-
-## Configuration options
-
-Key command-line options for headless usage:
-
-| Option                  | Description                        | Example                                            |
-| ----------------------- | ---------------------------------- | -------------------------------------------------- |
-| `--prompt`, `-p`        | Run in headless mode               | `gemini -p "query"`                                |
-| `--output-format`       | Specify output format (text, json) | `gemini -p "query" --output-format json`           |
-| `--model`, `-m`         | Specify the Gemini model           | `gemini -p "query" -m gemini-2.5-flash`            |
-| `--debug`, `-d`         | Enable debug mode                  | `gemini -p "query" --debug`                        |
-| `--include-directories` | Include additional directories     | `gemini -p "query" --include-directories src,docs` |
-| `--yolo`, `-y`          | Auto-approve all actions           | `gemini -p "query" --yolo`                         |
-| `--approval-mode`       | Set approval mode                  | `gemini -p "query" --approval-mode auto_edit`      |
-
-For complete details on all available configuration options, settings files, and
-environment variables, see the
-[Configuration Guide](../get-started/configuration.md).
-
-## Examples
-
-#### Code review
-
-```bash
-cat src/auth.py | gemini -p "Review this authentication code for security issues" > security-review.txt
-```
-
-#### Generate commit messages
-
-```bash
-result=$(git diff --cached | gemini -p "Write a concise commit message for these changes" --output-format json)
-echo "$result" | jq -r '.response'
-```
-
-#### API documentation
-
-```bash
-result=$(cat api/routes.js | gemini -p "Generate OpenAPI spec for these routes" --output-format json)
-echo "$result" | jq -r '.response' > openapi.json
-```
-
-#### Batch code analysis
-
-```bash
-for file in src/*.py; do
-    echo "Analyzing $file..."
-    result=$(cat "$file" | gemini -p "Find potential bugs and suggest improvements" --output-format json)
-    echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
-    echo "Completed analysis for $(basename "$file")" >> reports/progress.log
-done
-```
-
-#### Code review
-
-```bash
-result=$(git diff origin/main...HEAD | gemini -p "Review these changes for bugs, security issues, and code quality" --output-format json)
-echo "$result" | jq -r '.response' > pr-review.json
-```
-
-#### Log analysis
-
-```bash
-grep "ERROR" /var/log/app.log | tail -20 | gemini -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt
-```
-
-#### Release notes generation
-
-```bash
-result=$(git log --oneline v1.0.0..HEAD | gemini -p "Generate release notes from these commits" --output-format json)
-response=$(echo "$result" | jq -r '.response')
-echo "$response"
-echo "$response" >> CHANGELOG.md
-```
-
-#### Model and tool usage tracking
-
-```bash
-result=$(gemini -p "Explain this database schema" --include-directories db --output-format json)
-total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
-models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
-tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
-tools_used=$(echo "$result" | jq -r '.stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
-echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
-echo "$result" | jq -r '.response' > schema-docs.md
-echo "Recent usage trends:"
-tail -5 usage.log
-```
-
-## Resources
-
-- [CLI Configuration](../get-started/configuration.md) - Complete configuration
-  guide
-- [Authentication](../get-started/authentication.md) - Setup authentication
-- [Commands](./commands.md) - Interactive commands reference
-- [Tutorials](./tutorials.md) - Step-by-step automation guides