@office-ai/aioncli-core 0.18.7 → 0.24.0

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

@@ -0,0 +1,131 @@
+# 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.

package/dist/docs/examples/proxy-script.md

@@ -0,0 +1,83 @@
+# Example proxy script
+
+The following is an example of a proxy script that can be used with the
+`GEMINI_SANDBOX_PROXY_COMMAND` environment variable. This script only allows
+`HTTPS` connections to `example.com:443` and declines all other requests.
+
+```javascript
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Example proxy server that listens on :::8877 and only allows HTTPS connections to example.com.
+// Set `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js` to run proxy alongside sandbox
+// Test via `curl https://example.com` inside sandbox (in shell mode or via shell tool)
+
+import http from 'node:http';
+import net from 'node:net';
+import { URL } from 'node:url';
+import console from 'node:console';
+
+const PROXY_PORT = 8877;
+const ALLOWED_DOMAINS = ['example.com', 'googleapis.com'];
+const ALLOWED_PORT = '443';
+
+const server = http.createServer((req, res) => {
+  // Deny all requests other than CONNECT for HTTPS
+  console.log(
+    `[PROXY] Denying non-CONNECT request for: ${req.method} ${req.url}`,
+  );
+  res.writeHead(405, { 'Content-Type': 'text/plain' });
+  res.end('Method Not Allowed');
+});
+
+server.on('connect', (req, clientSocket, head) => {
+  // req.url will be in the format "hostname:port" for a CONNECT request.
+  const { port, hostname } = new URL(`http://${req.url}`);
+
+  console.log(`[PROXY] Intercepted CONNECT request for: ${hostname}:${port}`);
+
+  if (
+    ALLOWED_DOMAINS.some(
+      (domain) => hostname == domain || hostname.endsWith(`.${domain}`),
+    ) &&
+    port === ALLOWED_PORT
+  ) {
+    console.log(`[PROXY] Allowing connection to ${hostname}:${port}`);
+
+    // Establish a TCP connection to the original destination.
+    const serverSocket = net.connect(port, hostname, () => {
+      clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      // Create a tunnel by piping data between the client and the destination server.
+      serverSocket.write(head);
+      serverSocket.pipe(clientSocket);
+      clientSocket.pipe(serverSocket);
+    });
+
+    serverSocket.on('error', (err) => {
+      console.error(`[PROXY] Error connecting to destination: ${err.message}`);
+      clientSocket.end(`HTTP/1.1 502 Bad Gateway\r\n\r\n`);
+    });
+  } else {
+    console.log(`[PROXY] Denying connection to ${hostname}:${port}`);
+    clientSocket.end('HTTP/1.1 403 Forbidden\r\n\r\n');
+  }
+
+  clientSocket.on('error', (err) => {
+    // This can happen if the client hangs up.
+    console.error(`[PROXY] Client socket error: ${err.message}`);
+  });
+});
+
+server.listen(PROXY_PORT, () => {
+  const address = server.address();
+  console.log(`[PROXY] Proxy listening on ${address.address}:${address.port}`);
+  console.log(
+    `[PROXY] Allowing HTTPS connections to domains: ${ALLOWED_DOMAINS.join(', ')}`,
+  );
+});
+```

package/dist/docs/extension.md

@@ -0,0 +1,160 @@
+# Gemini CLI Extensions
+
+_This documentation is up-to-date with the v0.4.0 release._
+
+Gemini CLI extensions package prompts, MCP servers, and custom commands into a familiar and user-friendly format. With extensions, you can expand the capabilities of Gemini CLI and share those capabilities with others. They are designed to be easily installable and shareable.
+
+## Extension management
+
+We offer a suite of extension management tools using `gemini extensions` commands.
+
+Note that these commands are not supported from within the CLI, although you can list installed extensions using the `/extensions list` subcommand.
+
+Note that all of these commands will only be reflected in active CLI sessions on restart.
+
+### Installing an extension
+
+You can install an extension using `gemini extensions install` with either a GitHub URL or a local path`.
+
+Note that we create a copy of the installed extension, so you will need to run `gemini extensions update` to pull in changes from both locally-defined extensions and those on GitHub.
+
+```
+gemini extensions install https://github.com/gemini-cli-extensions/security
+```
+
+This will install the Gemini CLI Security extension, which offers support for a `/security:analyze` command.
+
+### Uninstalling an extension
+
+To uninstall, run `gemini extensions uninstall extension-name`, so, in the case of the install example:
+
+```
+gemini extensions uninstall gemini-cli-security
+```
+
+### Disabling an extension
+
+Extensions are, by default, enabled across all workspaces. You can disable an extension entirely or for specific workspace.
+
+For example, `gemini extensions disable extension-name` will disable the extension at the user level, so it will be disabled everywhere. `gemini extensions disable extension-name --scope=workspace` will only disable the extension in the current workspace.
+
+### Enabling an extension
+
+You can enable extensions using `gemini extensions enable extension-name`. You can also enable an extension for a specific workspace using `gemini extensions enable extension-name --scope=workspace` from within that workspace.
+
+This is useful if you have an extension disabled at the top-level and only enabled in specific places.
+
+### Updating an extension
+
+For extensions installed from a local path or a git repository, you can explicitly update to the latest version (as reflected in the `gemini-extension.json` `version` field) with `gemini extensions update extension-name`.
+
+You can update all extensions with:
+
+```
+gemini extensions update --all
+```
+
+## Extension creation
+
+We offer commands to make extension development easier.
+
+### Create a boilerplate extension
+
+We offer several example extensions `context`, `custom-commands`, `exclude-tools` and `mcp-server`. You can view these examples [here](https://github.com/google-gemini/gemini-cli/tree/main/packages/cli/src/commands/extensions/examples).
+
+To copy one of these examples into a development directory using the type of your choosing, run:
+
+```
+gemini extensions new path/to/directory custom-commands
+```
+
+### Link a local extension
+
+The `gemini extensions link` command will create a symbolic link from the extension installation directory to the development path.
+
+This is useful so you don't have to run `gemini extensions update` every time you make changes you'd like to test.
+
+```
+gemini extensions link path/to/directory
+```
+
+## How it works
+
+On startup, Gemini CLI looks for extensions in `<home>/.gemini/extensions`
+
+Extensions exist as a directory that contains a `gemini-extension.json` file. For example:
+
+`<home>/.gemini/extensions/my-extension/gemini-extension.json`
+
+### `gemini-extension.json`
+
+The `gemini-extension.json` file contains the configuration for the extension. The file has the following structure:
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"
+    }
+  },
+  "contextFileName": "GEMINI.md",
+  "excludeTools": ["run_shell_command"]
+}
+```
+
+- `name`: The name of the extension. This is used to uniquely identify the extension and for conflict resolution when extension commands have the same name as user or project commands. The name should be lowercase or numbers and use dashes instead of underscores or spaces. This is how users will refer to your extension in the CLI. Note that we expect this name to match the extension directory name.
+- `version`: The version of the extension.
+- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a [`settings.json` file](./cli/configuration.md). If both an extension and a `settings.json` file configure an MCP server with the same name, the server defined in the `settings.json` file takes precedence.
+  - Note that all MCP server configuration options are supported except for `trust`.
+- `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the extension directory. If this property is not used but a `GEMINI.md` file is present in your extension directory, then that file will be loaded.
+- `excludeTools`: An array of tool names to exclude from the model. You can also specify command-specific restrictions for tools that support it, like the `run_shell_command` tool. For example, `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf` command. Note that this differs from the MCP server `excludeTools` functionality, which can be listed in the MCP server config.
+
+When Gemini CLI starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes precedence.
+
+### Custom commands
+
+Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing TOML files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.
+
+**Example**
+
+An extension named `gcp` with the following structure:
+
+```
+.gemini/extensions/gcp/
+├── gemini-extension.json
+└── commands/
+    ├── deploy.toml
+    └── gcs/
+        └── sync.toml
+```
+
+Would provide these commands:
+
+- `/deploy` - Shows as `[gcp] Custom command from deploy.toml` in help
+- `/gcs:sync` - Shows as `[gcp] Custom command from sync.toml` in help
+
+### Conflict resolution
+
+Extension commands have the lowest precedence. When a conflict occurs with user or project commands:
+
+1. **No conflict**: Extension command uses its natural name (e.g., `/deploy`)
+2. **With conflict**: Extension command is renamed with the extension prefix (e.g., `/gcp.deploy`)
+
+For example, if both a user and the `gcp` extension define a `deploy` command:
+
+- `/deploy` - Executes the user's deploy command
+- `/gcp.deploy` - Executes the extension's deploy command (marked with `[gcp]` tag)
+
+## Variables
+
+Gemini CLI extensions allow variable substitution in `gemini-extension.json`. This can be useful if e.g., you need the current directory to run an MCP server using `"cwd": "${extensionPath}${/}run.ts"`.
+
+**Supported variables:**
+
+| variable                   | description                                                                                                                                                     |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `${extensionPath}`         | The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.gemini/extensions/example-extension'. This will not unwrap symlinks. |
+| `${workspacePath}`         | The fully-qualified path of the current workspace.                                                                                                              |
+| `${/} or ${pathSeparator}` | The path separator (differs per OS).                                                                                                                            |

