@terminai/core 0.21.0

package/dist/docs/issue-and-pr-automation.md

@@ -0,0 +1,134 @@
+# Automation and triage processes
+
+This document provides a detailed overview of the automated processes we use to
+manage and triage issues and pull requests. Our goal is to provide prompt
+feedback and ensure that contributions are reviewed and integrated efficiently.
+Understanding this automation will help you as a contributor know what to expect
+and how to best interact with our repository bots.
+
+## Guiding principle: Issues and pull requests
+
+First and foremost, almost every Pull Request (PR) should be linked to a
+corresponding Issue. The issue describes the "what" and the "why" (the bug or
+feature), while the PR is the "how" (the implementation). This separation helps
+us track work, prioritize features, and maintain clear historical context. Our
+automation is built around this principle.
+
+> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
+> maintainers. We will not accept pull requests related to these issues.
+
+---
+
+## Detailed automation workflows
+
+Here is a breakdown of the specific automation workflows that run in our
+repository.
+
+### 1. When you open an issue: `Automated Issue Triage`
+
+This is the first bot you will interact with when you create an issue. Its job
+is to perform an initial analysis and apply the correct labels.
+
+- **Workflow File**: `.github/workflows/gemini-automated-issue-triage.yml`
+- **When it runs**: Immediately after an issue is created or reopened.
+- **What it does**:
+  - It uses a Gemini model to analyze the issue's title and body against a
+    detailed set of guidelines.
+  - **Applies one `area/*` label**: Categorizes the issue into a functional area
+    of the project (e.g., `area/ux`, `area/models`, `area/platform`).
+  - **Applies one `kind/*` label**: Identifies the type of issue (e.g.,
+    `kind/bug`, `kind/enhancement`, `kind/question`).
+  - **Applies one `priority/*` label**: Assigns a priority from P0 (critical) to
+    P3 (low) based on the described impact.
+  - **May apply `status/need-information`**: If the issue lacks critical details
+    (like logs or reproduction steps), it will be flagged for more information.
+  - **May apply `status/need-retesting`**: If the issue references a CLI version
+    that is more than six versions old, it will be flagged for retesting on a
+    current version.
+- **What you should do**:
+  - Fill out the issue template as completely as possible. The more detail you
+    provide, the more accurate the triage will be.
+  - If the `status/need-information` label is added, please provide the
+    requested details in a comment.
+
+### 2. When you open a pull request: `Continuous Integration (CI)`
+
+This workflow ensures that all changes meet our quality standards before they
+can be merged.
+
+- **Workflow File**: `.github/workflows/ci.yml`
+- **When it runs**: On every push to a pull request.
+- **What it does**:
+  - **Lint**: Checks that your code adheres to our project's formatting and
+    style rules.
+  - **Test**: Runs our full suite of automated tests across macOS, Windows, and
+    Linux, and on multiple Node.js versions. This is the most time-consuming
+    part of the CI process.
+  - **Post Coverage Comment**: After all tests have successfully passed, a bot
+    will post a comment on your PR. This comment provides a summary of how well
+    your changes are covered by tests.
+- **What you should do**:
+  - Ensure all CI checks pass. A green checkmark ✅ will appear next to your
+    commit when everything is successful.
+  - If a check fails (a red "X" ❌), click the "Details" link next to the failed
+    check to view the logs, identify the problem, and push a fix.
+
+### 3. Ongoing triage for pull requests: `PR Auditing and Label Sync`
+
+This workflow runs periodically to ensure all open PRs are correctly linked to
+issues and have consistent labels.
+
+- **Workflow File**: `.github/workflows/gemini-scheduled-pr-triage.yml`
+- **When it runs**: Every 15 minutes on all open pull requests.
+- **What it does**:
+  - **Checks for a linked issue**: The bot scans your PR description for a
+    keyword that links it to an issue (e.g., `Fixes #123`, `Closes #456`).
+  - **Adds `status/need-issue`**: If no linked issue is found, the bot will add
+    the `status/need-issue` label to your PR. This is a clear signal that an
+    issue needs to be created and linked.
+  - **Synchronizes labels**: If an issue _is_ linked, the bot ensures the PR's
+    labels perfectly match the issue's labels. It will add any missing labels
+    and remove any that don't belong, and it will remove the `status/need-issue`
+    label if it was present.
+- **What you should do**:
+  - **Always link your PR to an issue.** This is the most important step. Add a
+    line like `Resolves #<issue-number>` to your PR description.
+  - This will ensure your PR is correctly categorized and moves through the
+    review process smoothly.
+
+### 4. Ongoing triage for issues: `Scheduled Issue Triage`
+
+This is a fallback workflow to ensure that no issue gets missed by the triage
+process.
+
+- **Workflow File**: `.github/workflows/gemini-scheduled-issue-triage.yml`
+- **When it runs**: Every hour on all open issues.
+- **What it does**:
+  - It actively seeks out issues that either have no labels at all or still have
+    the `status/need-triage` label.
+  - It then triggers the same powerful Gemini-based analysis as the initial
+    triage bot to apply the correct labels.
+- **What you should do**:
+  - You typically don't need to do anything. This workflow is a safety net to
+    ensure every issue is eventually categorized, even if the initial triage
+    fails.
+
+### 5. Release automation
+
+This workflow handles the process of packaging and publishing new versions of
+the Gemini CLI.
+
+- **Workflow File**: `.github/workflows/release-manual.yml`
+- **When it runs**: On a daily schedule for "nightly" releases, and manually for
+  official patch/minor releases.
+- **What it does**:
+  - Automatically builds the project, bumps the version numbers, and publishes
+    the packages to npm.
+  - Creates a corresponding release on GitHub with generated release notes.
+- **What you should do**:
+  - As a contributor, you don't need to do anything for this process. You can be
+    confident that once your PR is merged into the `main` branch, your changes
+    will be included in the very next nightly release.
+
+We hope this detailed overview is helpful. If you have any questions about our
+automation or processes, please don't hesitate to ask!

