Metadata-Version: 2.4
Name: soulacp
Version: 0.2.0
Summary: Python ACP client library with native CLI sessions and bounded connection pooling
Author-email: AIXP Labs <noreply@SoulACP.dev>
License-Expression: Apache-2.0
Project-URL: Homepage, https://soulacp.dev
Project-URL: Repository, https://github.com/AIXP-Labs/SoulACP
Project-URL: Issues, https://github.com/AIXP-Labs/SoulACP/issues
Project-URL: Documentation, https://soulacp.dev
Project-URL: Changelog, https://github.com/AIXP-Labs/SoulACP/blob/main/CHANGELOG.md
Keywords: acp,agent-client-protocol,claude-code,gemini,opencode,openclaw,cursor,codex,qwen-code,kimi,codebuddy,cline,copilot,minion,vibe,nova,crow,amp,auggie,autohand,corust,deepagents,droid,fast-agent,copilot-ls,goose,junie,kilo,pi-acp,qoder,stakpak,ai-agent,coding-agent,soulacp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=1.4; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.15.22; extra == "dev"
Requires-Dist: pyright>=1.1.390; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: bandit>=1.7.10; extra == "dev"
Requires-Dist: pre-commit>=4.6.0; extra == "dev"
Requires-Dist: tomli>=2.0; extra == "dev"
Requires-Dist: opentelemetry-api>=1.20; extra == "dev"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
Dynamic: license-file

# SoulACP

**Python client library for the Agent Client Protocol, with native CLI sessions and bounded connection pooling.**