package/dist/docs/extensions/extension-releasing.md

@@ -0,0 +1,183 @@
+# Extension releasing
+
+There are two primary ways of releasing extensions to users:
+
+- [Git repository](#releasing-through-a-git-repository)
+- [Github Releases](#releasing-through-github-releases)
+
+Git repository releases tend to be the simplest and most flexible approach,
+while GitHub releases can be more efficient on initial install as they are
+shipped as single archives instead of requiring a git clone which downloads each
+file individually. Github releases may also contain platform specific archives
+if you need to ship platform specific binary files.
+
+## Releasing through a git repository
+
+This is the most flexible and simple option. All you need to do is create a
+publicly accessible git repo (such as a public github repository) and then users
+can install your extension using `gemini extensions install <your-repo-uri>`.
+They can optionally depend on a specific ref (branch/tag/commit) using the
+`--ref=<some-ref>` argument, this defaults to the default branch.
+
+Whenever commits are pushed to the ref that a user depends on, they will be
+prompted to update the extension. Note that this also allows for easy rollbacks,
+the HEAD commit is always treated as the latest version regardless of the actual
+version in the `gemini-extension.json` file.
+
+### Managing release channels using a git repository
+
+Users can depend on any ref from your git repo, such as a branch or tag, which
+allows you to manage multiple release channels.
+
+For instance, you can maintain a `stable` branch, which users can install this
+way `gemini extensions install <your-repo-uri> --ref=stable`. Or, you could make
+this the default by treating your default branch as your stable release branch,
+and doing development in a different branch (for instance called `dev`). You can
+maintain as many branches or tags as you like, providing maximum flexibility for
+you and your users.
+
+Note that these `ref` arguments can be tags, branches, or even specific commits,
+which allows users to depend on a specific version of your extension. It is up
+to you how you want to manage your tags and branches.
+
+### Example releasing flow using a git repo
+
+While there are many options for how you want to manage releases using a git
+flow, we recommend treating your default branch as your "stable" release branch.
+This means that the default behavior for
+`gemini extensions install <your-repo-uri>` is to be on the stable release
+branch.
+
+Lets say you want to maintain three standard release channels, `stable`,
+`preview`, and `dev`. You would do all your standard development in the `dev`
+branch. When you are ready to do a preview release, you merge that branch into
+your `preview` branch. When you are ready to promote your preview branch to
+stable, you merge `preview` into your stable branch (which might be your default
+branch or a different branch).
+
+You can also cherry pick changes from one branch into another using
+`git cherry-pick`, but do note that this will result in your branches having a
+slightly divergent history from each other, unless you force push changes to
+your branches on each release to restore the history to a clean slate (which may
+not be possible for the default branch depending on your repository settings).
+If you plan on doing cherry picks, you may want to avoid having your default
+branch be the stable branch to avoid force-pushing to the default branch which
+should generally be avoided.
+
+## Releasing through GitHub releases
+
+Gemini CLI extensions can be distributed through
+[GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases).
+This provides a faster and more reliable initial installation experience for
+users, as it avoids the need to clone the repository.
+
+Each release includes at least one archive file, which contains the full
+contents of the repo at the tag that it was linked to. Releases may also include
+[pre-built archives](#custom-pre-built-archives) if your extension requires some
+build step or has platform specific binaries attached to it.
+
+When checking for updates, gemini will just look for the "latest" release on
+github (you must mark it as such when creating the release), unless the user
+installed a specific release by passing `--ref=<some-release-tag>`.
+
+You may also install extensions with the `--pre-release` flag in order to get
+the latest release regardless of whether it has been marked as "latest". This
+allows you to test that your release works before actually pushing it to all
+users.
+
+### Custom pre-built archives
+
+Custom archives must be attached directly to the github release as assets and
+must be fully self-contained. This means they should include the entire
+extension, see [archive structure](#archive-structure).
+
+If your extension is platform-independent, you can provide a single generic
+asset. In this case, there should be only one asset attached to the release.
+
+Custom archives may also be used if you want to develop your extension within a
+larger repository, you can build an archive which has a different layout from
+the repo itself (for instance it might just be an archive of a subdirectory
+containing the extension).
+
+#### Platform specific archives
+
+To ensure Gemini CLI can automatically find the correct release asset for each
+platform, you must follow this naming convention. The CLI will search for assets
+in the following order:
+
+1.  **Platform and architecture-Specific:**
+    `{platform}.{arch}.{name}.{extension}`
+2.  **Platform-specific:** `{platform}.{name}.{extension}`
+3.  **Generic:** If only one asset is provided, it will be used as a generic
+    fallback.
+
+- `{name}`: The name of your extension.
+- `{platform}`: The operating system. Supported values are:
+  - `darwin` (macOS)
+  - `linux`
+  - `win32` (Windows)
+- `{arch}`: The architecture. Supported values are:
+  - `x64`
+  - `arm64`
+- `{extension}`: The file extension of the archive (e.g., `.tar.gz` or `.zip`).
+
+**Examples:**
+
+- `darwin.arm64.my-tool.tar.gz` (specific to Apple Silicon Macs)
+- `darwin.my-tool.tar.gz` (for all Macs)
+- `linux.x64.my-tool.tar.gz`
+- `win32.my-tool.zip`
+
+#### Archive structure
+
+Archives must be fully contained extensions and have all the standard
+requirements - specifically the `gemini-extension.json` file must be at the root
+of the archive.
+
+The rest of the layout should look exactly the same as a typical extension, see
+[extensions.md](./index.md).
+
+#### Example GitHub Actions workflow
+
+Here is an example of a GitHub Actions workflow that builds and releases a
+Gemini CLI extension for multiple platforms:
+
+```yaml
+name: Release Extension
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build extension
+        run: npm run build
+
+      - name: Create release assets
+        run: |
+          npm run package -- --platform=darwin --arch=arm64
+          npm run package -- --platform=linux --arch=x64
+          npm run package -- --platform=win32 --arch=x64
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            release/darwin.arm64.my-tool.tar.gz
+            release/linux.arm64.my-tool.tar.gz
+            release/win32.arm64.my-tool.zip
+```