package/dist/docs/local-development.md

@@ -0,0 +1,129 @@
+# Local development guide
+
+This guide provides instructions for setting up and using local development
+features, such as development tracing.
+
+## Development tracing
+
+Development traces (dev traces) are OpenTelemetry (OTel) traces that help you
+debug your code by instrumenting interesting events like model calls, tool
+scheduler, tool calls, etc.
+
+Dev traces are verbose and are specifically meant for understanding agent
+behaviour and debugging issues. They are disabled by default.
+
+To enable dev traces, set the `TERMINAI_DEV_TRACING=true` environment variable
+when running Gemini CLI (preferred binary name is `terminai`; `gemini` is a
+compatibility alias).
+
+### Viewing dev traces
+
+You can view dev traces using either Jaeger or the Genkit Developer UI.
+
+#### Using Genkit
+
+Genkit provides a web-based UI for viewing traces and other telemetry data.
+
+1.  **Start the Genkit telemetry server:**
+
+    Run the following command to start the Genkit server:
+
+    ```bash
+    npm run telemetry -- --target=genkit
+    ```
+
+    The script will output the URL for the Genkit Developer UI, for example:
+
+    ```
+    Genkit Developer UI: http://localhost:4000
+    ```
+
+2.  **Run Gemini CLI with dev tracing:**
+
+    In a separate terminal, run your Gemini CLI command with the
+    `TERMINAI_DEV_TRACING` environment variable:
+
+    ```bash
+    TERMINAI_DEV_TRACING=true terminai
+    ```
+
+3.  **View the traces:**
+
+    Open the Genkit Developer UI URL in your browser and navigate to the
+    **Traces** tab to view the traces.
+
+#### Using Jaeger
+
+You can view dev traces in the Jaeger UI. To get started, follow these steps:
+
+1.  **Start the telemetry collector:**
+
+    Run the following command in your terminal to download and start Jaeger and
+    an OTEL collector:
+
+    ```bash
+    npm run telemetry -- --target=local
+    ```
+
+    This command also configures your workspace for local telemetry and provides
+    a link to the Jaeger UI (usually `http://localhost:16686`).
+
+2.  **Run Gemini CLI with dev tracing:**
+
+    In a separate terminal, run your Gemini CLI command with the
+    `TERMINAI_DEV_TRACING` environment variable:
+
+    ```bash
+    TERMINAI_DEV_TRACING=true terminai
+    ```
+
+3.  **View the traces:**
+
+    After running your command, open the Jaeger UI link in your browser to view
+    the traces.
+
+For more detailed information on telemetry, see the
+[telemetry documentation](./cli/telemetry.md).
+
+### Instrumenting code with dev traces
+
+You can add dev traces to your own code for more detailed instrumentation. This
+is useful for debugging and understanding the flow of execution.
+
+Use the `runInDevTraceSpan` function to wrap any section of code in a trace
+span.
+
+Here is a basic example:
+
+```typescript
+import { runInDevTraceSpan } from '@google/gemini-cli-core';
+
+await runInDevTraceSpan({ name: 'my-custom-span' }, async ({ metadata }) => {
+  // The `metadata` object allows you to record the input and output of the
+  // operation as well as other attributes.
+  metadata.input = { key: 'value' };
+  // Set custom attributes.
+  metadata.attributes['gen_ai.request.model'] = 'gemini-2.5-flash-mega';
+
+  // Your code to be traced goes here
+  try {
+    const output = await somethingRisky();
+    metadata.output = output;
+    return output;
+  } catch (e) {
+    metadata.error = e;
+    throw e;
+  }
+});
+```
+
+In this example:
+
+- `name`: The name of the span, which will be displayed in the trace.
+- `metadata.input`: (Optional) An object containing the input data for the
+  traced operation.
+- `metadata.output`: (Optional) An object containing the output data from the
+  traced operation.
+- `metadata.attributes`: (Optional) A record of custom attributes to add to the
+  span.
+- `metadata.error`: (Optional) An error object to record if the operation fails.

