npm - @didim365/agent-cli-core - Versions diffs - 0.1.1 → 0.1.3 - Mend

@didim365/agent-cli-core 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1081) hide show

package/dist/docs/core/memport.md DELETED Viewed

@@ -1,246 +0,0 @@
-# Memory Import Processor
-The Memory Import Processor is a feature that allows you to modularize your
-GEMINI.md files by importing content from other files using the `@file.md`
-syntax.
-## Overview
-This feature enables you to break down large GEMINI.md files into smaller, more
-manageable components that can be reused across different contexts. The import
-processor supports both relative and absolute paths, with built-in safety
-features to prevent circular imports and ensure file access security.
-## Syntax
-Use the `@` symbol followed by the path to the file you want to import:
-```markdown
-# Main GEMINI.md file
-This is the main content.
-@./components/instructions.md
-More content here.
-@./shared/configuration.md
-```
-## Supported path formats
-### Relative paths
-- `@./file.md` - Import from the same directory
-- `@../file.md` - Import from parent directory
-- `@./components/file.md` - Import from subdirectory
-### Absolute paths
-- `@/absolute/path/to/file.md` - Import using absolute path
-## Examples
-### Basic import
-```markdown
-# My GEMINI.md
-Welcome to my project!
-@./get-started.md
-## Features
-@./features/overview.md
-```
-### Nested imports
-The imported files can themselves contain imports, creating a nested structure:
-```markdown
-# main.md
-@./header.md @./content.md @./footer.md
-```
-```markdown
-# header.md
-# Project Header
-@./shared/title.md
-```
-## Safety features
-### Circular import detection
-The processor automatically detects and prevents circular imports:
-```markdown
-# file-a.md
-@./file-b.md
-```
-```markdown
-# file-b.md
-@./file-a.md <!-- This will be detected and prevented -->
-```
-### File access security
-The `validateImportPath` function ensures that imports are only allowed from
-specified directories, preventing access to sensitive files outside the allowed
-scope.
-### Maximum import depth
-To prevent infinite recursion, there's a configurable maximum import depth
-(default: 5 levels).
-## Error handling
-### Missing files
-If a referenced file doesn't exist, the import will fail gracefully with an
-error comment in the output.
-### File access errors
-Permission issues or other file system errors are handled gracefully with
-appropriate error messages.
-## Code region detection
-The import processor uses the `marked` library to detect code blocks and inline
-code spans, ensuring that `@` imports inside these regions are properly ignored.
-This provides robust handling of nested code blocks and complex Markdown
-structures.
-## Import tree structure
-The processor returns an import tree that shows the hierarchy of imported files,
-similar to Claude's `/memory` feature. This helps users debug problems with
-their GEMINI.md files by showing which files were read and their import
-relationships.
-Example tree structure:
-```
-Memory Files
- L project: GEMINI.md
-            L a.md
-              L b.md
-                L c.md
-              L d.md
-                L e.md
-                  L f.md
-            L included.md
-```
-The tree preserves the order that files were imported and shows the complete
-import chain for debugging purposes.
-## Comparison to Claude Code's `/memory` (`claude.md`) approach
-Claude Code's `/memory` feature (as seen in `claude.md`) produces a flat, linear
-document by concatenating all included files, always marking file boundaries
-with clear comments and path names. It does not explicitly present the import
-hierarchy, but the LLM receives all file contents and paths, which is sufficient
-for reconstructing the hierarchy if needed.
-> [!NOTE] The import tree is mainly for clarity during development and has
-> limited relevance to LLM consumption.
-## API reference
-### `processImports(content, basePath, debugMode?, importState?)`
-Processes import statements in GEMINI.md content.
-**Parameters:**
-- `content` (string): The content to process for imports
-- `basePath` (string): The directory path where the current file is located
-- `debugMode` (boolean, optional): Whether to enable debug logging (default:
-  false)
-- `importState` (ImportState, optional): State tracking for circular import
-  prevention
-**Returns:** Promise&lt;ProcessImportsResult&gt; - Object containing processed
-content and import tree
-### `ProcessImportsResult`
-```typescript
-interface ProcessImportsResult {
-  content: string; // The processed content with imports resolved
-  importTree: MemoryFile; // Tree structure showing the import hierarchy
-}
-```
-### `MemoryFile`
-```typescript
-interface MemoryFile {
-  path: string; // The file path
-  imports?: MemoryFile[]; // Direct imports, in the order they were imported
-}
-```
-### `validateImportPath(importPath, basePath, allowedDirectories)`
-Validates import paths to ensure they are safe and within allowed directories.
-**Parameters:**
-- `importPath` (string): The import path to validate
-- `basePath` (string): The base directory for resolving relative paths
-- `allowedDirectories` (string[]): Array of allowed directory paths
-**Returns:** boolean - Whether the import path is valid
-### `findProjectRoot(startDir)`
-Finds the project root by searching for a `.git` directory upwards from the
-given start directory. Implemented as an **async** function using non-blocking
-file system APIs to avoid blocking the Node.js event loop.
-**Parameters:**
-- `startDir` (string): The directory to start searching from
-**Returns:** Promise&lt;string&gt; - The project root directory (or the start
-directory if no `.git` is found)
-## Best Practices
-1. **Use descriptive file names** for imported components
-2. **Keep imports shallow** - avoid deeply nested import chains
-3. **Document your structure** - maintain a clear hierarchy of imported files
-4. **Test your imports** - ensure all referenced files exist and are accessible
-5. **Use relative paths** when possible for better portability
-## Troubleshooting
-### Common issues
-1. **Import not working**: Check that the file exists and the path is correct
-2. **Circular import warnings**: Review your import structure for circular
-   references
-3. **Permission errors**: Ensure the files are readable and within allowed
-   directories
-4. **Path resolution issues**: Use absolute paths if relative paths aren't
-   resolving correctly
-### Debug mode
-Enable debug mode to see detailed logging of the import process:
-```typescript
-const result = await processImports(content, basePath, true);
-```

