@office-ai/aioncli-core 0.30.0 → 0.30.1

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

@@ -0,0 +1,199 @@
+# 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 increased quota,
+several options are available depending on your authentication account type.
+
+For a high-level comparison of available subscriptions and to select the right
+quota for your needs, see the [Plans page](https://geminicli.com/plans/).
+
+## Overview
+
+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
+
+Access to Gemini CLI begins with a generous free tier, perfect for
+experimentation and light use.
+
+Your free usage is governed by the following limits, which 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:
+
+### Individuals
+
+These tiers apply when you sign in with a personal account. To verify whether
+you're on a personal account, visit
+[Google One](https://one.google.com/about/plans?hl=en-US&g1_landing_page=0):
+
+- If you are on a personal account, you will see your personal dashboard.
+- If you are not on a personal account, you will see: "You're currently signed
+  in to your Google Workspace Account."
+
+**Supported tiers:** _- Tiers not listed above, including Google AI Plus, are
+not supported._
+
+- [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)
+
+### Through your organization
+
+These tiers are applicable when you are signing in with a Google Workspace
+account.
+
+- To verify your account type, visit
+  [the Google One page](https://one.google.com/about/plans?hl=en-US&g1_landing_page=0).
+- You are on a workspace account if you see the message "You're currently signed
+  in to your Google Workspace Account".
+
+**Supported tiers:** _- Tiers not listed above, including Workspace AI
+Standard/Plus and AI Expanded, are not supported._
+
+- [Workspace AI Ultra Access](https://workspace.google.com/products/ai-ultra/).
+- [Purchase a Gemini Code Assist Subscription through Google Cloud](https://cloud.google.com/gemini/docs/codeassist/overview).
+
+  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 the following request limits:
+  - 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 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)
+
+An enterprise-grade platform for building, deploying, and managing AI models,
+including Gemini. It offers enhanced security, data governance, and integration
+with other Google Cloud services.
+
+- 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
+
+Ideal for developers who want to quickly build applications with the Gemini
+models. This is the most direct way to use the models.
+
+- 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 reaching a limit on your
+quota.
+
+## 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.
+
+## Check usage and limits
+
+You can check your current token usage and applicable limits using the
+`/stats model` command. This command provides a snapshot of your current
+session's token usage, as well as information about the limits associated with
+your current quota.
+
+For more information on the `/stats` command and its subcommands, see the
+[Command Reference](../reference/commands.md#stats).
+
+A summary of model usage is also presented on exit at the end of a session.
+
+## Tips to avoid high costs
+
+When using a pay-as-you-go plan, be mindful of your usage to avoid unexpected
+costs.
+
+- **Be selective with suggestions**: Before accepting a suggestion, especially
+  for a computationally intensive task like refactoring a large codebase,
+  consider if it's the most cost-effective approach.
+- **Use precise prompts**: You are paying per call, so think about the most
+  efficient way to get your desired result. A well-crafted prompt can often get
+  you the answer you need in a single call, rather than multiple back-and-forth
+  interactions.
+- **Monitor your usage**: Use the `/stats model` command to track your token
+  usage during a session. This can help you stay aware of your spending in real
+  time.

package/dist/docs/resources/tos-privacy.md

@@ -0,0 +1,102 @@
+# Gemini CLI: License, Terms of Service, and Privacy Notices
+
+Gemini CLI is an open-source tool that lets you interact with Google's powerful
+AI services directly from your command-line interface. The Gemini CLI software
+is licensed under the
+[Apache 2.0 license](https://github.com/google-gemini/gemini-cli/blob/main/LICENSE).
+When you use Gemini CLI to access or use Google’s services, the Terms of Service
+and Privacy Notices applicable to those services apply to such access and use.
+
+Directly accessing the services powering Gemini CLI (e.g., the Gemini Code
+Assist service) using third-party software, tools, or services (for example,
+using OpenClaw with Gemini CLI OAuth) is a violation of applicable terms and
+policies. Such actions may be grounds for suspension or termination of your
+account.
+
+Your Gemini CLI Usage Statistics are handled in accordance with Google's Privacy
+Policy.
+
+**Note:** See [quotas and pricing](quota-and-pricing.md) for the quota and
+pricing details that apply to your usage of the Gemini CLI.
+
+## Supported authentication methods
+
+Your authentication method refers to the method you use to log into and access
+Google’s services with Gemini CLI. Supported authentication methods include:
+
+- Logging in with your Google account to Gemini Code Assist.
+- Using an API key with Gemini Developer API.
+- Using an API key with Vertex AI GenAI API.
+
+The Terms of Service and Privacy Notices applicable to the aforementioned Google
+services are set forth in the table below.
+
+If you log in with your Google account and you do not already have a Gemini Code
+Assist account associated with your Google account, you will be directed to the
+sign up flow for Gemini Code Assist for individuals. If your Google account is
+managed by your organization, your administrator may not permit access to Gemini
+Code Assist for individuals. Please see the
+[Gemini Code Assist for individuals FAQs](https://developers.google.com/gemini-code-assist/resources/faqs)
+for further information.
+
+| Authentication Method    | Service(s)                   | Terms of Service                                                                                        | Privacy Notice                                                                                |
+| :----------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |
+| Google Account           | Gemini Code Assist services  | [Terms of Service](https://developers.google.com/gemini-code-assist/resources/privacy-notices)          | [Privacy Notices](https://developers.google.com/gemini-code-assist/resources/privacy-notices) |
+| Gemini Developer API Key | Gemini API - Unpaid Services | [Gemini API Terms of Service - Unpaid Services](https://ai.google.dev/gemini-api/terms#unpaid-services) | [Google Privacy Policy](https://policies.google.com/privacy)                                  |
+| Gemini Developer API Key | Gemini API - Paid Services   | [Gemini API Terms of Service - Paid Services](https://ai.google.dev/gemini-api/terms#paid-services)     | [Google Privacy Policy](https://policies.google.com/privacy)                                  |
+| Vertex AI GenAI API Key  | Vertex AI GenAI API          | [Google Cloud Platform Terms of Service](https://cloud.google.com/terms/service-terms/)                 | [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice)            |
+
+## 1. If you have signed in with your Google account to Gemini Code Assist
+
+For users who use their Google account to access
+[Gemini Code Assist](https://codeassist.google), these Terms of Service and
+Privacy Notice documents apply:
+
+- Gemini Code Assist for individuals:
+  [Google Terms of Service](https://policies.google.com/terms) and
+  [Gemini Code Assist for individuals Privacy Notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals).
+- Gemini Code Assist with Google AI Pro or Ultra subscription:
+  [Google Terms of Service](https://policies.google.com/terms),
+  [Google One Additional Terms of Service](https://one.google.com/terms-of-service)
+  and [Google Privacy Policy\*](https://policies.google.com/privacy).
+- Gemini Code Assist Standard and Enterprise editions:
+  [Google Cloud Platform Terms of Service](https://cloud.google.com/terms) and
+  [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice).
+
+_\* If your account is also associated with an active subscription to Gemini
+Code Assist Standard or Enterprise edition, the terms and privacy policy of
+Gemini Code Assist Standard or Enterprise edition will apply to all your use of
+Gemini Code Assist._
+
+## 2. If you have signed in with a Gemini API key to the Gemini Developer API
+
+If you are using a Gemini API key for authentication with the
+[Gemini Developer API](https://ai.google.dev/gemini-api/docs), these Terms of
+Service and Privacy Notice documents apply:
+
+- Terms of Service: Your use of the Gemini CLI is governed by the
+  [Gemini API Terms of Service](https://ai.google.dev/gemini-api/terms). These
+  terms may differ depending on whether you are using an unpaid or paid service:
+  - For unpaid services, refer to the
+    [Gemini API Terms of Service - Unpaid Services](https://ai.google.dev/gemini-api/terms#unpaid-services).
+  - For paid services, refer to the
+    [Gemini API Terms of Service - Paid Services](https://ai.google.dev/gemini-api/terms#paid-services).
+- Privacy Notice: The collection and use of your data is described in the
+  [Google Privacy Policy](https://policies.google.com/privacy).
+
+## 3. If you have signed in with a Gemini API key to the Vertex AI GenAI API
+
+If you are using a Gemini API key for authentication with a
+[Vertex AI GenAI API](https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest)
+backend, these Terms of Service and Privacy Notice documents apply:
+
+- Terms of Service: Your use of the Gemini CLI is governed by the
+  [Google Cloud Platform Service Terms](https://cloud.google.com/terms/service-terms/).
+- Privacy Notice: The collection and use of your data is described in the
+  [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice).
+
+## Usage statistics opt-out
+
+You may opt-out from sending Gemini CLI Usage Statistics to Google by following
+the instructions available here:
+[Usage Statistics Configuration](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md#usage-statistics).

package/dist/docs/resources/troubleshooting.md

@@ -0,0 +1,176 @@
+# Troubleshooting guide
+
+This guide provides solutions to common issues and debugging tips, including
+topics on:
+
+- Authentication or login errors
+- Frequently asked questions (FAQs)
+- Debugging tips
+- Existing GitHub Issues similar to yours or creating new Issues
+
+## Authentication or login errors
+
+- **Error:
+  `You must be a named user on your organization's Gemini Code Assist Standard edition subscription to use this service. Please contact your administrator to request an entitlement to Gemini Code Assist Standard edition.`**
+  - **Cause:** This error might occur if Gemini CLI detects the
+    `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` environment variable is
+    defined. Setting these variables forces an organization subscription check.
+    This might be an issue if you are using an individual Google account not
+    linked to an organizational subscription.
+
+  - **Solution:**
+    - **Individual Users:** Unset the `GOOGLE_CLOUD_PROJECT` and
+      `GOOGLE_CLOUD_PROJECT_ID` environment variables. Check and remove these
+      variables from your shell configuration files (for example, `.bashrc`,
+      `.zshrc`) and any `.env` files. If this doesn't resolve the issue, try
+      using a different Google account.
+
+    - **Organizational Users:** Contact your Google Cloud administrator to be
+      added to your organization's Gemini Code Assist subscription.
+
+- **Error:
+  `Failed to sign in. Message: Your current account is not eligible... because it is not currently available in your location.`**
+  - **Cause:** Gemini CLI does not currently support your location. For a full
+    list of supported locations, see the following pages:
+    - Gemini Code Assist for individuals:
+      [Available locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
+
+- **Error: `Failed to sign in. Message: Request contains an invalid argument`**
+  - **Cause:** Users with Google Workspace accounts or Google Cloud accounts
+    associated with their Gmail accounts may not be able to activate the free
+    tier of the Google Code Assist plan.
+  - **Solution:** For Google Cloud accounts, you can work around this by setting
+    `GOOGLE_CLOUD_PROJECT` to your project ID. Alternatively, you can obtain the
+    Gemini API key from
+    [Google AI Studio](http://aistudio.google.com/app/apikey), which also
+    includes a separate free tier.
+
+- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` or
+  `unable to get local issuer certificate`**
+  - **Cause:** You may be on a corporate network with a firewall that intercepts
+    and inspects SSL/TLS traffic. This often requires a custom root CA
+    certificate to be trusted by Node.js.
+  - **Solution:** First try setting `NODE_USE_SYSTEM_CA`; if that does not
+    resolve the issue, set `NODE_EXTRA_CA_CERTS`.
+    - Set the `NODE_USE_SYSTEM_CA=1` environment variable to tell Node.js to use
+      the operating system's native certificate store (where corporate
+      certificates are typically already installed).
+      - Example: `export NODE_USE_SYSTEM_CA=1` (Windows PowerShell:
+        `$env:NODE_USE_SYSTEM_CA=1`)
+    - Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of
+      your corporate root CA certificate file.
+      - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt`
+        (Windows PowerShell:
+        `$env:NODE_EXTRA_CA_CERTS="C:\path\to\your\corporate-ca.crt"`)
+
+## Common error messages and solutions
+
+- **Error: `EADDRINUSE` (Address already in use) when starting an MCP server.**
+  - **Cause:** Another process is already using the port that the MCP server is
+    trying to bind to.
+  - **Solution:** Either stop the other process that is using the port or
+    configure the MCP server to use a different port.
+
+- **Error: Command not found (when attempting to run Gemini CLI with
+  `gemini`).**
+  - **Cause:** Gemini CLI is not correctly installed or it is not in your
+    system's `PATH`.
+  - **Solution:** The update depends on how you installed Gemini CLI:
+    - If you installed `gemini` globally, check that your `npm` global binary
+      directory is in your `PATH`. You can update Gemini CLI using the command
+      `npm install -g @google/gemini-cli@latest`.
+    - If you are running `gemini` from source, ensure you are using the correct
+      command to invoke it (e.g., `node packages/cli/dist/index.js ...`). To
+      update Gemini CLI, pull the latest changes from the repository, and then
+      rebuild using the command `npm run build`.
+
+- **Error: `MODULE_NOT_FOUND` or import errors.**
+  - **Cause:** Dependencies are not installed correctly, or the project hasn't
+    been built.
+  - **Solution:**
+    1.  Run `npm install` to ensure all dependencies are present.
+    2.  Run `npm run build` to compile the project.
+    3.  Verify that the build completed successfully with `npm run start`.
+
+- **Error: "Operation not permitted", "Permission denied", or similar.**
+  - **Cause:** When sandboxing is enabled, Gemini CLI may attempt operations
+    that are restricted by your sandbox configuration, such as writing outside
+    the project directory or system temp directory.
+  - **Solution:** Refer to the [Configuration: Sandboxing](../cli/sandbox.md)
+    documentation for more information, including how to customize your sandbox
+    configuration.
+
+- **Gemini CLI is not running in interactive mode in "CI" environments**
+  - **Issue:** The Gemini CLI does not enter interactive mode (no prompt
+    appears) if an environment variable starting with `CI_` (e.g., `CI_TOKEN`)
+    is set. This is because the `is-in-ci` package, used by the underlying UI
+    framework, detects these variables and assumes a non-interactive CI
+    environment.
+  - **Cause:** The `is-in-ci` package checks for the presence of `CI`,
+    `CONTINUOUS_INTEGRATION`, or any environment variable with a `CI_` prefix.
+    When any of these are found, it signals that the environment is
+    non-interactive, which prevents the Gemini CLI from starting in its
+    interactive mode.
+  - **Solution:** If the `CI_` prefixed variable is not needed for the CLI to
+    function, you can temporarily unset it for the command. e.g.,
+    `env -u CI_TOKEN gemini`
+
+- **DEBUG mode not working from project .env file**
+  - **Issue:** Setting `DEBUG=true` in a project's `.env` file doesn't enable
+    debug mode for gemini-cli.
+  - **Cause:** The `DEBUG` and `DEBUG_MODE` variables are automatically excluded
+    from project `.env` files to prevent interference with gemini-cli behavior.
+  - **Solution:** Use a `.gemini/.env` file instead, or configure the
+    `advanced.excludedEnvVars` setting in your `settings.json` to exclude fewer
+    variables.
+
+## Exit codes
+
+The Gemini CLI uses specific exit codes to indicate the reason for termination.
+This is especially useful for scripting and automation.
+
+| Exit Code | Error Type                 | Description                                                                                         |
+| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
+| 41        | `FatalAuthenticationError` | An error occurred during the authentication process.                                                |
+| 42        | `FatalInputError`          | Invalid or missing input was provided to the CLI. (non-interactive mode only)                       |
+| 44        | `FatalSandboxError`        | An error occurred with the sandboxing environment (e.g., Docker, Podman, or Seatbelt).              |
+| 52        | `FatalConfigError`         | A configuration file (`settings.json`) is invalid or contains errors.                               |
+| 53        | `FatalTurnLimitedError`    | The maximum number of conversational turns for the session was reached. (non-interactive mode only) |
+
+## Debugging tips
+
+- **CLI debugging:**
+  - Use the `--debug` flag for more detailed output. In interactive mode, press
+    F12 to view the debug console.
+  - Check the CLI logs, often found in a user-specific configuration or cache
+    directory.
+
+- **Core debugging:**
+  - Check the server console output for error messages or stack traces.
+  - Increase log verbosity if configurable. For example, set the `DEBUG_MODE`
+    environment variable to `true` or `1`.
+  - Use Node.js debugging tools (e.g., `node --inspect`) if you need to step
+    through server-side code.
+
+- **Tool issues:**
+  - If a specific tool is failing, try to isolate the issue by running the
+    simplest possible version of the command or operation the tool performs.
+  - For `run_shell_command`, check that the command works directly in your shell
+    first.
+  - For _file system tools_, verify that paths are correct and check the
+    permissions.
+
+- **Pre-flight checks:**
+  - Always run `npm run preflight` before committing code. This can catch many
+    common issues related to formatting, linting, and type errors.
+
+## Existing GitHub issues similar to yours or creating new issues
+
+If you encounter an issue that was not covered here in this _Troubleshooting
+guide_, consider searching the Gemini CLI
+[Issue tracker on GitHub](https://github.com/google-gemini/gemini-cli/issues).
+If you can't find an issue similar to yours, consider creating a new GitHub
+Issue with a detailed description. Pull requests are also welcome!
+
+> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
+> maintainers. We will not accept pull requests related to these issues.

package/dist/docs/resources/uninstall.md

@@ -0,0 +1,56 @@
+# Uninstalling the CLI
+
+Your uninstall method depends on how you ran the CLI. Follow the instructions
+for either npx or a global npm installation.
+
+## Method 1: Using npx
+
+npx runs packages from a temporary cache without a permanent installation. To
+"uninstall" the CLI, you must clear this cache, which will remove gemini-cli and
+any other packages previously executed with npx.
+
+The npx cache is a directory named `_npx` inside your main npm cache folder. You
+can find your npm cache path by running `npm config get cache`.
+
+**For macOS / Linux**
+
+```bash
+# The path is typically ~/.npm/_npx
+rm -rf "$(npm config get cache)/_npx"
+```
+
+**For Windows (PowerShell)**
+
+```powershell
+# The path is typically $env:LocalAppData\npm-cache\_npx
+Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force
+```
+
+## Method 2: Using npm (global install)
+
+If you installed the CLI globally (e.g., `npm install -g @google/gemini-cli`),
+use the `npm uninstall` command with the `-g` flag to remove it.
+
+```bash
+npm uninstall -g @google/gemini-cli
+```
+
+This command completely removes the package from your system.
+
+## Method 3: Homebrew
+
+If you installed the CLI globally using Homebrew (e.g.,
+`brew install gemini-cli`), use the `brew uninstall` command to remove it.
+
+```bash
+brew uninstall gemini-cli
+```
+
+## Method 4: MacPorts
+
+If you installed the CLI globally using MacPorts (e.g.,
+`sudo port install gemini-cli`), use the `port uninstall` command to remove it.
+
+```bash
+sudo port uninstall gemini-cli
+```

package/dist/src/agents/a2a-errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview Custom error types for A2A remote agent operations.
+ * Provides structured, user-friendly error messages for common failure modes
+ * during agent card fetching, authentication, and communication.
+ */
+/**
+ * Base class for all A2A agent errors.
+ * Provides a `userMessage` field with a human-readable description.
+ */
+export declare class A2AAgentError extends Error {
+    /** A user-friendly message suitable for display in the CLI. */
+    readonly userMessage: string;
+    /** The agent name associated with this error. */
+    readonly agentName: string;
+    constructor(agentName: string, message: string, userMessage: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when the agent card URL returns a 404 Not Found response.
+ */
+export declare class AgentCardNotFoundError extends A2AAgentError {
+    constructor(agentName: string, agentCardUrl: string);
+}
+/**
+ * Thrown when the agent card URL returns a 401/403 response,
+ * indicating an authentication or authorization failure.
+ */
+export declare class AgentCardAuthError extends A2AAgentError {
+    readonly statusCode: number;
+    constructor(agentName: string, agentCardUrl: string, statusCode: 401 | 403);
+}
+/**
+ * Thrown when the agent card's security schemes require authentication
+ * but the agent definition does not include the necessary auth configuration.
+ */
+export declare class AgentAuthConfigMissingError extends A2AAgentError {
+    /** Human-readable description of required authentication schemes. */
+    readonly requiredAuth: string;
+    /** Specific fields or config entries that are missing. */
+    readonly missingFields: string[];
+    constructor(agentName: string, requiredAuth: string, missingFields: string[]);
+}
+/**
+ * Thrown when a generic/unexpected network or server error occurs
+ * while fetching the agent card or communicating with the remote agent.
+ */
+export declare class AgentConnectionError extends A2AAgentError {
+    constructor(agentName: string, agentCardUrl: string, cause: unknown);
+}
+/**
+ * Attempts to classify a raw error from the A2A SDK into a typed A2AAgentError.
+ *
+ * Inspects the error message and full cause chain for HTTP status codes and
+ * well-known patterns to produce a structured, user-friendly error.
+ *
+ * @param agentName The name of the agent being loaded.
+ * @param agentCardUrl The URL of the agent card.
+ * @param error The raw error caught during agent loading.
+ * @returns A classified A2AAgentError subclass.
+ */
+export declare function classifyAgentError(agentName: string, agentCardUrl: string, error: unknown): A2AAgentError;