package/dist/docs/mermaid/context.mmd

@@ -0,0 +1,103 @@
+graph LR
+    %% --- Style Definitions ---
+    classDef new fill:#98fb98,color:#000
+    classDef changed fill:#add8e6,color:#000
+    classDef unchanged fill:#f0f0f0,color:#000
+
+    %% --- Subgraphs ---
+    subgraph "Context Providers"
+        direction TB
+        A["gemini.tsx"]
+        B["AppContainer.tsx"]
+    end
+
+    subgraph "Contexts"
+        direction TB
+        CtxSession["SessionContext"]
+        CtxVim["VimModeContext"]
+        CtxSettings["SettingsContext"]
+        CtxApp["AppContext"]
+        CtxConfig["ConfigContext"]
+        CtxUIState["UIStateContext"]
+        CtxUIActions["UIActionsContext"]
+    end
+
+    subgraph "Component Consumers"
+        direction TB
+        ConsumerApp["App"]
+        ConsumerAppContainer["AppContainer"]
+        ConsumerAppHeader["AppHeader"]
+        ConsumerDialogManager["DialogManager"]
+        ConsumerHistoryItem["HistoryItemDisplay"]
+        ConsumerComposer["Composer"]
+        ConsumerMainContent["MainContent"]
+        ConsumerNotifications["Notifications"]
+    end
+
+    %% --- Provider -> Context Connections ---
+    A -.-> CtxSession
+    A -.-> CtxVim
+    A -.-> CtxSettings
+
+    B -.-> CtxApp
+    B -.-> CtxConfig
+    B -.-> CtxUIState
+    B -.-> CtxUIActions
+    B -.-> CtxSettings
+
+    %% --- Context -> Consumer Connections ---
+    CtxSession -.-> ConsumerAppContainer
+    CtxSession -.-> ConsumerApp
+
+    CtxVim -.-> ConsumerAppContainer
+    CtxVim -.-> ConsumerComposer
+    CtxVim -.-> ConsumerApp
+
+    CtxSettings -.-> ConsumerAppContainer
+    CtxSettings -.-> ConsumerAppHeader
+    CtxSettings -.-> ConsumerDialogManager
+    CtxSettings -.-> ConsumerApp
+
+    CtxApp -.-> ConsumerAppHeader
+    CtxApp -.-> ConsumerNotifications
+
+    CtxConfig -.-> ConsumerAppHeader
+    CtxConfig -.-> ConsumerHistoryItem
+    CtxConfig -.-> ConsumerComposer
+    CtxConfig -.-> ConsumerDialogManager
+
+
+
+    CtxUIState -.-> ConsumerApp
+    CtxUIState -.-> ConsumerMainContent
+    CtxUIState -.-> ConsumerComposer
+    CtxUIState -.-> ConsumerDialogManager
+
+    CtxUIActions -.-> ConsumerComposer
+    CtxUIActions -.-> ConsumerDialogManager
+
+    %% --- Apply Styles ---
+    %% New Elements (Green)
+    class B,CtxApp,CtxConfig,CtxUIState,CtxUIActions,ConsumerAppHeader,ConsumerDialogManager,ConsumerComposer,ConsumerMainContent,ConsumerNotifications new
+
+    %% Heavily Changed Elements (Blue)
+    class A,ConsumerApp,ConsumerAppContainer,ConsumerHistoryItem changed
+
+    %% Mostly Unchanged Elements (Gray)
+    class CtxSession,CtxVim,CtxSettings unchanged
+
+    %% --- Link Styles ---
+    %% CtxSession (Red)
+    linkStyle 0,8,9 stroke:#e57373,stroke-width:2px
+    %% CtxVim (Orange)
+    linkStyle 1,10,11,12 stroke:#ffb74d,stroke-width:2px
+    %% CtxSettings (Yellow)
+    linkStyle 2,7,13,14,15,16 stroke:#fff176,stroke-width:2px
+    %% CtxApp (Green)
+    linkStyle 3,17,18 stroke:#81c784,stroke-width:2px
+    %% CtxConfig (Blue)
+    linkStyle 4,19,20,21,22 stroke:#64b5f6,stroke-width:2px
+    %% CtxUIState (Indigo)
+    linkStyle 5,23,24,25,26 stroke:#7986cb,stroke-width:2px
+    %% CtxUIActions (Violet)
+    linkStyle 6,27,28 stroke:#ba68c8,stroke-width:2px