package/dist/docs/core/policy-engine.md DELETED Viewed

@@ -1,300 +0,0 @@
-# Policy engine
-The Gemini CLI includes a powerful policy engine that provides fine-grained
-control over tool execution. It allows users and administrators to define rules
-that determine whether a tool call should be allowed, denied, or require user
-confirmation.
-## Quick start
-To create your first policy:
-1.  **Create the policy directory** if it doesn't exist:
-    ```bash
-    mkdir -p ~/.gemini/policies
-    ```
-2.  **Create a new policy file** (e.g., `~/.gemini/policies/my-rules.toml`). You
-    can use any filename ending in `.toml`; all such files in this directory
-    will be loaded and combined:
-    ```toml
-    [[rule]]
-    toolName = "run_shell_command"
-    commandPrefix = "git status"
-    decision = "allow"
-    priority = 100
-    ```
-3.  **Run a command** that triggers the policy (e.g., ask Gemini CLI to
-    `git status`). The tool will now execute automatically without prompting for
-    confirmation.
-## Core concepts
-The policy engine operates on a set of rules. Each rule is a combination of
-conditions and a resulting decision. When a large language model wants to
-execute a tool, the policy engine evaluates all rules to find the
-highest-priority rule that matches the tool call.
-A rule consists of the following main components:
-- **Conditions**: Criteria that a tool call must meet for the rule to apply.
-  This can include the tool's name, the arguments provided to it, or the current
-  approval mode.
-- **Decision**: The action to take if the rule matches (`allow`, `deny`, or
-  `ask_user`).
-- **Priority**: A number that determines the rule's precedence. Higher numbers
-  win.
-For example, this rule will ask for user confirmation before executing any `git`
-command.
-```toml
-[[rule]]
-toolName = "run_shell_command"
-commandPrefix = "git "
-decision = "ask_user"
-priority = 100
-```
-### Conditions
-Conditions are the criteria that a tool call must meet for a rule to apply. The
-primary conditions are the tool's name and its arguments.
-#### Tool Name
-The `toolName` in the rule must match the name of the tool being called.
-- **Wildcards**: For Model-hosting-protocol (MCP) servers, you can use a
-  wildcard. A `toolName` of `my-server__*` will match any tool from the
-  `my-server` MCP.
-#### Arguments pattern
-If `argsPattern` is specified, the tool's arguments are converted to a stable
-JSON string, which is then tested against the provided regular expression. If
-the arguments don't match the pattern, the rule does not apply.
-### Decisions
-There are three possible decisions a rule can enforce:
-- `allow`: The tool call is executed automatically without user interaction.
-- `deny`: The tool call is blocked and is not executed.
-- `ask_user`: The user is prompted to approve or deny the tool call. (In
-  non-interactive mode, this is treated as `deny`.)
-### Priority system and tiers
-The policy engine uses a sophisticated priority system to resolve conflicts when
-multiple rules match a single tool call. The core principle is simple: **the
-rule with the highest priority wins**.
-To provide a clear hierarchy, policies are organized into three tiers. Each tier
-has a designated number that forms the base of the final priority calculation.
-| Tier    | Base | Description                                                                |
-| :------ | :--- | :------------------------------------------------------------------------- |
-| Default | 1    | Built-in policies that ship with the Gemini CLI.                           |
-| User    | 2    | Custom policies defined by the user.                                       |
-| Admin   | 3    | Policies managed by an administrator (e.g., in an enterprise environment). |
-Within a TOML policy file, you assign a priority value from **0 to 999**. The
-engine transforms this into a final priority using the following formula:
-`final_priority = tier_base + (toml_priority / 1000)`
-This system guarantees that:
-- Admin policies always override User and Default policies.
-- User policies always override Default policies.
-- You can still order rules within a single tier with fine-grained control.
-For example:
-- A `priority: 50` rule in a Default policy file becomes `1.050`.
-- A `priority: 100` rule in a User policy file becomes `2.100`.
-- A `priority: 20` rule in an Admin policy file becomes `3.020`.
-### Approval modes
-Approval modes allow the policy engine to apply different sets of rules based on
-the CLI's operational mode. A rule can be associated with one or more modes
-(e.g., `yolo`, `autoEdit`). The rule will only be active if the CLI is running
-in one of its specified modes. If a rule has no modes specified, it is always
-active.
-## Rule matching
-When a tool call is made, the engine checks it against all active rules,
-starting from the highest priority. The first rule that matches determines the
-outcome.
-A rule matches a tool call if all of its conditions are met:
-1.  **Tool name**: The `toolName` in the rule must match the name of the tool
-    being called.
-    - **Wildcards**: For Model-hosting-protocol (MCP) servers, you can use a
-      wildcard. A `toolName` of `my-server__*` will match any tool from the
-      `my-server` MCP.
-2.  **Arguments pattern**: If `argsPattern` is specified, the tool's arguments
-    are converted to a stable JSON string, which is then tested against the
-    provided regular expression. If the arguments don't match the pattern, the
-    rule does not apply.
-## Configuration
-Policies are defined in `.toml` files. The CLI loads these files from Default,
-User, and (if configured) Admin directories.
-### Policy locations
-| Tier      | Type   | Location                    |
-| :-------- | :----- | :-------------------------- |
-| **User**  | Custom | `~/.gemini/policies/*.toml` |
-| **Admin** | System | _See below (OS specific)_   |
-#### System-wide policies (Admin)
-Administrators can enforce system-wide policies (Tier 3) that override all user
-and default settings. These policies must be placed in specific, secure
-directories:
-| OS          | Policy Directory Path                             |
-| :---------- | :------------------------------------------------ |
-| **Linux**   | `/etc/gemini-cli/policies`                        |
-| **macOS**   | `/Library/Application Support/GeminiCli/policies` |
-| **Windows** | `C:\ProgramData\gemini-cli\policies`              |
-**Security Requirements:**
-To prevent privilege escalation, the CLI enforces strict security checks on
-admin directories. If checks fail, system policies are **ignored**.
-- **Linux / macOS:** Must be owned by `root` (UID 0) and NOT writable by group
-  or others (e.g., `chmod 755`).
-- **Windows:** Must be in `C:\ProgramData`. Standard users (`Users`, `Everyone`)
-  must NOT have `Write`, `Modify`, or `Full Control` permissions. _Tip: If you
-  see a security warning, use the folder properties to remove write permissions
-  for non-admin groups. You may need to "Disable inheritance" in Advanced
-  Security Settings._
-### TOML rule schema
-Here is a breakdown of the fields available in a TOML policy rule:
-```toml
-[[rule]]
-# A unique name for the tool, or an array of names.
-toolName = "run_shell_command"
-# (Optional) The name of an MCP server. Can be combined with toolName
-# to form a composite name like "mcpName__toolName".
-mcpName = "my-custom-server"
-# (Optional) A regex to match against the tool's arguments.
-argsPattern = '"command":"(git|npm)'
-# (Optional) A string or array of strings that a shell command must start with.
-# This is syntactic sugar for `toolName = "run_shell_command"` and an `argsPattern`.
-commandPrefix = "git "
-# (Optional) A regex to match against the entire shell command.
-# This is also syntactic sugar for `toolName = "run_shell_command"`.
-# Note: This pattern is tested against the JSON representation of the arguments (e.g., `{"command":"<your_command>"}`), so anchors like `^` or `$` will apply to the full JSON string, not just the command text.
-# You cannot use commandPrefix and commandRegex in the same rule.
-commandRegex = "^git (commit|push)"
-# The decision to take. Must be "allow", "deny", or "ask_user".
-decision = "ask_user"
-# The priority of the rule, from 0 to 999.
-priority = 10
-# (Optional) An array of approval modes where this rule is active.
-modes = ["autoEdit"]
-```
-### Using arrays (lists)
-To apply the same rule to multiple tools or command prefixes, you can provide an
-array of strings for the `toolName` and `commandPrefix` fields.
-**Example:**
-This single rule will apply to both the `write_file` and `replace` tools.
-```toml
-[[rule]]
-toolName = ["write_file", "replace"]
-decision = "ask_user"
-priority = 10
-```
-### Special syntax for `run_shell_command`
-To simplify writing policies for `run_shell_command`, you can use
-`commandPrefix` or `commandRegex` instead of the more complex `argsPattern`.
-- `commandPrefix`: Matches if the `command` argument starts with the given
-  string.
-- `commandRegex`: Matches if the `command` argument matches the given regular
-  expression.
-**Example:**
-This rule will ask for user confirmation before executing any `git` command.
-```toml
-[[rule]]
-toolName = "run_shell_command"
-commandPrefix = "git "
-decision = "ask_user"
-priority = 100
-```
-### Special syntax for MCP tools
-You can create rules that target tools from Model-hosting-protocol (MCP) servers
-using the `mcpName` field or a wildcard pattern.
-**1. Using `mcpName`**
-To target a specific tool from a specific server, combine `mcpName` and
-`toolName`.
-```toml
-# Allows the `search` tool on the `my-jira-server` MCP
-[[rule]]
-mcpName = "my-jira-server"
-toolName = "search"
-decision = "allow"
-priority = 200
-```
-**2. Using a wildcard**
-To create a rule that applies to _all_ tools on a specific MCP server, specify
-only the `mcpName`.
-```toml
-# Denies all tools from the `untrusted-server` MCP
-[[rule]]
-mcpName = "untrusted-server"
-decision = "deny"
-priority = 500
-```
-## Default policies
-The Gemini CLI ships with a set of default policies to provide a safe
-out-of-the-box experience.
-- **Read-only tools** (like `read_file`, `glob`) are generally **allowed**.
-- **Agent delegation** (like `delegate_to_agent`) defaults to **`ask_user`** to
-  ensure remote agents can prompt for confirmation, but local sub-agent actions
-  are executed silently and checked individually.
-- **Write tools** (like `write_file`, `run_shell_command`) default to
-  **`ask_user`**.
-- In **`yolo`** mode, a high-priority rule allows all tools.
-- In **`autoEdit`** mode, rules allow certain write operations to happen without
-  prompting.