[![CI](https://github.com/AIXP-Labs/SoulACP/actions/workflows/ci.yml/badge.svg)](https://github.com/AIXP-Labs/SoulACP/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/soulacp)](https://pypi.org/project/soulacp/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

English | [简体中文](README_CN.md)

## Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Supported Agents](#supported-agents)
- [Usage](#usage)
- [Session Management](#session-management)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Testing](#testing)
- [Project Documents](#project-documents)
- [AIXP Labs](#aixp-labs-aixpdev)
- [License](#license)
- [Alignment & Philosophy](#alignment-philosophy)

## Features

- **30 CLI integrations**: 29 ACP adapters plus one legacy Cursor CLI adapter; see [Supported Agents](#supported-agents)
- **Native CLI sessions**: The provider CLI remains the source of truth; soulacp stores only session mappings and transport state
- **No duplicated conversation history**: Prompts are not replayed through a second middleware-owned transcript
- **ManagedSession**: High-level API with safe session reuse, explicit reset, startup retry, and fallback
- **Bounded connection pooling**: Session-safe reuse, FIFO backpressure, lifecycle retirement
- **Session store**: TTL-backed user→session mapping with memory or file storage
- **Async streaming**: Real-time response chunks via asyncio
- **Safe retry**: Exponential backoff for retryable control-plane failures; prompts are never blindly replayed
- **Structured session context**: Validated additional roots and stdio/HTTP/SSE MCP server definitions
- **Host services**: Configured-root file access and bounded ACP terminal process management
- **Current ACP lifecycle**: Capability-gated authentication, logout, session close, request cancellation, and config APIs
- **Pure stdlib core**: No required runtime dependencies; the OpenTelemetry API is optional

## Installation

SoulACP requires Python 3.10 or later and at least one supported agent CLI or
ACP bridge installed and, when required, authenticated.

### Published release

```bash
python -m pip install soulacp
```

### Current source

The source checkout can contain unreleased APIs documented in this README.

```bash
git clone https://github.com/AIXP-Labs/SoulACP.git
cd SoulACP
python -m pip install -e .

# Development and test tools
python -m pip install -e ".[dev]"
```

### Optional telemetry

```bash
# Published package
python -m pip install "soulacp[otel]"

# Current source checkout
python -m pip install -e ".[otel]"
```

## Quick Start

### ManagedSession (recommended)

```python
import asyncio
from soulacp import ManagedSession

async def main():
    async with ManagedSession(provider="claude", model="claude-acp/sonnet") as session:
        # Simple query — session auto-managed
        response = await session.query("Hello!", user_id="user1")
        print(response)

        # Streaming
        async for chunk in session.stream("Write hello world", user_id="user1"):
            print(chunk, end="", flush=True)

asyncio.run(main())
```

ManagedSession automatically handles:

- **Session reuse**: Same user_id gets same CLI session across requests
- **Explicit reset**: `reset_session(user_id)` clears a reviewed stale/overflowed session without implicit prompt replay
- **Retry**: Exponential backoff on safe, pre-prompt transient failures
- **Fallback**: Optional provider switch only when the prompt outcome is known not to be in progress

### Low-level API

```python
import asyncio
from soulacp import ACPConfig, ACPConnectionPool, resolve_client_class

async def main():
    config = ACPConfig(provider="claude", model="claude-acp/sonnet")
    client_class = resolve_client_class("claude")

    async with ACPConnectionPool(config, client_class) as pool:
        async with pool.acquire() as (client, session_id):
            response = await client.query("Hello!")
            print(response)

asyncio.run(main())
```

## Supported Agents

| Agent | Provider | Model Example | Base Command |
|-------|----------|---------------|-------------|
| Claude Code | `claude` | `claude-acp/sonnet` | `claude-agent-acp` (`claude-code-acp` legacy) |
| Gemini | `gemini` | `gemini-acp/gemini-3-flash-preview` | `gemini --acp` |
| OpenCode | `opencode` | `opencode-acp/default` | `opencode acp` |
| OpenClaw | `openclaw` | `openclaw/default` | `openclaw acp --no-prefix-cwd` |
| Cursor (ACP) | `cursor` | `cursor-acp/default` | `cursor-agent acp` |
| Cursor (Legacy) | `cursor-cli` | `cursor-cli/gpt-4` | `cursor-agent -p` |
| Codex | `codex` | `codex-acp/gpt-5.5` | `codex-acp` |
| Qwen Code | `qwen` | `qwen-acp/qwen-coder` | `qwen-code --acp --experimental-skills` |
| Kimi CLI | `kimi` | `kimi-acp/default` | `kimi acp` |
| Codebuddy Code | `codebuddy` | `codebuddy-acp/default` | `codebuddy-code --acp` |
| Cline | `cline` | `cline-acp/default` | `cline --acp` |
| GitHub Copilot | `copilot` | `copilot-acp/default` | `copilot --acp` |
| Minion Code | `minion` | `minion-acp/default` | `minion-code acp` |
| Mistral Vibe | `vibe` | `vibe-acp/default` | `vibe-acp` |
| Nova | `nova` | `nova-acp/default` | `nova acp` |
| Crow CLI | `crow` | `crow-acp/default` | `crow-cli acp` |
| Amp | `amp` | `amp-acp/default` | `amp-acp` |
| Auggie | `auggie` | `auggie-acp/default` | `auggie --acp` |
| Autohand | `autohand` | `autohand-acp/default` | `autohand-acp` |
| Corust Agent | `corust` | `corust-acp/default` | `corust-agent-acp` |
| DeepAgents | `deepagents` | `deepagents-acp/default` | `deepagents-acp` |
| Factory Droid | `droid` | `droid-acp/default` | `droid exec --output-format acp-daemon` |
| fast-agent | `fastagent` | `fastagent-acp/default` | `fast-agent-acp -x` |
| Copilot LS | `copilot-ls` | `copilot-ls/default` | `copilot-language-server --acp` |
| Goose | `goose` | `goose-acp/default` | `goose acp` |
| Junie | `junie` | `junie-acp/default` | `junie --acp=true` |
| Kilo | `kilo` | `kilo-acp/default` | `kilo acp` |
| pi ACP | `pi` | `pi-acp/default` | `pi-acp` |
| Qoder | `qoder` | `qoder-acp/default` | `qodercli --acp` |
| Stakpak | `stakpak` | `stakpak-acp/default` | `stakpak acp` |

The base-command column is not an installation command. Adapters can append
model, policy, or authentication arguments at launch. Model availability
depends on the installed CLI, account, and authentication method.
The namespaced model ID `provider-acp/default` (and `provider/default`) leaves
model selection to the provider; SoulACP does not send `default` as a literal
model name or overwrite an existing provider model setting.

Registry helpers expose best-effort installation hints and inspect `PATH`
without starting provider processes:

```python
from soulacp import list_agents, list_installed_agents

for agent in list_agents():
    print(f"{agent.name:12} {agent.install_cmd}")

installed = [agent.name for agent in list_installed_agents()]
print("Installed:", installed)
```

Install the current Claude and Codex ACP bridges with:

```bash
npm install -g @agentclientprotocol/claude-agent-acp @agentclientprotocol/codex-acp
```

The renamed Claude bridge is preferred; `claude-code-acp` remains a legacy
compatibility fallback. The Codex bridge includes its runtime, but the
`codex login` commands below require the Codex CLI on `PATH`:

```bash
npm install -g @openai/codex
```

According to the [official transition notice](https://github.com/google-gemini/gemini-cli/discussions/27274),
Gemini CLI stopped serving Google AI Pro, Ultra, and free individual accounts
on 2026-06-18. The `gemini --acp` adapter now requires a supported
Enterprise/Google Cloud or paid API authentication path; installing the CLI
alone does not grant individual-tier access.

## Usage

### Claude Code

```python
import asyncio
from soulacp import ManagedSession

async def main():
    async with ManagedSession(provider="claude", model="claude-acp/sonnet") as session:
        response = await session.query("Hello!")
        print(response)

asyncio.run(main())
```

### Gemini

```python
import asyncio
from soulacp import ManagedSession

async def main():
    async with ManagedSession(provider="gemini", model="gemini-acp/gemini-3-flash-preview") as session:
        response = await session.query("Hello!")
        print(response)

asyncio.run(main())
```

### Codex (OpenAI)

Codex ACP supports an eligible ChatGPT subscription or API-key authentication.
For local ChatGPT authentication, run `codex login` once; the Codex bridge then
uses `~/.codex/auth.json` without requiring `OPENAI_API_KEY`.

```python
import asyncio
from soulacp import ManagedSession

async def main():
    # Example model; availability depends on the account and bridge version
    async with ManagedSession(provider="codex", model="codex-acp/gpt-5.5") as session:
        response = await session.query("Hello!")
        print(response)

asyncio.run(main())
```

**Environment variables** (all optional):

| Variable | Values | Default | Purpose |
|----------|--------|---------|---------|
| `CODEX_REASONING_EFFORT` | `minimal` / `low` / `medium` / `high` / `xhigh` | `medium` | Reasoning budget |
| `CODEX_SANDBOX_MODE` | `read-only` / `workspace-write` / `danger-full-access` | (codex default) | File-system permission |
| `CODEX_APPROVAL_POLICY` | `untrusted` / `on-request` / `never` | (Codex default) | Approval prompts |
| `CODEX_NETWORK_ACCESS` | `true` / `1` / `yes` | not injected | Opt in to network in `workspace-write`; other values leave Codex config unchanged |

The following disables approval prompts, allows workspace writes, and enables
network access. Use it only in a trusted workspace:

Bash:

```bash
export CODEX_SANDBOX_MODE=workspace-write
export CODEX_APPROVAL_POLICY=never
export CODEX_NETWORK_ACCESS=true
```

PowerShell:

```powershell
$env:CODEX_SANDBOX_MODE = "workspace-write"
$env:CODEX_APPROVAL_POLICY = "never"
$env:CODEX_NETWORK_ACCESS = "true"
```

For API-key authentication, let Codex persist the selected authentication mode
instead of relying on an environment key alone. Assuming `OPENAI_API_KEY` is
already set:

```bash
# Bash
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
```

```powershell
# PowerShell
$env:OPENAI_API_KEY | codex login --with-api-key
```

The same model ID format is used, but model availability depends on the account
and current Codex ACP bridge. Consult the
[official model catalog](https://developers.openai.com/api/docs/models) instead
of relying on legacy aliases.

### Multi-Agent

```python
import asyncio
from soulacp import ManagedSession

async def main():
    # Claude for code generation
    async with ManagedSession(provider="claude", model="claude-acp/sonnet") as claude:
        code = await claude.query("Write a sorting algorithm in Python")

    # Gemini for code review
    async with ManagedSession(provider="gemini", model="gemini-acp/gemini-3-flash-preview") as gemini:
        review = await gemini.query(f"Review this code:\n{code}")
        print(review)

asyncio.run(main())
```

## Session Management

### ManagedSession + ProviderSessionStore

ManagedSession uses ProviderSessionStore internally to map `(user_id, provider)` to CLI session IDs:

```python
import asyncio
from soulacp import ManagedSession

async def main():
    async with ManagedSession(provider="claude", model="claude-acp/sonnet") as session:
        # First request — creates a CLI session and stores the mapping
        await session.query("Remember 42.", user_id="alice")

        # Second request — reuses Alice's CLI session
        await session.query("What number?", user_id="alice")

        # A different user receives a different logical session
        await session.query("Hello!", user_id="bob")

asyncio.run(main())
```

### Custom Session Store

```python
import asyncio
from soulacp import ManagedSession, ProviderSessionStore, FileCache

async def main():
    store = ProviderSessionStore(cache=FileCache("~/.soulacp/sessions.json"))
    async with ManagedSession(
        provider="claude",
        model="claude-acp/sonnet",
        session_store=store,
    ) as session:
        await session.query("Remember 42.", user_id="alice")

asyncio.run(main())  # Closing the session flushes pending file-cache writes
```

### Session Lifecycle

| Event | Behavior |
|-------|----------|
| Successful first request | New CLI session created, mapping stored after pool release (TTL 7 days) |
| Subsequent requests | Same user_id → same CLI session (reuse) |
| Concurrent requests for one user/session | Serialized within one `ManagedSession` instance; different sessions can still run concurrently |
| Context overflow | Raise to caller; call `reset_session(user_id)` only after deciding whether to submit a new turn |
| Confirmed stale stored session | Clear that provider mapping once, then explicitly create a fresh session |
| Pre-prompt connection/timeout error | Preserve the mapping and retry the same session within the configured attempt budget |
| Prompt transport/RPC failure | Raise without retry or fallback because side effects may already exist |
| Fallback | Switch provider only before prompt execution (e.g. startup failure); reuse that provider's own stored session |

### Cache Backends

```python
from soulacp import MemoryCache, FileCache

# In-memory (default) — fast, lost on restart
memory = MemoryCache(max_size=10000)

# File-based — persists across restarts
file_cache = FileCache("~/.soulacp/sessions.json", debounce_seconds=1.0)
```

File-cache paths expand `~`; writes use an atomic temp-file replacement and
`ManagedSession.close()` flushes pending debounced mutations. User IDs are
stored as fixed-width pseudonymous SHA-256 key components, with read-time
migration only for unambiguous legacy plaintext keys. Numeric IDs, lowercase
10/32-character hexadecimal IDs, and delimiter-ambiguous legacy identities are
not auto-migrated because the historical formats cannot prove ownership;
affected mappings must be re-established. One `ProviderSessionStore` serializes
its compound lookup, migration, update, clear, and flush operations so a legacy
migration cannot overwrite a newer mapping. Coordinating multiple store or
cache instances remains the external backend's responsibility. `FileCache` normalizes values to
their standard JSON representation before publishing them and returns detached
read snapshots, so later caller mutation cannot change persisted state. Cache
keys must be valid UTF-8 strings; TTLs must be non-negative integers within the
finite runtime range. `FileCache` is a single-owner backend: do not
open the same path from multiple `FileCache` instances or processes.
Deployments with multiple owners should provide a coordinated external
`CacheBackend`. Stored session IDs are not encrypted, so protect the cache file
with appropriate OS permissions and do not share it.

### Low-level Session Control

```python
import asyncio
from soulacp import ACPConnectionPool, ACPConfig, resolve_client_class

async def main():
    config = ACPConfig(provider="claude", model="claude-acp/sonnet")
    client_class = resolve_client_class("claude")

    async with ACPConnectionPool(config, client_class) as pool:
        # Explicit session reuse
        async with pool.acquire() as (client, sid):
            await client.query("Remember 42.")

        async with pool.acquire(session_id=sid) as (client, sid2):
            assert sid2 == sid
            response = await client.query("What number?")
            print(response)

        # Force a new transport without bypassing the hard connection limit
        async with pool.acquire(session_id=sid, fresh=True) as (client, sid3):
            assert sid3 == sid

        stats = pool.get_stats()  # Non-blocking, no health-check I/O
        print(stats)

asyncio.run(main())
```

Native `ACPClientBase` adapters retain the agent's advertised capabilities,
implementation info, authentication methods, and current session config in
`agent_capabilities`, `agent_info`, `auth_methods`, and
`session_config_options`; `session_mode_state` tracks advertised modes and the
current selection. Stable `session_info_update`, `usage_update`, and
`available_commands_update` notifications are validated into `session_info`,
`session_usage`, and `available_commands`. These five session-owned states are
cleared together for a new/load/resume transition and restored together if the
transition fails. Every stable ACP v1 session-update shape, including content
blocks, tool calls, and plans, is structurally validated before state mutation
or callback delivery. `set_update_callback()` remains the raw, receive-ordered hook
for every update, including tool calls, plans, and thought chunks that are not
flattened into response text. Capability-gated `list_sessions()` and
`delete_session()` cover ACP session-history management; `set_config_option()`
updates flat or grouped select and boolean options, while `set_mode()` switches
an advertised legacy mode for backward compatibility. ACP is moving dedicated
mode methods into session config options, so category `mode` config options are
preferred when an agent advertises them. Configured models similarly use an
advertised category `model` select option; an already-selected value emits no
RPC, and the non-standard `session/set_model` method is only a compatibility
fallback when no model option is advertised. Agent-pushed `config_option_update`
and `current_mode_update` events keep both states current. `authenticate()`,
`logout()`, and `close_session()` expose the current ACP lifecycle methods and
reject calls not advertised by the agent. Successful logout or closure of the
active session invalidates pool reuse, so releasing that lease retires the
transport. Session load/resume performs no transport I/O and reports that the
stored session cannot be restored unless the agent advertises `loadSession` or
`sessionCapabilities.resume`; managed sessions then clear that unusable mapping
once and start fresh. The standalone
legacy `CursorCLIClient` exposes only the minimal `ACPClient` protocol.

Only a leading `<provider>-acp/` or `<provider>/` namespace is removed from a
configured model. Nested IDs such as `claude-acp/openai/gpt-5` therefore remain
`openai/gpt-5`. When an executable explicitly returns JSON-RPC `-32601` for the
legacy `session/set_model` fallback, soulacp warns once and caches that result
for the same adapter/executable; later clients use the provider default without
repeating the unsupported request.

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ACP_PROVIDER` | `claude` | Provider name |
| `ACP_MODEL` | `claude-acp/sonnet` | Model identifier |
| `ACP_CWD` | Current directory | Working directory for the agent subprocess |
| `ACP_POOL_SIZE` | 5 | Maximum retained idle connections |
| `ACP_POOL_MAX_CONNECTIONS` | 8 | Hard open + creating limit per `ACPConnectionPool` instance |
| `ACP_POOL_ACQUIRE_TIMEOUT` | 30 | FIFO capacity wait timeout (seconds) |
| `ACP_POOL_IDLE_TIMEOUT` | 600 | Seconds since release before idle retirement |
| `ACP_POOL_KEEPALIVE_INTERVAL` | 300 | Idle local transport-state check interval; `0` disables |
| `ACP_POOL_MAX_AGE` | 7200 | Soft connection age limit at lease boundaries |
| `ACP_POOL_MAX_USES` | 50 | Soft successful-lease limit |
| `ACP_POOL_CROSS_SESSION_REUSE` | false | Permit explicit resume on a transport bound to another session |
| `ACP_TIMEOUT_CONNECT` | 30 | Connection timeout (seconds) |
| `ACP_TIMEOUT_PROMPT` | 21600 | End-to-end prompt deadline (seconds, 6 hours) |
| `ACP_TIMEOUT_STREAM` | 1800 | No-ACP-activity stream timeout (seconds, 30 minutes) |
| `ACP_INHERIT_PARENT_ENV` | true | Inherit the full parent environment in provider and ACP terminal children |
| `ACP_AUTO_APPROVE` | true | Prefer `allow_once`; false prefers `reject_once` |
| `ACP_ENABLE_FALLBACK` | false | Enable pre-prompt provider fallback |
| `ACP_MAX_RETRIES` | 3 | Total pre-prompt attempt budget; `0` still performs one attempt |
| `ACP_RETRY_BASE_DELAY` | 1 | Retry backoff base (seconds) |
| `ACP_MAX_TURNS` | unset | Optional Claude-only maxTurns override |
| `ACP_OTEL_PROPAGATE` | 0 | Inject active W3C `traceparent`/`tracestate` at subprocess startup when set to `1`; baggage is excluded |
| `ACP_LOG_SENSITIVE_DATA` | 0 | Set exactly to `1` to opt into raw provider diagnostics in debug/error logs |

> **Security:** `ACP_AUTO_APPROVE=true` automatically chooses an allow option
> (`allow_once` preferred) when the agent requests permission. This is not an
> OS sandbox. Set it to `false` for untrusted workspaces and review the provider
> CLI's own permission model.

`pool_size` is not a concurrency limit. Total physical capacity is bounded by
`pool_max_connections` for each pool instance. Each `ManagedSession` creates
one pool per `provider:model` key, so N keys in one instance can reserve up to N
times the per-pool limit; multiple `ManagedSession` instances multiply this
again. There is no process-wide limiter. With
`pool_cross_session_reuse=False`, an anonymous request never receives an idle
client already bound to another logical session. This favors isolation and
makes the pool primarily a session-affinity cache. A requested session ID can
have only one live lease at a time. `ACPConnectionPool` validates and snapshots
its `ACPConfig` when constructed, and each physical client receives a separate
snapshot. Later caller or client mutation therefore cannot change the pool's
validated capacity and lifecycle policy; construct a new pool to apply policy
changes.

Boolean environment variables accept only `true/false`, `1/0`, `yes/no`, or
`on/off`; invalid values raise `ValueError` instead of silently disabling a
feature. OpenClaw does not receive `--session` by default, so each ACP bridge
uses its isolated session key. Setting `OPENCLAW_SESSION_KEY` deliberately opts
into OpenClaw's shared/attached session routing.

### Provider-specific environment variables

| Variable | Adapter | Purpose |
|----------|---------|---------|
| `MOONSHOT_API_KEY` | Kimi | API-key authentication |
| `MISTRAL_API_KEY` | Vibe | API-key authentication |
| `OPENCLAW_URL` | OpenClaw | Gateway URL |
| `OPENCLAW_TOKEN_FILE` | OpenClaw | Token authentication override via a protected file |
| `OPENCLAW_PASSWORD_FILE` | OpenClaw | Password authentication override via a protected file when no token file is configured |
| `OPENCLAW_SESSION_KEY` | OpenClaw | Explicitly attach/share a Gateway session; unset preserves isolated `acp-bridge:<uuid>` routing |
| `OPENCLAW_VERBOSE` | OpenClaw | Enable verbose bridge logging with `true`, `1`, or `yes` |

`OPENCLAW_URL` must be an absolute `ws://` or `wss://` URL without embedded
credentials. Plain `OPENCLAW_TOKEN` and `OPENCLAW_PASSWORD` launch overrides
are rejected: OpenClaw accepts them only as command-line values, where local
process tools can read them. Use configured Gateway authentication or a
protected credential file instead.

### Programmatic

```python
from soulacp import ACPConfig

config = ACPConfig(
    provider="claude",
    model="claude-acp/sonnet",
    pool_size=5,
    pool_max_connections=8,
    pool_acquire_timeout=30,
    pool_idle_timeout=600,
    pool_keepalive_interval=300,
    pool_max_age=7200,
    pool_max_uses=50,
    pool_cross_session_reuse=False,
    timeout_connect=30,
    timeout_prompt=21600,
    timeout_stream=1800,
    inherit_parent_env=True,
    auto_approve_permissions=True,
    enable_fallback=False,
    additional_directories=["/absolute/path/to/shared"],
    mcp_servers=[
        {
            "name": "local-tools",
            "command": "/absolute/path/to/mcp-server",
            "args": [],
            "env": [],
        }
    ],
)
```

`extra_args` is appended to the subprocess argv without shell expansion and is
visible to local process-inspection tools. Never put credentials in it.
`extra_env` is merged into the subprocess environment and overrides duplicate
keys. Treat both as trusted configuration; do not log them indiscriminately.
`ACPConfig` representations omit the working directory, additional roots, MCP
definitions, extra arguments, and environment overrides to reduce accidental
log exposure. The fields remain directly accessible and must still be handled
as sensitive configuration.
Provider and ACP terminal subprocesses inherit the parent environment by default
for CLI authentication and compatibility. Set `inherit_parent_env=False` (or
`ACP_INHERIT_PARENT_ENV=false`) to retain only a bounded runtime/path/locale
allowlist; then supply required credentials explicitly through `extra_env` or the
provider's own credential store. This limits environment propagation but is not
an OS sandbox. `additional_directories` and `mcp_servers`
are structured constructor-only fields; they intentionally have no environment
string parser. Roots and stdio commands must be absolute. HTTP/SSE MCP servers
require absolute HTTP(S) URLs without embedded credentials; use validated
header entries for authentication. MCP metadata must already use strict JSON
types with string object keys; tuples and non-string keys are rejected instead
of being silently coerced. Remote MCP servers and additional roots are
sent only when the agent advertises the corresponding
capability, otherwise session creation fails before an unsupported request is
sent.

### From Environment

```python
import asyncio
from soulacp import ACPConfig, ManagedSession

async def main():
    config = ACPConfig.from_env()
    async with ManagedSession(
        provider=config.provider,
        model=config.model,
        config=config,
    ) as session:
        print(await session.query("Hello!"))

asyncio.run(main())
```

`ManagedSession` requires `provider` and `model`. When `config` is omitted, it
loads the remaining settings with `ACPConfig.from_env()`, but the constructor's
provider and model override `ACP_PROVIDER` and `ACP_MODEL`. When a config is
provided, all other fields are preserved without hidden environment overrides;
the constructor still replaces `config.provider` and `config.model`. The
pattern above uses the environment-selected provider and model explicitly.

Prompt and stream deadline failures close the underlying transport and are not
automatically retried or sent to a fallback provider. This prevents requests
with an unknown outcome or partial output from being replayed.
For streaming APIs, time spent by the caller processing an already-yielded
chunk is not charged again by the generator-side prompt deadline. A native
ACP `session/prompt` RPC that is still in flight retains its original
end-to-end deadline.
When an individual outbound RPC is cancelled or times out, soulacp first sends
the standard best-effort `$/cancel_request` notification. Incoming
`$/cancel_request` notifications cancel matching host requests before their
reply starts and return JSON-RPC code `-32800`; prompt timeout cleanup still
retires the transport so a late response cannot leak into a later lease.

Native client connect/disconnect operations are serialized. Prompt/stream and
session load/resume operations are also serialized per client so a completed
old prompt cannot overwrite a newly selected session. Concurrent callers cannot
publish duplicate subprocesses, disconnect waits for an in-flight connect, and
owned cleanup completes before caller cancellation is propagated. Pool lease
release and retirement use the same ownership rule even when cancellation
arrives while cleanup is waiting for the pool lock, so capacity cannot remain
stranded in a leased state.
Bounded user-cancellable waits also preserve caller cancellation on Python 3.10
when the awaited operation completes in the same event-loop turn.
Legacy Cursor query cleanup likewise owns child-process reaping through repeated
caller cancellation. It also bounds output-pipe drain after direct process exit
and explicitly closes exited subprocess transports. A failed terminate/kill never releases physical pool
capacity: the client or terminal record remains owned, `close()` reports the
failure, and a later `close()` retries it. `ManagedSession` retains only the
pools and store flushes that failed, so successful cleanup is not repeated.
Native asyncio transports and OpenCode apply the same rule to a subprocess that
arrives after startup timeout: the late handle is claimed, reaped, or retained
for a later cleanup retry. RPC waits also observe direct subprocess exit while
preserving a bounded window for buffered tail frames, so an inherited stdout
pipe cannot hold a request until its full configured deadline. OpenCode
reader-thread callbacks are bound to the dispatch queue that scheduled them, so
a delayed callback from a disconnected transport cannot enter a replacement
transport generation.
Idle health checks inspect local process and pipe state without injecting probe
bytes into the newline-delimited JSON-RPC transport.

ACP v1 initialization must negotiate protocol version `1`, and every advertised
authentication method must have a non-empty agent-provided `id`; soulacp never
synthesizes one. Known advertised capability fields and every stable v1 RPC
response are validated before local session, mode, or configuration state is
committed. Response and known nested `_meta` values must be objects or null;
supported host requests apply the same metadata contract and return `-32602`
for malformed metadata. ACP v1 permission requests must include a valid
`toolCall` and options with non-empty IDs, names, and standard kinds before
soulacp selects one. Explicit pre-v1 ID-only options remain a compatibility
path when every option omits `kind`. ACP stdout and legacy Cursor JSON stdout are decoded as
strict UTF-8, and server request IDs accept the protocol's null, int64, and
string forms while responses remain correlated to soulacp's int64 integer IDs.
Externally decoded JSON also rejects duplicate object keys so fields cannot be
silently replaced during parsing. Inbound and outbound JSON reject invalid
Unicode and non-finite numbers instead of emitting implementation-specific JSON;
OpenCode's inherited `OPENCODE_CONFIG_CONTENT` must likewise be a strict JSON
object. Prompt completion is accepted only from the correlated
`session/prompt` response with a standard
`stopReason` (`end_turn`, `max_tokens`, `max_turn_requests`, `refusal`, or
`cancelled`). Message-end update extensions do not complete a turn. Incoming
session updates and all supported host requests must identify the current session;
stale cross-session messages fail closed. Transport loss after the prompt write
raises `ACPRequestOutcomeUnknownError`; malformed completion raises
`ACPProtocolError`. Any RPC interrupted after its write may have reached the
agent, so the transport is retired after best-effort `$/cancel_request` rather
than being returned to the pool with potentially divergent session state.

ACP filesystem requests honor the v1 absolute `path`; schema-boundary `line=0`
maps to the first 1-based line, and `limit=0` returns no lines. Requests are
contained to `cwd` plus validated `additional_directories` and bound file, text,
write, and directory sizes. Reads accept regular files only and enforce the byte
limit on the opened stream, including files that grow after path validation.
This is best-effort path containment under stable filesystem topology, not
race-resistant symlink protection or an OS sandbox.
Terminal working directories use the same configured roots; requests use
no-shell argv execution, bounded output (including
`outputByteLimit=null` or `0`), the standard `truncated` result flag, and a limit
of 32 unreleased or late-spawning terminal records and 32 concurrent
terminal-wait host requests per client service. A cancelled terminal create
retains its capacity reservation until the late child is reaped. SoulACP owns
the direct child process, and terminal wait follows that child's exit with only
a bounded output-drain window; use OS job/container
isolation when descendant-process cleanup must be guaranteed.

### Pool statistics and OpenTelemetry

`get_stats()` retains the original keys and adds closed/idle/active/checking/
closing state, creating reservations, unreaped transports, waiters, claimed
sessions, capacity, creation/disconnect failures, cleanup retries, session
hits, resume results, keepalive loop failures, evictions, lifecycle peaks, and a policy snapshot
including the effective startup-attempt budget.
Metrics use only low-cardinality attributes; session IDs, prompts, user IDs,
paths, and PIDs are never metric attributes. Built-in provider names are kept;
unknown/custom provider labels are collapsed to `custom` in metrics and spans,
and unrecognized pool-dimension values are collapsed to `other`.

soulacp uses only the OpenTelemetry API. Applications remain responsible for
configuring the SDK, readers, exporters, and backend. Without the optional API
package, all pool instrumentation is a no-op. Instruments are process-wide;
metrics and RPC spans omit session IDs, prompts, error text, user IDs, paths,
and PIDs. Telemetry backend failures are isolated and cannot replace operation
results or exceptions.

### Privacy boundaries

Default SoulACP logs and public exception strings redact provider messages,
RPC data, session IDs, stderr, user IDs, and cache paths. `RPCError` and
`ACPProviderError` retain raw fields for programmatic diagnosis; raw text is
rendered only through `format_diagnostic(include_sensitive=True)`. Setting
`ACP_LOG_SENSITIVE_DATA=1` additionally enables raw provider diagnostics in
library logs and should be limited to short-lived, access-controlled debugging.

`ProviderSessionStore` uses memory by default. An explicitly configured
`FileCache` stores provider session IDs unencrypted and uses deterministic
pseudonymous user-key hashes; protect the file with OS permissions and do not
share it across trust domains. Only unambiguous legacy plaintext cache keys are
migrated when accessed; ambiguous mappings fail closed and must be
re-established.

Legacy Cursor CLI prompts are sent through stdin, not argv. Cursor's documented
resume interface still requires the session ID in `--resume`, and explicit
`OPENCLAW_SESSION_KEY` values are likewise command-line metadata. Prefer the
native Cursor ACP adapter when process-list privacy is required. SoulACP agent
subprocesses run as the current OS account and inherit the parent environment
by default; minimal-environment mode does not change that OS trust boundary.
This library is not a credential sandbox.

## Architecture

```text
ManagedSession (high-level API)
  ├── ProviderSessionStore (user→session mapping)
  │   └── CacheBackend (MemoryCache / FileCache)
  ├── ACPConnectionPool (bounded reuse + FIFO backpressure + lifecycle)
  │   └── ACPClientBase (JSON-RPC over stdio subprocess)
  │       ├── 29 ACP adapter implementations (see Supported Agents)
  │       └── CursorCLIClient (legacy non-ACP integration)
  └── Services
      ├── FSService (file system operations)
      └── TerminalService (no-shell argv execution, live bounded output, kill/release)
```

## Testing

```bash
# Default suite (provider CLI and model calls are skipped)
python -m pytest tests/ -v

# Integration tests (requires installed and authenticated CLIs)
python -m pytest --run-integration tests/test_integration.py -v          # Claude Code
python -m pytest --run-integration tests/test_integration_gemini.py -v   # Gemini
python -m pytest --run-integration tests/test_integration_codex.py -v    # Codex

# All unit + integration + stdio stress tests
python -m pytest --run-integration tests/ -v

# Static checks used by CI
python -m ruff check src/soulacp/ tests/ examples/
python -m ruff format --check src/soulacp/ tests/ examples/
python -m pyright
# Bash; in PowerShell, set `$env:PYTHONPATH = "src"` first.
PYTHONPATH=src python -m pyright --verifytypes soulacp --ignoreexternal
python -m bandit -q -r src/soulacp

# Build both source and wheel distributions
python -m build
```

Files named `test_integration*`, `test_spike_*`, and `test_stress_*` require
`--run-integration`; the default suite intentionally skips them.

## Project Documents

| Document | Purpose |
|----------|---------|
| [CHANGELOG.md](CHANGELOG.md) | Release history and behavioral changes |
| [SECURITY.md](SECURITY.md) | Security policy and vulnerability reporting |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution workflow |
| [GOVERNANCE.md](GOVERNANCE.md) | Project governance and decision-making |
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards |

## AIXP Labs [aixp.dev](https://aixp.dev)

AIXP Labs develops and maintains the following core projects:

| Project | Description | Website |
|---------|-------------|---------|
| [HSAW](https://hsaw.dev) | Human Sovereignty and Wellbeing — Axiom 0 white paper (foundation) | hsaw.dev |
| [AIZP](https://aizp.dev) | AI Zenith-Zero Protocol — runtime behavioral alignment | aizp.dev |
| [AILP](https://ailp.dev) | AI List Protocol — agent discovery and capability advertising | ailp.dev |
| [AIVP](https://aivp.dev) | AI Value Protocol — international commerce, crypto asset settlement | aivp.dev |
| [AIRP](https://airp.dev) | AI RMB Protocol — Mainland China commerce, RMB licensed settlement | airp.dev |
| [AIBP](https://aibp.dev) | AI Bot Protocol — social communication and trust | aibp.dev |
| [AIAP](https://aiap.dev) | AI Application Protocol — governance and compliance | aiap.dev |
| [AISP](https://aisp.dev) | AI Skill Protocol — single-file skills with machine-enforced contract red lines | aisp.dev |
| [AISOP](https://aisop.dev) | AI Standard Operating Protocol — flow program definition | aisop.dev |
| [SoulSkill](https://soulskill.dev) | AISP skill reference library & multi-CLI plugin distribution | soulskill.dev |
| [SoulAgent](https://soulagent.dev) | Drop-in AI agent invoked directly by any CLI / SDK / IDE | soulagent.dev |
| [SoulBot](https://soulbot.dev) | AI agent runtime & orchestration framework (scheduling, agent-spawn, inter-agent comms) | soulbot.dev |
| [SoulACP](https://soulacp.dev) | Adapter library — bridging CLI tools and LLM providers **(this project)** | soulacp.dev |

---

## ⚠️ Disclaimer

This software is **experimental** and provided for **research and educational purposes only**. Not intended for production use. Use at your own risk. The authors assume no liability for any damages arising from the use of this software. See [LICENSE](LICENSE) for full terms (Apache 2.0).

---

## License

[Apache License 2.0](LICENSE) - Copyright 2026 AIXP Labs AIXP.dev | SoulACP.dev

---

Align Axiom 0: Human Sovereignty and Wellbeing. Version: SoulACP V0.2.0. www.soulacp.dev

<a id="alignment-philosophy"></a>

## ⚓ Alignment & Philosophy

### Axiom 0: [HSAW | Human Sovereignty and Wellbeing](https://hsaw.dev)

- **No HITL, HSAW.**
  *Human Sovereignty and Wellbeing is Axiom 0, requiring no hypocritical human-in-the-loop.*
- **No w.a.s.h, Real h.s.a.w.**
- **人非蝼蚁，人为道。**
- **We are not beggars, we the people.**