package/dist/docs/mermaid/render-path.mmd

@@ -0,0 +1,64 @@
+graph TD
+    %% --- Style Definitions ---
+    classDef new fill:#98fb98,color:#000
+    classDef changed fill:#add8e6,color:#000
+    classDef unchanged fill:#f0f0f0,color:#000
+    classDef dispatcher fill:#f9e79f,color:#000,stroke:#333,stroke-width:1px
+    classDef container fill:#f5f5f5,color:#000,stroke:#ccc
+
+    %% --- Component Tree ---
+    subgraph "Entry Point"
+      A["gemini.tsx"]
+    end
+
+    subgraph "State & Logic Wrapper"
+      B["AppContainer.tsx"]
+    end
+
+    subgraph "Primary Layout"
+      C["App.tsx"]
+    end
+
+    A -.-> B
+    B -.-> C
+
+    subgraph "UI Containers"
+        direction LR
+        C -.-> D["MainContent"]
+        C -.-> G["Composer"]
+        C -.-> F["DialogManager"]
+        C -.-> E["Notifications"]
+    end
+
+    subgraph "MainContent"
+        direction TB
+        D -.-> H["AppHeader"]
+        D -.-> I["HistoryItemDisplay"]:::dispatcher
+        D -.-> L["ShowMoreLines"]
+    end
+
+    subgraph "Composer"
+        direction TB
+        G -.-> K_Prompt["InputPrompt"]
+        G -.-> K_Footer["Footer"]
+    end
+
+    subgraph "DialogManager"
+        F -.-> J["Various Dialogs<br>(Auth, Theme, Settings, etc.)"]
+    end
+
+    %% --- Apply Styles ---
+    class B,D,E,F,G,H,J,K_Prompt,L new
+    class A,C,I changed
+    class K_Footer unchanged
+
+    %% --- Link Styles ---
+    %% MainContent Branch (Blue)
+    linkStyle 2,6,7,8 stroke:#64b5f6,stroke-width:2px
+    %% Composer Branch (Green)
+    linkStyle 3,9,10 stroke:#81c784,stroke-width:2px
+    %% DialogManager Branch (Orange)
+    linkStyle 4,11 stroke:#ffb74d,stroke-width:2px
+    %% Notifications Branch (Violet)
+    linkStyle 5 stroke:#ba68c8,stroke-width:2px
+