package/dist/docs/core/tools-api.md DELETED Viewed

@@ -1,131 +0,0 @@
-# Gemini CLI core: Tools API
-The Gemini CLI core (`packages/core`) features a robust system for defining,
-registering, and executing tools. These tools extend the capabilities of the
-Gemini model, allowing it to interact with the local environment, fetch web
-content, and perform various actions beyond simple text generation.
-## Core concepts
-- **Tool (`tools.ts`):** An interface and base class (`BaseTool`) that defines
-  the contract for all tools. Each tool must have:
-  - `name`: A unique internal name (used in API calls to Gemini).
-  - `displayName`: A user-friendly name.
-  - `description`: A clear explanation of what the tool does, which is provided
-    to the Gemini model.
-  - `parameterSchema`: A JSON schema defining the parameters that the tool
-    accepts. This is crucial for the Gemini model to understand how to call the
-    tool correctly.
-  - `validateToolParams()`: A method to validate incoming parameters.
-  - `getDescription()`: A method to provide a human-readable description of what
-    the tool will do with specific parameters before execution.
-  - `shouldConfirmExecute()`: A method to determine if user confirmation is
-    required before execution (e.g., for potentially destructive operations).
-  - `execute()`: The core method that performs the tool's action and returns a
-    `ToolResult`.
-- **`ToolResult` (`tools.ts`):** An interface defining the structure of a tool's
-  execution outcome:
-  - `llmContent`: The factual content to be included in the history sent back to
-    the LLM for context. This can be a simple string or a `PartListUnion` (an
-    array of `Part` objects and strings) for rich content.
-  - `returnDisplay`: A user-friendly string (often Markdown) or a special object
-    (like `FileDiff`) for display in the CLI.
-- **Returning rich content:** Tools are not limited to returning simple text.
-  The `llmContent` can be a `PartListUnion`, which is an array that can contain
-  a mix of `Part` objects (for images, audio, etc.) and `string`s. This allows a
-  single tool execution to return multiple pieces of rich content.
-- **Tool registry (`tool-registry.ts`):** A class (`ToolRegistry`) responsible
-  for:
-  - **Registering tools:** Holding a collection of all available built-in tools
-    (e.g., `ReadFileTool`, `ShellTool`).
-  - **Discovering tools:** It can also discover tools dynamically:
-    - **Command-based discovery:** If `tools.discoveryCommand` is configured in
-      settings, this command is executed. It's expected to output JSON
-      describing custom tools, which are then registered as `DiscoveredTool`
-      instances.
-    - **MCP-based discovery:** If `mcp.serverCommand` is configured, the
-      registry can connect to a Model Context Protocol (MCP) server to list and
-      register tools (`DiscoveredMCPTool`).
-  - **Providing schemas:** Exposing the `FunctionDeclaration` schemas of all
-    registered tools to the Gemini model, so it knows what tools are available
-    and how to use them.
-  - **Retrieving tools:** Allowing the core to get a specific tool by name for
-    execution.
-## Built-in tools
-The core comes with a suite of pre-defined tools, typically found in
-`packages/core/src/tools/`. These include:
-- **File system tools:**
-  - `LSTool` (`ls.ts`): Lists directory contents.
-  - `ReadFileTool` (`read-file.ts`): Reads the content of a single file.
-  - `WriteFileTool` (`write-file.ts`): Writes content to a file.
-  - `GrepTool` (`grep.ts`): Searches for patterns in files.
-  - `GlobTool` (`glob.ts`): Finds files matching glob patterns.
-  - `EditTool` (`edit.ts`): Performs in-place modifications to files (often
-    requiring confirmation).
-  - `ReadManyFilesTool` (`read-many-files.ts`): Reads and concatenates content
-    from multiple files or glob patterns (used by the `@` command in CLI).
-- **Execution tools:**
-  - `ShellTool` (`shell.ts`): Executes arbitrary shell commands (requires
-    careful sandboxing and user confirmation).
-- **Web tools:**
-  - `WebFetchTool` (`web-fetch.ts`): Fetches content from a URL.
-  - `WebSearchTool` (`web-search.ts`): Performs a web search.
-- **Memory tools:**
-  - `MemoryTool` (`memoryTool.ts`): Interacts with the AI's memory.
-Each of these tools extends `BaseTool` and implements the required methods for
-its specific functionality.
-## Tool execution flow
-1.  **Model request:** The Gemini model, based on the user's prompt and the
-    provided tool schemas, decides to use a tool and returns a `FunctionCall`
-    part in its response, specifying the tool name and arguments.
-2.  **Core receives request:** The core parses this `FunctionCall`.
-3.  **Tool retrieval:** It looks up the requested tool in the `ToolRegistry`.
-4.  **Parameter validation:** The tool's `validateToolParams()` method is
-    called.
-5.  **Confirmation (if needed):**
-    - The tool's `shouldConfirmExecute()` method is called.
-    - If it returns details for confirmation, the core communicates this back to
-      the CLI, which prompts the user.
-    - The user's decision (e.g., proceed, cancel) is sent back to the core.
-6.  **Execution:** If validated and confirmed (or if no confirmation is needed),
-    the core calls the tool's `execute()` method with the provided arguments and
-    an `AbortSignal` (for potential cancellation).
-7.  **Result processing:** The `ToolResult` from `execute()` is received by the
-    core.
-8.  **Response to model:** The `llmContent` from the `ToolResult` is packaged as
-    a `FunctionResponse` and sent back to the Gemini model so it can continue
-    generating a user-facing response.
-9.  **Display to user:** The `returnDisplay` from the `ToolResult` is sent to
-    the CLI to show the user what the tool did.
-## Extending with custom tools
-While direct programmatic registration of new tools by users isn't explicitly
-detailed as a primary workflow in the provided files for typical end-users, the
-architecture supports extension through:
-- **Command-based discovery:** Advanced users or project administrators can
-  define a `tools.discoveryCommand` in `settings.json`. This command, when run
-  by the Gemini CLI core, should output a JSON array of `FunctionDeclaration`
-  objects. The core will then make these available as `DiscoveredTool`
-  instances. The corresponding `tools.callCommand` would then be responsible for
-  actually executing these custom tools.
-- **MCP server(s):** For more complex scenarios, one or more MCP servers can be
-  set up and configured via the `mcpServers` setting in `settings.json`. The
-  Gemini CLI core can then discover and use tools exposed by these servers. As
-  mentioned, if you have multiple MCP servers, the tool names will be prefixed
-  with the server name from your configuration (e.g.,
-  `serverAlias__actualToolName`).
-This tool system provides a flexible and powerful way to augment the Gemini
-model's capabilities, making the Gemini CLI a versatile assistant for a wide
-range of tasks.