ACP HTTP Client

Common errors

• TypeError: AcpHttpClient is not a constructor

  cause Attempting to import `AcpHttpClient` using CommonJS `require` syntax or an incorrect named import.
  fix Ensure you are using `import { AcpHttpClient } from 'acp-http-client';` for modern JavaScript/TypeScript environments. If forced to use CommonJS, ensure your build tool correctly transpiles ESM imports or look for a specific CJS build if available (though unlikely for this library).

• Error: RPC Method '...' not found

  cause The agent being communicated with does not expose the requested RPC method, likely due to a version mismatch between the client and the agent, or a misconfigured agent.
  fix Verify that the `sandbox-agent` running matches the expected version by the `acp-http-client` library. Check the agent's logs for available RPC methods or ensure your agent's configuration properly registers the required capabilities.

• ECONNREFUSED connect ECONNREFUSED ::1:8080

  cause The `acp-http-client` could not establish a connection to the configured agent endpoint, often because the agent is not running or is listening on a different address/port.
  fix Ensure the `sandbox-agent` is running and accessible at the `baseUrl` provided during `AcpHttpClient` initialization (e.g., `http://localhost:8080`). Check firewall rules and the agent's actual listening address and port.

Warnings

• breaking The install script URL for the underlying sandbox agent changed between v0.3.x and v0.4.x. While this client library primarily interfaces with a running agent, changes in the agent's installation and version compatibility might require updates to your agent deployment strategy.
  Fix: Refer to the `sandbox-agent` repository's documentation or changelog for the correct agent installation script URL and ensure your deployed agent version is compatible with the client library's expected protocol.
• gotcha The library is under active development, with frequent release candidates (e.g., 0.5.0-rc.X) introducing new features like 'Agent Computer providers' and 'desktop computer-use APIs.' These features may involve new RPC methods or changes to existing ones, potentially requiring updates to your client-side API interfaces.
  Fix: Always pin to exact minor or patch versions (e.g., `0.4.2` or `^0.4.0`) to avoid unexpected behavior. Review the changelog for `0.5.0` (and subsequent major versions) thoroughly before upgrading to production environments.
• breaking Error handling for RPC calls has been improved to surface agent `stderr` in RPC errors, and a `defaultCwd` parameter was added. This change might affect how you parse or react to RPC errors from the agent and how you configure command execution.
  Fix: Update error handling logic to account for potentially richer `AcpRpcError` messages and consider the implications of `defaultCwd` if you rely on specific working directories for agent commands. Test existing RPC error handling after upgrade.

Install

• npm install acp-http-client npm
• yarn add acp-http-client yarn
• pnpm add acp-http-client pnpm

Imports

• AcpHttpClient
  wrong:

  const AcpHttpClient = require('acp-http-client').AcpHttpClient;

  correct:

  import { AcpHttpClient } from 'acp-http-client';

  The primary class for instantiating the ACP client. The library is primarily ESM, but CommonJS `require` might work with transpilation or specific Node.js settings.
• AcpRpcError

  import { AcpRpcError } from 'acp-http-client';

  For handling RPC-specific errors returned by the agent. Check `error.code` and `error.message`.
• AcpClientConfig

  import type { AcpClientConfig } from 'acp-http-client';

  TypeScript type definition for the client configuration object, useful for ensuring correct setup parameters.

Quickstart

This quickstart demonstrates how to initialize the AcpHttpClient, define an agent's API interface, and make a basic JSON-RPC call to interact with a sandboxed agent's desktop and file system APIs.

import { AcpHttpClient } from 'acp-http-client';

interface AgentApi {
  desktop: {
    getScreenResolution(): Promise<{ width: number; height: number }>;
    click(x: number, y: number): Promise<void>;
  };
  fileSystem: {
    readFile(path: string): Promise<string>;
  };
}

async function runAgentTask() {
  const agentEndpoint = process.env.ACP_AGENT_ENDPOINT ?? 'http://localhost:8080';
  const client = new AcpHttpClient<AgentApi>({
    baseUrl: agentEndpoint,
    // Optional: Add authentication headers if your agent requires it
    headers: {
      'Authorization': `Bearer ${process.env.ACP_AGENT_TOKEN ?? ''}`
    }
  });

  try {
    console.log('Connecting to ACP agent at:', agentEndpoint);
    const resolution = await client.call('desktop.getScreenResolution');
    console.log('Agent screen resolution:', resolution);

    // Example: Click at the center of the screen
    await client.call('desktop.click', resolution.width / 2, resolution.height / 2);
    console.log('Successfully simulated a click.');

    const fileContent = await client.call('fileSystem.readFile', '/etc/hostname');
    console.log('Hostname file content:', fileContent.trim());

  } catch (error) {
    if (error instanceof AcpRpcError) {
      console.error(`RPC Error (${error.code}): ${error.message}`);
    } else {
      console.error('An unexpected error occurred:', error);
    }
    process.exit(1);
  }
}

runAgentTask();