package/dist/docs/npm.md

@@ -0,0 +1,62 @@
+# Package overview
+
+This monorepo contains two main packages: `@google/gemini-cli` and
+`@google/gemini-cli-core`.
+
+## `@google/gemini-cli`
+
+This is the main package for the Gemini CLI. It is responsible for the user
+interface, command parsing, and all other user-facing functionality.
+
+When this package is published, it is bundled into a single executable file.
+This bundle includes all of the package's dependencies, including
+`@google/gemini-cli-core`. This means that whether a user installs the package
+with `npm install -g @google/gemini-cli` or runs it directly with
+`npx @google/gemini-cli`, they are using this single, self-contained executable.
+
+## `@google/gemini-cli-core`
+
+This package contains the core logic for interacting with the Gemini API. It is
+responsible for making API requests, handling authentication, and managing the
+local cache.
+
+This package is not bundled. When it is published, it is published as a standard
+Node.js package with its own dependencies. This allows it to be used as a
+standalone package in other projects, if needed. All transpiled js code in the
+`dist` folder is included in the package.
+
+## NPM workspaces
+
+This project uses
+[NPM Workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces) to manage
+the packages within this monorepo. This simplifies development by allowing us to
+manage dependencies and run scripts across multiple packages from the root of
+the project.
+
+### How it works
+
+The root `package.json` file defines the workspaces for this project:
+
+```json
+{
+  "workspaces": ["packages/*"]
+}
+```
+
+This tells NPM that any folder inside the `packages` directory is a separate
+package that should be managed as part of the workspace.
+
+### Benefits of workspaces
+
+- **Simplified dependency management**: Running `npm install` from the root of
+  the project will install all dependencies for all packages in the workspace
+  and link them together. This means you don't need to run `npm install` in each
+  package's directory.
+- **Automatic linking**: Packages within the workspace can depend on each other.
+  When you run `npm install`, NPM will automatically create symlinks between the
+  packages. This means that when you make changes to one package, the changes
+  are immediately available to other packages that depend on it.
+- **Simplified script execution**: You can run scripts in any package from the
+  root of the project using the `--workspace` flag. For example, to run the
+  `build` script in the `cli` package, you can run
+  `npm run build --workspace @google/gemini-cli`.

package/dist/docs/quota-and-pricing.md

