@machina.ai/cell-cli-core 1.22.5-rc1 → 1.25.0-rc2

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

@@ -0,0 +1,131 @@
+# Cell CLI core: Tools API
+
+The Cell 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 Cell 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
+  Cell 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 Cell 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/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
+
+Cell 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 Cell 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 Cell
+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
+```

package/dist/docs/extensions/getting-started-extensions.md

@@ -0,0 +1,244 @@
+# Getting started with Cell CLI extensions
+
+This guide will walk you through creating your first Cell CLI extension. You'll
+learn how to set up a new extension, add a custom tool via an MCP server, create
+a custom command, and provide context to the model with a `GEMINI.md` file.
+
+## Prerequisites
+
+Before you start, make sure you have the Cell CLI installed and a basic
+understanding of Node.js and TypeScript.
+
+## Step 1: Create a new extension
+
+The easiest way to start is by using one of the built-in templates. We'll use
+the `mcp-server` example as our foundation.
+
+Run the following command to create a new directory called `my-first-extension`
+with the template files:
+
+```bash
+gemini extensions new my-first-extension mcp-server
+```
+
+This will create a new directory with the following structure:
+
+```
+my-first-extension/
+├── example.ts
+├── gemini-extension.json
+├── package.json
+└── tsconfig.json
+```
+
+## Step 2: Understand the extension files
+
+Let's look at the key files in your new extension.
+
+### `gemini-extension.json`
+
+This is the manifest file for your extension. It tells Cell CLI how to load and
+use your extension.
+
+```json
+{
+  "name": "my-first-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "nodeServer": {
+      "command": "node",
+      "args": ["${extensionPath}${/}dist${/}example.js"],
+      "cwd": "${extensionPath}"
+    }
+  }
+}
+```
+
+- `name`: The unique name for your extension.
+- `version`: The version of your extension.
+- `mcpServers`: This section defines one or more Model Context Protocol (MCP)
+  servers. MCP servers are how you can add new tools for the model to use.
+  - `command`, `args`, `cwd`: These fields specify how to start your server.
+    Notice the use of the `${extensionPath}` variable, which Cell CLI replaces
+    with the absolute path to your extension's installation directory. This
+    allows your extension to work regardless of where it's installed.
+
+### `example.ts`
+
+This file contains the source code for your MCP server. It's a simple Node.js
+server that uses the `@modelcontextprotocol/sdk`.
+
+```typescript
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({
+  name: 'prompt-server',
+  version: '1.0.0',
+});
+
+// Registers a new tool named 'fetch_posts'
+server.registerTool(
+  'fetch_posts',
+  {
+    description: 'Fetches a list of posts from a public API.',
+    inputSchema: z.object({}).shape,
+  },
+  async () => {
+    const apiResponse = await fetch(
+      'https://jsonplaceholder.typicode.com/posts',
+    );
+    const posts = await apiResponse.json();
+    const response = { posts: posts.slice(0, 5) };
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response),
+        },
+      ],
+    };
+  },
+);
+
+// ... (prompt registration omitted for brevity)
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+This server defines a single tool called `fetch_posts` that fetches data from a
+public API.
+
+### `package.json` and `tsconfig.json`
+
+These are standard configuration files for a TypeScript project. The
+`package.json` file defines dependencies and a `build` script, and
+`tsconfig.json` configures the TypeScript compiler.
+
+## Step 3: Build and link your extension
+
+Before you can use the extension, you need to compile the TypeScript code and
+link the extension to your Cell CLI installation for local development.
+
+1.  **Install dependencies:**
+
+    ```bash
+    cd my-first-extension
+    npm install
+    ```
+
+2.  **Build the server:**
+
+    ```bash
+    npm run build
+    ```
+
+    This will compile `example.ts` into `dist/example.js`, which is the file
+    referenced in your `gemini-extension.json`.
+
+3.  **Link the extension:**
+
+    The `link` command creates a symbolic link from the Cell CLI extensions
+    directory to your development directory. This means any changes you make
+    will be reflected immediately without needing to reinstall.
+
+    ```bash
+    gemini extensions link .
+    ```
+
+Now, restart your Cell CLI session. The new `fetch_posts` tool will be
+available. You can test it by asking: "fetch posts".
+
+## Step 4: Add a custom command
+
+Custom commands provide a way to create shortcuts for complex prompts. Let's add
+a command that searches for a pattern in your code.
+
+1.  Create a `commands` directory and a subdirectory for your command group:
+
+    ```bash
+    mkdir -p commands/fs
+    ```
+
+2.  Create a file named `commands/fs/grep-code.toml`:
+
+    ```toml
+    prompt = """
+    Please summarize the findings for the pattern `{{args}}`.
+
+    Search Results:
+    !{grep -r {{args}} .}
+    """
+    ```
+
+    This command, `/fs:grep-code`, will take an argument, run the `grep` shell
+    command with it, and pipe the results into a prompt for summarization.
+
+After saving the file, restart the Cell CLI. You can now run
+`/fs:grep-code "some pattern"` to use your new command.
+
+## Step 5: Add a custom `GEMINI.md`
+
+You can provide persistent context to the model by adding a `GEMINI.md` file to
+your extension. This is useful for giving the model instructions on how to
+behave or information about your extension's tools. Note that you may not always
+need this for extensions built to expose commands and prompts.
+
+1.  Create a file named `GEMINI.md` in the root of your extension directory:
+
+    ```markdown
+    # My First Extension Instructions
+
+    You are an expert developer assistant. When the user asks you to fetch
+    posts, use the `fetch_posts` tool. Be concise in your responses.
+    ```
+
+2.  Update your `gemini-extension.json` to tell the CLI to load this file:
+
+    ```json
+    {
+      "name": "my-first-extension",
+      "version": "1.0.0",
+      "contextFileName": "GEMINI.md",
+      "mcpServers": {
+        "nodeServer": {
+          "command": "node",
+          "args": ["${extensionPath}${/}dist${/}example.js"],
+          "cwd": "${extensionPath}"
+        }
+      }
+    }
+    ```
+
+Restart the CLI again. The model will now have the context from your `GEMINI.md`
+file in every session where the extension is active.
+
+## Step 6: Releasing your extension
+
+Once you are happy with your extension, you can share it with others. The two
+primary ways of releasing extensions are via a Git repository or through GitHub
+Releases. Using a public Git repository is the simplest method.
+
+For detailed instructions on both methods, please refer to the
+[Extension Releasing Guide](./extension-releasing.md).
+
+## Conclusion
+
+You've successfully created a Cell CLI extension! You learned how to:
+
+- Bootstrap a new extension from a template.
+- Add custom tools with an MCP server.
+- Create convenient custom commands.
+- Provide persistent context to the model.
+- Link your extension for local development.
+
+From here, you can explore more advanced features and build powerful new
+capabilities into the Cell CLI.