@anthropic-field/core 0.1.0

package/dist/docs/troubleshooting.md

@@ -0,0 +1,173 @@
+# 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 login. 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 login. 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`
+    - 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`
+
+## 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/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from './src/index.js';
+export { Storage } from './src/config/storage.js';
+export { DEFAULT_GEMINI_MODEL, DEFAULT_GEMINI_MODEL_AUTO, DEFAULT_GEMINI_FLASH_MODEL, DEFAULT_GEMINI_FLASH_LITE_MODEL, DEFAULT_GEMINI_EMBEDDING_MODEL, } from './src/config/models.js';
+export { serializeTerminalToObject, type AnsiOutput, type AnsiLine, type AnsiToken, } from './src/utils/terminalSerializer.js';
+export { DEFAULT_TRUNCATE_TOOL_OUTPUT_LINES, DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD, } from './src/config/config.js';
+export { detectIdeFromEnv } from './src/ide/detect-ide.js';
+export { logExtensionEnable, logIdeConnection, logExtensionDisable, } from './src/telemetry/loggers.js';
+export { IdeConnectionEvent, IdeConnectionType, ExtensionInstallEvent, ExtensionDisableEvent, ExtensionEnableEvent, ExtensionUninstallEvent, ExtensionUpdateEvent, ModelSlashCommandEvent, } from './src/telemetry/types.js';
+export { makeFakeConfig } from './src/test-utils/config.js';
+export * from './src/utils/pathReader.js';
+export { ClearcutLogger } from './src/telemetry/clearcut-logger/clearcut-logger.js';
+export { logModelSlashCommand } from './src/telemetry/loggers.js';
+export { KeychainTokenStorage } from './src/mcp/token-storage/keychain-token-storage.js';
+export * from './src/utils/googleQuotaErrors.js';
+export type { GoogleApiError } from './src/utils/googleErrors.js';
+export { getCodeAssistServer } from './src/code_assist/codeAssist.js';
+export { getExperiments } from './src/code_assist/experiments/experiments.js';
+export { ExperimentFlags } from './src/code_assist/experiments/flagNames.js';
+export { getErrorStatus, ModelNotFoundError } from './src/utils/httpErrors.js';

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from './src/index.js';
+export { Storage } from './src/config/storage.js';
+export { DEFAULT_GEMINI_MODEL, DEFAULT_GEMINI_MODEL_AUTO, DEFAULT_GEMINI_FLASH_MODEL, DEFAULT_GEMINI_FLASH_LITE_MODEL, DEFAULT_GEMINI_EMBEDDING_MODEL, } from './src/config/models.js';
+export { serializeTerminalToObject, } from './src/utils/terminalSerializer.js';
+export { DEFAULT_TRUNCATE_TOOL_OUTPUT_LINES, DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD, } from './src/config/config.js';
+export { detectIdeFromEnv } from './src/ide/detect-ide.js';
+export { logExtensionEnable, logIdeConnection, logExtensionDisable, } from './src/telemetry/loggers.js';
+export { IdeConnectionEvent, IdeConnectionType, ExtensionInstallEvent, ExtensionDisableEvent, ExtensionEnableEvent, ExtensionUninstallEvent, ExtensionUpdateEvent, ModelSlashCommandEvent, } from './src/telemetry/types.js';
+export { makeFakeConfig } from './src/test-utils/config.js';
+export * from './src/utils/pathReader.js';
+export { ClearcutLogger } from './src/telemetry/clearcut-logger/clearcut-logger.js';
+export { logModelSlashCommand } from './src/telemetry/loggers.js';
+export { KeychainTokenStorage } from './src/mcp/token-storage/keychain-token-storage.js';
+export * from './src/utils/googleQuotaErrors.js';
+export { getCodeAssistServer } from './src/code_assist/codeAssist.js';
+export { getExperiments } from './src/code_assist/experiments/experiments.js';
+export { ExperimentFlags } from './src/code_assist/experiments/flagNames.js';
+export { getErrorStatus, ModelNotFoundError } from './src/utils/httpErrors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,yBAAyB,GAI1B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,kCAAkC,EAClC,sCAAsC,GACvC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mDAAmD,CAAC;AACzF,cAAc,kCAAkC,CAAC;AAEjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,8CAA8C,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/src/__mocks__/fs/promises.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as actualFsPromises from 'node:fs/promises';
+export declare const mockControl: {
+    mockReadFile: import("vitest").Mock<(...args: any[]) => any>;
+};
+export declare const access: typeof actualFsPromises.access, appendFile: typeof actualFsPromises.appendFile, chmod: typeof actualFsPromises.chmod, chown: typeof actualFsPromises.chown, copyFile: typeof actualFsPromises.copyFile, cp: typeof actualFsPromises.cp, lchmod: typeof actualFsPromises.lchmod, lchown: typeof actualFsPromises.lchown, link: typeof actualFsPromises.link, lstat: typeof actualFsPromises.lstat, mkdir: typeof actualFsPromises.mkdir, open: typeof actualFsPromises.open, opendir: typeof actualFsPromises.opendir, readdir: typeof actualFsPromises.readdir, readlink: typeof actualFsPromises.readlink, realpath: typeof actualFsPromises.realpath, rename: typeof actualFsPromises.rename, rmdir: typeof actualFsPromises.rmdir, rm: typeof actualFsPromises.rm, stat: typeof actualFsPromises.stat, symlink: typeof actualFsPromises.symlink, truncate: typeof actualFsPromises.truncate, unlink: typeof actualFsPromises.unlink, utimes: typeof actualFsPromises.utimes, watch: typeof actualFsPromises.watch, writeFile: typeof actualFsPromises.writeFile;
+export declare const readFile: import("vitest").Mock<(...args: any[]) => any>;

package/dist/src/__mocks__/fs/promises.js

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { vi } from 'vitest';
+import * as actualFsPromises from 'node:fs/promises';
+const readFileMock = vi.fn();
+// Export a control object so tests can access and manipulate the mock
+export const mockControl = {
+    mockReadFile: readFileMock,
+};
+// Export all other functions from the actual fs/promises module
+export const { access, appendFile, chmod, chown, copyFile, cp, lchmod, lchown, link, lstat, mkdir, open, opendir, readdir, readlink, realpath, rename, rmdir, rm, stat, symlink, truncate, unlink, utimes, watch, writeFile, } = actualFsPromises;
+// Override readFile with our mock
+export const readFile = readFileMock;
+//# sourceMappingURL=promises.js.map

package/dist/src/__mocks__/fs/promises.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promises.js","sourceRoot":"","sources":["../../../../src/__mocks__/fs/promises.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC5B,OAAO,KAAK,gBAAgB,MAAM,kBAAkB,CAAC;AAErD,MAAM,YAAY,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;AAE7B,sEAAsE;AACtE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,YAAY,EAAE,YAAY;CAC3B,CAAC;AAEF,gEAAgE;AAChE,MAAM,CAAC,MAAM,EACX,MAAM,EACN,UAAU,EACV,KAAK,EACL,KAAK,EACL,QAAQ,EACR,EAAE,EACF,MAAM,EACN,MAAM,EACN,IAAI,EACJ,KAAK,EACL,KAAK,EACL,IAAI,EACJ,OAAO,EACP,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,KAAK,EACL,EAAE,EACF,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,MAAM,EACN,MAAM,EACN,KAAK,EACL,SAAS,GACV,GAAG,gBAAgB,CAAC;AAErB,kCAAkC;AAClC,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC"}

package/dist/src/agents/a2a-client-manager.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AgentCard, Message, Task } from '@a2a-js/sdk';
+import { type Client, type AuthenticationHandler } from '@a2a-js/sdk/client';
+export type SendMessageResult = Message | Task;
+/**
+ * Manages A2A clients and caches loaded agent information.
+ * Follows a singleton pattern to ensure a single client instance.
+ */
+export declare class A2AClientManager {
+    private static instance;
+    private clients;
+    private agentCards;
+    private constructor();
+    /**
+     * Gets the singleton instance of the A2AClientManager.
+     */
+    static getInstance(): A2AClientManager;
+    /**
+     * Resets the singleton instance. Only for testing purposes.
+     * @internal
+     */
+    static resetInstanceForTesting(): void;
+    /**
+     * Loads an agent by fetching its AgentCard and caches the client.
+     * @param name The name to assign to the agent.
+     * @param agentCardUrl The full URL to the agent's card.
+     * @param authHandler Optional authentication handler to use for this agent.
+     * @returns The loaded AgentCard.
+     */
+    loadAgent(name: string, agentCardUrl: string, authHandler?: AuthenticationHandler): Promise<AgentCard>;
+    /**
+     * Invalidates all cached clients and agent cards.
+     */
+    clearCache(): void;
+    /**
+     * Sends a message to a loaded agent.
+     * @param agentName The name of the agent to send the message to.
+     * @param message The message content.
+     * @param options Optional context and task IDs to maintain conversation state.
+     * @returns The response from the agent (Message or Task).
+     * @throws Error if the agent returns an error response.
+     */
+    sendMessage(agentName: string, message: string, options?: {
+        contextId?: string;
+        taskId?: string;
+    }): Promise<SendMessageResult>;
+    /**
+     * Retrieves a loaded agent card.
+     * @param name The name of the agent.
+     * @returns The agent card, or undefined if not found.
+     */
+    getAgentCard(name: string): AgentCard | undefined;
+    /**
+     * Retrieves a loaded client.
+     * @param name The name of the agent.
+     * @returns The client, or undefined if not found.
+     */
+    getClient(name: string): Client | undefined;
+    /**
+     * Retrieves a task from an agent.
+     * @param agentName The name of the agent.
+     * @param taskId The ID of the task to retrieve.
+     * @returns The task details.
+     */
+    getTask(agentName: string, taskId: string): Promise<Task>;
+    /**
+     * Cancels a task on an agent.
+     * @param agentName The name of the agent.
+     * @param taskId The ID of the task to cancel.
+     * @returns The cancellation response.
+     */
+    cancelTask(agentName: string, taskId: string): Promise<Task>;
+}

package/dist/src/agents/a2a-client-manager.js

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ClientFactory, ClientFactoryOptions, DefaultAgentCardResolver, RestTransportFactory, JsonRpcTransportFactory, createAuthenticatingFetchWithRetry, } from '@a2a-js/sdk/client';
+import { v4 as uuidv4 } from 'uuid';
+import { debugLogger } from '../utils/debugLogger.js';
+/**
+ * Manages A2A clients and caches loaded agent information.
+ * Follows a singleton pattern to ensure a single client instance.
+ */
+export class A2AClientManager {
+    static instance;
+    // Each agent should manage their own context/taskIds/card/etc
+    clients = new Map();
+    agentCards = new Map();
+    constructor() { }
+    /**
+     * Gets the singleton instance of the A2AClientManager.
+     */
+    static getInstance() {
+        if (!A2AClientManager.instance) {
+            A2AClientManager.instance = new A2AClientManager();
+        }
+        return A2AClientManager.instance;
+    }
+    /**
+     * Resets the singleton instance. Only for testing purposes.
+     * @internal
+     */
+    static resetInstanceForTesting() {
+        // @ts-expect-error - Resetting singleton for testing
+        A2AClientManager.instance = undefined;
+    }
+    /**
+     * Loads an agent by fetching its AgentCard and caches the client.
+     * @param name The name to assign to the agent.
+     * @param agentCardUrl The full URL to the agent's card.
+     * @param authHandler Optional authentication handler to use for this agent.
+     * @returns The loaded AgentCard.
+     */
+    async loadAgent(name, agentCardUrl, authHandler) {
+        if (this.clients.has(name) && this.agentCards.has(name)) {
+            throw new Error(`Agent with name '${name}' is already loaded.`);
+        }
+        let fetchImpl = fetch;
+        if (authHandler) {
+            fetchImpl = createAuthenticatingFetchWithRetry(fetch, authHandler);
+        }
+        const resolver = new DefaultAgentCardResolver({ fetchImpl });
+        const options = ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+            transports: [
+                new RestTransportFactory({ fetchImpl }),
+                new JsonRpcTransportFactory({ fetchImpl }),
+            ],
+            cardResolver: resolver,
+        });
+        const factory = new ClientFactory(options);
+        const client = await factory.createFromUrl(agentCardUrl, '');
+        const agentCard = await client.getAgentCard();
+        this.clients.set(name, client);
+        this.agentCards.set(name, agentCard);
+        debugLogger.debug(`[A2AClientManager] Loaded agent '${name}' from ${agentCardUrl}`);
+        return agentCard;
+    }
+    /**
+     * Invalidates all cached clients and agent cards.
+     */
+    clearCache() {
+        this.clients.clear();
+        this.agentCards.clear();
+        debugLogger.debug('[A2AClientManager] Cache cleared.');
+    }
+    /**
+     * Sends a message to a loaded agent.
+     * @param agentName The name of the agent to send the message to.
+     * @param message The message content.
+     * @param options Optional context and task IDs to maintain conversation state.
+     * @returns The response from the agent (Message or Task).
+     * @throws Error if the agent returns an error response.
+     */
+    async sendMessage(agentName, message, options) {
+        const client = this.clients.get(agentName);
+        if (!client) {
+            throw new Error(`Agent '${agentName}' not found.`);
+        }
+        const messageParams = {
+            message: {
+                kind: 'message',
+                role: 'user',
+                messageId: uuidv4(),
+                parts: [{ kind: 'text', text: message }],
+                contextId: options?.contextId,
+                taskId: options?.taskId,
+            },
+            configuration: {
+                blocking: true,
+            },
+        };
+        try {
+            return await client.sendMessage(messageParams);
+        }
+        catch (error) {
+            const prefix = `A2AClient SendMessage Error [${agentName}]`;
+            if (error instanceof Error) {
+                throw new Error(`${prefix}: ${error.message}`, { cause: error });
+            }
+            throw new Error(`${prefix}: Unexpected error during sendMessage: ${String(error)}`);
+        }
+    }
+    /**
+     * Retrieves a loaded agent card.
+     * @param name The name of the agent.
+     * @returns The agent card, or undefined if not found.
+     */
+    getAgentCard(name) {
+        return this.agentCards.get(name);
+    }
+    /**
+     * Retrieves a loaded client.
+     * @param name The name of the agent.
+     * @returns The client, or undefined if not found.
+     */
+    getClient(name) {
+        return this.clients.get(name);
+    }
+    /**
+     * Retrieves a task from an agent.
+     * @param agentName The name of the agent.
+     * @param taskId The ID of the task to retrieve.
+     * @returns The task details.
+     */
+    async getTask(agentName, taskId) {
+        const client = this.clients.get(agentName);
+        if (!client) {
+            throw new Error(`Agent '${agentName}' not found.`);
+        }
+        try {
+            return await client.getTask({ id: taskId });
+        }
+        catch (error) {
+            const prefix = `A2AClient getTask Error [${agentName}]`;
+            if (error instanceof Error) {
+                throw new Error(`${prefix}: ${error.message}`, { cause: error });
+            }
+            throw new Error(`${prefix}: Unexpected error: ${String(error)}`);
+        }
+    }
+    /**
+     * Cancels a task on an agent.
+     * @param agentName The name of the agent.
+     * @param taskId The ID of the task to cancel.
+     * @returns The cancellation response.
+     */
+    async cancelTask(agentName, taskId) {
+        const client = this.clients.get(agentName);
+        if (!client) {
+            throw new Error(`Agent '${agentName}' not found.`);
+        }
+        try {
+            return await client.cancelTask({ id: taskId });
+        }
+        catch (error) {
+            const prefix = `A2AClient cancelTask Error [${agentName}]`;
+            if (error instanceof Error) {
+                throw new Error(`${prefix}: ${error.message}`, { cause: error });
+            }
+            throw new Error(`${prefix}: Unexpected error: ${String(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=a2a-client-manager.js.map

package/dist/src/agents/a2a-client-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-client-manager.js","sourceRoot":"","sources":["../../../src/agents/a2a-client-manager.ts"],"names":[],"mappings":"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"}

package/dist/src/agents/a2aUtils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Message, Task, Part } from '@a2a-js/sdk';
+/**
+ * Extracts a human-readable text representation from a Message object.
+ * Handles Text, Data (JSON), and File parts.
+ */
+export declare function extractMessageText(message: Message | undefined): string;
+/**
+ * Extracts text from a single Part.
+ */
+export declare function extractPartText(part: Part): string;
+/**
+ * Extracts a clean, human-readable text summary from a Task object.
+ * Includes the status message and any artifact content with context headers.
+ * Technical metadata like ID and State are omitted for better clarity and token efficiency.
+ */
+export declare function extractTaskText(task: Task): string;
+/**
+ * Extracts contextId and taskId from a Message or Task response.
+ * Follows the pattern from the A2A CLI sample to maintain conversational continuity.
+ */
+export declare function extractIdsFromResponse(result: Message | Task): {
+    contextId?: string;
+    taskId?: string;
+};

package/dist/src/agents/a2aUtils.js

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Extracts a human-readable text representation from a Message object.
+ * Handles Text, Data (JSON), and File parts.
+ */
+export function extractMessageText(message) {
+    if (!message) {
+        return '';
+    }
+    return extractPartsText(message.parts);
+}
+/**
+ * Extracts text from a single Part.
+ */
+export function extractPartText(part) {
+    if (isTextPart(part)) {
+        return part.text;
+    }
+    if (isDataPart(part)) {
+        // Attempt to format known data types if metadata exists, otherwise JSON stringify
+        return `Data: ${JSON.stringify(part.data)}`;
+    }
+    if (isFilePart(part)) {
+        const fileData = part.file;
+        if (fileData.name) {
+            return `File: ${fileData.name}`;
+        }
+        if ('uri' in fileData && fileData.uri) {
+            return `File: ${fileData.uri}`;
+        }
+        return `File: [binary/unnamed]`;
+    }
+    return '';
+}
+/**
+ * Extracts a clean, human-readable text summary from a Task object.
+ * Includes the status message and any artifact content with context headers.
+ * Technical metadata like ID and State are omitted for better clarity and token efficiency.
+ */
+export function extractTaskText(task) {
+    const parts = [];
+    // Status Message
+    const statusMessageText = extractMessageText(task.status?.message);
+    if (statusMessageText) {
+        parts.push(statusMessageText);
+    }
+    // Artifacts
+    if (task.artifacts) {
+        for (const artifact of task.artifacts) {
+            const artifactContent = extractPartsText(artifact.parts);
+            if (artifactContent) {
+                const header = artifact.name
+                    ? `Artifact (${artifact.name}):`
+                    : 'Artifact:';
+                parts.push(`${header}\n${artifactContent}`);
+            }
+        }
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Extracts text from an array of parts.
+ */
+function extractPartsText(parts) {
+    if (!parts || parts.length === 0) {
+        return '';
+    }
+    return parts
+        .map((p) => extractPartText(p))
+        .filter(Boolean)
+        .join('\n');
+}
+// Type Guards
+function isTextPart(part) {
+    return part.kind === 'text';
+}
+function isDataPart(part) {
+    return part.kind === 'data';
+}
+function isFilePart(part) {
+    return part.kind === 'file';
+}
+/**
+ * Extracts contextId and taskId from a Message or Task response.
+ * Follows the pattern from the A2A CLI sample to maintain conversational continuity.
+ */
+export function extractIdsFromResponse(result) {
+    let contextId;
+    let taskId;
+    if (result.kind === 'message') {
+        taskId = result.taskId;
+        contextId = result.contextId;
+    }
+    else if (result.kind === 'task') {
+        taskId = result.id;
+        contextId = result.contextId;
+        // If the task is in a final state (and not input-required), we clear the taskId
+        // so that the next interaction starts a fresh task (or keeps context without being bound to the old task).
+        if (result.status &&
+            result.status.state !== 'input-required' &&
+            (result.status.state === 'completed' ||
+                result.status.state === 'failed' ||
+                result.status.state === 'canceled')) {
+            taskId = undefined;
+        }
+    }
+    return { contextId, taskId };
+}
+//# sourceMappingURL=a2aUtils.js.map