@@ -0,0 +1,158 @@
+# Gemini CLI: Quotas and pricing
+
+Gemini CLI offers a generous free tier that covers many individual developers'
+use cases. For enterprise or professional usage, or if you need higher limits,
+several options are available depending on your authentication account type.
+
+See [privacy and terms](./tos-privacy.md) for details on the Privacy Policy and
+Terms of Service.
+
+> **Note:** Published prices are list price; additional negotiated commercial
+> discounting may apply.
+
+This article outlines the specific quotas and pricing applicable to Gemini CLI
+when using different authentication methods.
+
+Generally, there are three categories to choose from:
+
+- Free Usage: Ideal for experimentation and light use.
+- Paid Tier (fixed price): For individual developers or enterprises who need
+  more generous daily quotas and predictable costs.
+- Pay-As-You-Go: The most flexible option for professional use, long-running
+  tasks, or when you need full control over your usage.
+
+## Free usage
+
+Your journey begins with a generous free tier, perfect for experimentation and
+light use.
+
+Your free usage limits depend on your authorization type.
+
+### Log in with Google (Gemini Code Assist for individuals)
+
+For users who authenticate by using their Google account to access Gemini Code
+Assist for individuals. This includes:
+
+- 1000 model requests / user / day
+- 60 model requests / user / minute
+- Model requests will be made across the Gemini model family as determined by
+  Gemini CLI.
+
+Learn more at
+[Gemini Code Assist for Individuals Limits](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli).
+
+### Log in with Gemini API Key (unpaid)
+
+If you are using a Gemini API key, you can also benefit from a free tier. This
+includes:
+
+- 250 model requests / user / day
+- 10 model requests / user / minute
+- Model requests to Flash model only.
+
+Learn more at
+[Gemini API Rate Limits](https://ai.google.dev/gemini-api/docs/rate-limits).
+
+### Log in with Vertex AI (Express Mode)
+
+Vertex AI offers an Express Mode without the need to enable billing. This
+includes:
+
+- 90 days before you need to enable billing.
+- Quotas and models are variable and specific to your account.
+
+Learn more at
+[Vertex AI Express Mode Limits](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview#quotas).
+
+## Paid tier: Higher limits for a fixed cost
+
+If you use up your initial number of requests, you can continue to benefit from
+Gemini CLI by upgrading to one of the following subscriptions:
+
+- [Google AI Pro and AI Ultra](https://gemini.google/subscriptions/). This is
+  recommended for individual developers. Quotas and pricing are based on a fixed
+  price subscription.
+
+  For predictable costs, you can log in with Google.
+
+  Learn more at
+  [Gemini Code Assist Quotas and Limits](https://developers.google.com/gemini-code-assist/resources/quotas)
+
+- [Purchase a Gemini Code Assist Subscription through Google Cloud ](https://cloud.google.com/gemini/docs/codeassist/overview)
+  by signing up in the Google Cloud console. Learn more at
+  [Set up Gemini Code Assist](https://cloud.google.com/gemini/docs/discover/set-up-gemini).
+
+  Quotas and pricing are based on a fixed price subscription with assigned
+  license seats. For predictable costs, you can sign in with Google.
+
+  This includes:
+  - Gemini Code Assist Standard edition:
+    - 1500 model requests / user / day
+    - 120 model requests / user / minute
+  - Gemini Code Assist Enterprise edition:
+    - 2000 model requests / user / day
+    - 120 model requests / user / minute
+  - Model requests will be made across the Gemini model family as determined by
+    Gemini CLI.
+
+  [Learn more about Gemini Code Assist Standard and Enterprise license limits](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli).
+
+## Pay as you go
+
+If you hit your daily request limits or exhaust your Gemini Pro quota even after
+upgrading, the most flexible solution is to switch to a pay-as-you-go model,
+where you pay for the specific amount of processing you use. This is the
+recommended path for uninterrupted access.
+
+To do this, log in using a Gemini API key or Vertex AI.
+
+- Vertex AI (Regular Mode):
+  - Quota: Governed by a dynamic shared quota system or pre-purchased
+    provisioned throughput.
+  - Cost: Based on model and token usage.
+
+Learn more at
+[Vertex AI Dynamic Shared Quota](https://cloud.google.com/vertex-ai/generative-ai/docs/resources/dynamic-shared-quota)
+and [Vertex AI Pricing](https://cloud.google.com/vertex-ai/pricing).
+
+- Gemini API key:
+  - Quota: Varies by pricing tier.
+  - Cost: Varies by pricing tier and model/token usage.
+
+Learn more at
+[Gemini API Rate Limits](https://ai.google.dev/gemini-api/docs/rate-limits),
+[Gemini API Pricing](https://ai.google.dev/gemini-api/docs/pricing)
+
+It’s important to highlight that when using an API key, you pay per token/call.
+This can be more expensive for many small calls with few tokens, but it's the
+only way to ensure your workflow isn't interrupted by quota limits.
+
+## Gemini for workspace plans
+
+These plans currently apply only to the use of Gemini web-based products
+provided by Google-based experiences (for example, the Gemini web app or the
+Flow video editor). These plans do not apply to the API usage which powers the
+Gemini CLI. Supporting these plans is under active consideration for future
+support.
+
+## Tips to avoid high costs
+
+When using a Pay as you Go API key, be mindful of your usage to avoid unexpected
+costs.
+
+- Don't blindly accept every suggestion, especially for computationally
+  intensive tasks like refactoring large codebases.
+- Be intentional with your prompts and commands. You are paying per call, so
+  think about the most efficient way to get the job done.
+
+## Gemini API vs. Vertex
+
+- Gemini API (gemini developer api): This is the fastest way to use the Gemini
+  models directly.
+- Vertex AI: This is the enterprise-grade platform for building, deploying, and
+  managing Gemini models with specific security and control requirements.
+
+## Understanding your usage
+
+A summary of model usage is available through the `/stats` command and presented
+on exit at the end of a session.