openclaw-acp-bridge 0.3.2__tar.gz

openclaw_acp_bridge-0.3.2/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, sunshinejnjn@github
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FORDaily A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

openclaw_acp_bridge-0.3.2/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: openclaw-acp-bridge
+Version: 0.3.2
+Summary: A high-performance persistent TCP bridge and async client for OpenClaw ACP
+Author: sunshinejnjn@github
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/sunshinejnjn/openclaw-acp-bridge
+Project-URL: Bug Tracker, https://github.com/sunshinejnjn/openclaw-acp-bridge/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Dynamic: license-file
+
+# OpenClaw ACP Bridge
+
+A high-performance, persistent TCP bridge and client for the OpenClaw Agent Control Protocol (ACP).
+
+The **OpenClaw ACP Bridge** solves the challenge of maintaining persistent agent sessions over standard TCP while providing a high-speed "side-channel" for large-scale file transfers. It is designed for high-performance agentic workflows where large binary assets (images, videos, datasets) need to be moved efficiently between remote agents and local clients.
+
+## 🚀 Key Features
+
+- **Persistent Agent Session**: Unlike standard ACP tools that may restart agents per request, the bridge maintains a single persistent agent process across multiple client turns.
+- **High-Speed HTTP Side-Channel**: Automatically switches to HTTP streaming for large files (GB-sized), bypassing JSON-RPC/Base64 overhead and memory bloat.
+- **Explicit File Interception**: Use `/filerequest <path>` to instantly fetch any file from the remote agent's filesystem.
+- **Auto-File Retrieval**: Intelligently detects the `[FILEPATH: /path/to/file]` pattern in agent responses and automatically initiates a high-speed transfer.
+- **Async/Non-Blocking**: Built from the ground up for `asyncio`, utilizing `httpx` for reliable binary streaming.
+- **Environment Consistency**: Server-side agent launching utilizes interactive shells (`bash -i`) to ensure `.bashrc`, NVM, and local paths are correctly resolved.
+
+## 📦 Installation
+On the server (host where your openclaw gateway runs on) side, as the acp_server_bridge.
+And the client side if you want to run with our client interface. Or you can use acp directly to connect to the acp_server_bridge using TCP directly (pip install agent-client-protocol).
+```bash
+pip install openclaw-acp-bridge
+```
+
+## 🛠️ Usage
+
+### 1. Launch the Bridge Server
+On your remote server (where OpenClaw is installed), start the bridge using the provided helper script:
+
+```bash
+chmod +x run_acp_server.sh
+./run_acp_server.sh
+```
+
+Or run the module directly:
+
+```bash
+python -m openclaw_acp_bridge --host 0.0.0.0 --port 18781 --debug
+```
+
+*Note: The bridge will also open a side-channel HTTP server on `port + 1` (default 18782).*
+
+### 2. Connect the Async Client
+On your local machine, use the `OpenClaw` client to interact with the remote agent:
+
+```python
+import asyncio
+from openclaw_acp_bridge import OpenClaw
+
+async def main():
+    # Connect to the remote bridge
+    async with OpenClaw(host="10.71.253.132", download_dir="my_assets") as client:
+        # 1. Standard Chat
+        response = await client.chat("Hello, who are you?")
+        print(f"Agent: {response.text}")
+
+        # 2. Explicit File Request
+        # This uses the high-speed side-channel automatically
+        response = await client.chat("/filerequest /path/to/large_dataset.zip")
+        if response.files:
+            print(f"Received file: {response.files[0]}")
+
+        # 3. Auto-Retrieval Pattern
+        # Ask the agent to generate something and return the path
+        response = await client.chat("Generate a report and return path in [FILEPATH: /path] format.")
+        # The client automatically detects the pattern and fetches the file!
+        for file in response.files:
+            print(f"Auto-downloaded: {file}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 🔌 Using with Standard ACP Clients
+
+The bridge is fully compatible with any standard ACP-compliant client or SDK. To use it, simply point your client to the bridge's TCP address (default port `18781`).
+
+### Why use the Bridge with standard clients?
+1. **Persistence**: Even with a standard client, the bridge keeps your remote agent process alive across sessions.
+2. **Environment**: The bridge handles the complex `bash -i` shell environment setup for you.
+3. **Special Commands**: You can still use `/filerequest <path>` in your prompts. The bridge will intercept these and return a standard ACP `resource` block.
+
+*Note: When using a standard client, the high-speed HTTP side-channel will return a `resource` block with a `uri` starting with `http://`. Ensure your client can handle HTTP-based resources or use our provided `openclaw_acp_bridge` client for automatic handling.*
+
+## ⚙️ Advanced Configuration
+
+### Bridge Server Options
+You can customize the server behavior using CLI arguments:
+
+```bash
+python -m openclaw_acp_bridge --port 18781 --token "my-secret-key" --openclaw-path "/usr/local/bin/openclaw"
+```
+
+| Parameter | Description |
+| :--- | :--- |
+| `--host` | Host to bind the TCP server to (default: `0.0.0.0`) |
+| `--port` | Port to listen on (default: `18781`) |
+| `--token` | Optional authentication token. If set, clients must provide this token to connect. |
+| `--openclaw-path` | Path to the `openclaw` binary on the server (default: `openclaw`) |
+| `--no-http` | Disable the high-speed HTTP side-channel. When set, the bridge uses standard Base64 blobs for all file transfers. |
+| `--debug` | Enable verbose logging for debugging. |
+
+### Authentication
+The bridge supports simple token-based authentication. You can either pass the token via the `--token` CLI argument or place a `token.txt` file in the server's working directory. The `--token` argument takes precedence.
+
+### Download Directory
+The client allows you to specify where downloaded assets should be stored:
+```python
+client = OpenClaw(host="...", download_dir="./downloads")
+```
+
+## 🧪 Testing
+The package includes a comprehensive test suite `test_bridge.py` that demonstrates chat, small file blobs, and large-scale (100MB+) HTTP streaming.
+
+```bash
+python test_bridge.py --tests 1,2,3,4
+```
+
+## 📜 License
+BSD 3-Clause

openclaw_acp_bridge-0.3.2/README.md

@@ -0,0 +1,118 @@
+# OpenClaw ACP Bridge
+
+A high-performance, persistent TCP bridge and client for the OpenClaw Agent Control Protocol (ACP).
+
+The **OpenClaw ACP Bridge** solves the challenge of maintaining persistent agent sessions over standard TCP while providing a high-speed "side-channel" for large-scale file transfers. It is designed for high-performance agentic workflows where large binary assets (images, videos, datasets) need to be moved efficiently between remote agents and local clients.
+
+## 🚀 Key Features
+
+- **Persistent Agent Session**: Unlike standard ACP tools that may restart agents per request, the bridge maintains a single persistent agent process across multiple client turns.
+- **High-Speed HTTP Side-Channel**: Automatically switches to HTTP streaming for large files (GB-sized), bypassing JSON-RPC/Base64 overhead and memory bloat.
+- **Explicit File Interception**: Use `/filerequest <path>` to instantly fetch any file from the remote agent's filesystem.
+- **Auto-File Retrieval**: Intelligently detects the `[FILEPATH: /path/to/file]` pattern in agent responses and automatically initiates a high-speed transfer.
+- **Async/Non-Blocking**: Built from the ground up for `asyncio`, utilizing `httpx` for reliable binary streaming.
+- **Environment Consistency**: Server-side agent launching utilizes interactive shells (`bash -i`) to ensure `.bashrc`, NVM, and local paths are correctly resolved.
+
+## 📦 Installation
+On the server (host where your openclaw gateway runs on) side, as the acp_server_bridge.
+And the client side if you want to run with our client interface. Or you can use acp directly to connect to the acp_server_bridge using TCP directly (pip install agent-client-protocol).
+```bash
+pip install openclaw-acp-bridge
+```
+
+## 🛠️ Usage
+
+### 1. Launch the Bridge Server
+On your remote server (where OpenClaw is installed), start the bridge using the provided helper script:
+
+```bash
+chmod +x run_acp_server.sh
+./run_acp_server.sh
+```
+
+Or run the module directly:
+
+```bash
+python -m openclaw_acp_bridge --host 0.0.0.0 --port 18781 --debug
+```
+
+*Note: The bridge will also open a side-channel HTTP server on `port + 1` (default 18782).*
+
+### 2. Connect the Async Client
+On your local machine, use the `OpenClaw` client to interact with the remote agent:
+
+```python
+import asyncio
+from openclaw_acp_bridge import OpenClaw
+
+async def main():
+    # Connect to the remote bridge
+    async with OpenClaw(host="10.71.253.132", download_dir="my_assets") as client:
+        # 1. Standard Chat
+        response = await client.chat("Hello, who are you?")
+        print(f"Agent: {response.text}")
+
+        # 2. Explicit File Request
+        # This uses the high-speed side-channel automatically
+        response = await client.chat("/filerequest /path/to/large_dataset.zip")
+        if response.files:
+            print(f"Received file: {response.files[0]}")
+
+        # 3. Auto-Retrieval Pattern
+        # Ask the agent to generate something and return the path
+        response = await client.chat("Generate a report and return path in [FILEPATH: /path] format.")
+        # The client automatically detects the pattern and fetches the file!
+        for file in response.files:
+            print(f"Auto-downloaded: {file}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 🔌 Using with Standard ACP Clients
+
+The bridge is fully compatible with any standard ACP-compliant client or SDK. To use it, simply point your client to the bridge's TCP address (default port `18781`).
+
+### Why use the Bridge with standard clients?
+1. **Persistence**: Even with a standard client, the bridge keeps your remote agent process alive across sessions.
+2. **Environment**: The bridge handles the complex `bash -i` shell environment setup for you.
+3. **Special Commands**: You can still use `/filerequest <path>` in your prompts. The bridge will intercept these and return a standard ACP `resource` block.
+
+*Note: When using a standard client, the high-speed HTTP side-channel will return a `resource` block with a `uri` starting with `http://`. Ensure your client can handle HTTP-based resources or use our provided `openclaw_acp_bridge` client for automatic handling.*
+
+## ⚙️ Advanced Configuration
+
+### Bridge Server Options
+You can customize the server behavior using CLI arguments:
+
+```bash
+python -m openclaw_acp_bridge --port 18781 --token "my-secret-key" --openclaw-path "/usr/local/bin/openclaw"
+```
+
+| Parameter | Description |
+| :--- | :--- |
+| `--host` | Host to bind the TCP server to (default: `0.0.0.0`) |
+| `--port` | Port to listen on (default: `18781`) |
+| `--token` | Optional authentication token. If set, clients must provide this token to connect. |
+| `--openclaw-path` | Path to the `openclaw` binary on the server (default: `openclaw`) |
+| `--no-http` | Disable the high-speed HTTP side-channel. When set, the bridge uses standard Base64 blobs for all file transfers. |
+| `--debug` | Enable verbose logging for debugging. |
+
+### Authentication
+The bridge supports simple token-based authentication. You can either pass the token via the `--token` CLI argument or place a `token.txt` file in the server's working directory. The `--token` argument takes precedence.
+
+### Download Directory
+The client allows you to specify where downloaded assets should be stored:
+```python
+client = OpenClaw(host="...", download_dir="./downloads")
+```
+
+## 🧪 Testing
+The package includes a comprehensive test suite `test_bridge.py` that demonstrates chat, small file blobs, and large-scale (100MB+) HTTP streaming.
+
+```bash
+python test_bridge.py --tests 1,2,3,4
+```
+
+## 📜 License
+BSD 3-Clause

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge/__init__.py

@@ -0,0 +1,5 @@
+from .client import OpenClaw
+from .server import run_server
+
+__version__ = "0.3.2"
+__all__ = ["OpenClaw", "run_server"]

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge/__main__.py

@@ -0,0 +1,18 @@
+import argparse
+import asyncio
+from .server import run_server
+
+def main():
+    parser = argparse.ArgumentParser(description="OpenClaw ACP TCP Bridge")
+    parser.add_argument("--host", default="0.0.0.0", help="Host to bind to")
+    parser.add_argument("--port", type=int, default=18781, help="Port to listen on")
+    parser.add_argument("--debug", action="store_true", help="Enable verbose logging")
+    parser.add_argument("--token", help="Authentication token required for clients")
+    parser.add_argument("--openclaw-path", default="openclaw", help="Path to the openclaw binary")
+    parser.add_argument("--no-http", action="store_true", help="Disable the high-speed HTTP side-channel and use Base64 blobs instead")
+    args = parser.parse_args()
+
+    asyncio.run(run_server(args.host, args.port, args.debug, args.token, args.openclaw_path, use_http=(not args.no_http)))
+
+if __name__ == "__main__":
+    main()

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge/client.py

@@ -0,0 +1,249 @@
+import asyncio
+import os
+import base64
+import shutil
+import httpx
+from uuid import uuid4
+from typing import Optional, Callable, Any
+from acp import PROTOCOL_VERSION, text_block
+from acp.client import ClientSideConnection
+from acp.interfaces import Client
+
+class ChatResponse:
+    """A structured response from OpenClaw, containing text and any received files."""
+    def __init__(self, text: str, files: list[str]):
+        self.text = text
+        self.files = files
+
+    def __str__(self):
+        return self.text
+
+    def __repr__(self):
+        return self.text
+
+class _InternalACPClient(Client):
+    """Internal handler for ACP session updates."""
+    def __init__(self, on_update: Optional[Callable[[str, Any], Any]] = None, download_dir: str = "downloads"):
+        self.on_update = on_update
+        self.download_dir = download_dir
+        self.current_response_chunks = []
+        self.received_files = []
+        self.active_tasks = [] # Track background downloads
+        
+        # Ensure download directory exists
+        if not os.path.exists(self.download_dir):
+            os.makedirs(self.download_dir)
+
+    async def _download_stream(self, uri: str, save_path: str, filename: str):
+        try:
+            async with httpx.AsyncClient(timeout=300.0) as http_client:
+                async with http_client.stream("GET", uri) as r:
+                    with open(save_path, "wb") as f:
+                        chunk_count = 0
+                        async for chunk in r.aiter_bytes():
+                            f.write(chunk)
+                            chunk_count += len(chunk)
+                            if chunk_count > 0 and chunk_count % (10 * 1024 * 1024) == 0:
+                                print(f"--- [Download Progress: {chunk_count // (1024*1024)}MB] ---")
+            
+            self.received_files.append(save_path)
+            self.current_response_chunks.append(f"\n[File Received: {save_path}]\n")
+        except Exception as e:
+            self.current_response_chunks.append(f"\n[Stream Error: {e}]\n")
+
+
+    async def request_permission(self, options, session_id, tool_call, **kwargs):
+        return {"outcome": {"outcome": "approved"}}
+
+    async def session_update(self, session_id, update, **kwargs):
+        # Forward to custom callback if provided
+        if self.on_update:
+            if asyncio.iscoroutinefunction(self.on_update):
+                await self.on_update(session_id, update)
+            else:
+                self.on_update(session_id, update)
+        
+        # Helper to get attributes from either an object or a dict
+        def get_attr(obj, name, default=None):
+            if isinstance(obj, dict):
+                val = obj.get(name)
+                if val is not None: return val
+                # Try alternate case
+                alt_name = name.replace("_", "") if "_" in name else name
+                for k, v in obj.items():
+                    if k.lower() == name.lower() or k.lower() == alt_name.lower():
+                        return v
+                return default
+            return getattr(obj, name, default)
+
+        # Robust type detection
+        update_type = get_attr(update, 'session_update', get_attr(update, 'sessionUpdate'))
+        
+        if update_type == 'agent_message_chunk':
+            content = get_attr(update, 'content')
+            if content:
+                content_type = get_attr(content, 'type')
+                
+                if content_type == 'text':
+                    text = get_attr(content, 'text')
+                    if text: self.current_response_chunks.append(text)
+                elif content_type == 'resource':
+                    # Handle file/blob resources
+                    res_info = get_attr(content, 'resource')
+                    if res_info:
+                        uri = get_attr(res_info, 'uri', get_attr(res_info, 'URI', 'unknown_file'))
+                        blob = get_attr(res_info, 'blob')
+                        
+                        # Extract filename from URI
+                        filename = os.path.basename(uri.replace("file://", ""))
+                        save_path = os.path.join(self.download_dir, filename)
+
+                        # Priority 1: High-speed HTTP Side-Channel (for large files)
+                        if uri and str(uri).startswith("http"):
+                            task = asyncio.create_task(self._download_stream(uri, save_path, filename))
+                            self.active_tasks.append(task)
+                        # Priority 2: Standard Base64 Blob (for small files)
+                        elif blob and blob != "AAA=":
+                            with open(save_path, "wb") as f:
+                                f.write(base64.b64decode(blob))
+                            self.received_files.append(save_path)
+                            self.current_response_chunks.append(f"\n[File Saved: {save_path}]\n")
+                        else:
+                            self.current_response_chunks.append(f"\n[File Received: {uri}]\n")
+                elif content_type == 'image':
+                    # Handle direct image data
+                    data = get_attr(content, 'data')
+                    uri = get_attr(content, 'uri')
+                    
+                    if data:
+                        mime_type = get_attr(content, 'mimeType', 'image/png')
+                        ext = mime_type.split('/')[-1]
+                        uri = uri or f"image_{uuid4().hex[:8]}.{ext}"
+                        filename = os.path.basename(uri)
+                        save_path = os.path.join(self.download_dir, filename)
+                        
+                        with open(save_path, "wb") as f:
+                            f.write(base64.b64decode(data))
+                        
+                        self.received_files.append(save_path)
+                        self.current_response_chunks.append(f"\n[Image Saved: {save_path}]\n")
+                    elif uri and uri.startswith("http"):
+                        # Handle images served via HTTP as a background task
+                        task = asyncio.create_task(self._download_stream(uri, os.path.join(self.download_dir, os.path.basename(uri)), os.path.basename(uri)))
+                        self.active_tasks.append(task)
+
+class OpenClaw:
+    """
+    A high-level client for interacting with OpenClaw via the ACP TCP Bridge.
+    
+    Usage:
+        async with OpenClaw(host="10.71.253.132", token="...") as client:
+            response = await client.chat("Hello!")
+            print(response)
+    """
+    def __init__(self, host: str, port: int = 18781, token: Optional[str] = None, download_dir: str = "downloads"):
+        self.host = host
+        self.port = port
+        self.token = token
+        self.download_dir = download_dir
+        self._conn = None
+        self._writer = None
+        self._reader = None
+        self.session = None
+        self._internal_client = None
+
+    async def connect(self, on_update: Optional[Callable[[str, Any], Any]] = None):
+        """Connects to the remote OpenClaw server and initializes a session."""
+        # Increase limit to 10MB to handle large file transfers
+        self._reader, self._writer = await asyncio.open_connection(self.host, self.port, limit=10*1024*1024)
+        
+        # Handle token authentication
+        auth_token = self.token
+        if not auth_token:
+            try:
+                with open("token.txt", "r") as f:
+                    auth_token = f.read().strip()
+            except FileNotFoundError:
+                pass
+
+        if auth_token:
+            self._writer.write(auth_token.encode('utf-8') + b'\n')
+            await self._writer.drain()
+        
+        # Setup internal ACP infrastructure
+        self._internal_client = _InternalACPClient(on_update=on_update, download_dir=self.download_dir)
+        self._conn = ClientSideConnection(self._internal_client, self._writer, self._reader)
+        
+        # Initialize ACP protocol
+        await self._conn.initialize(protocol_version=PROTOCOL_VERSION)
+        self.session = await self._conn.new_session(cwd="/", mcp_servers=[])
+        
+        return self
+
+    async def chat(self, message: str) -> ChatResponse:
+        """
+        Sends a message to OpenClaw and returns a ChatResponse object.
+        The response object can be printed as a string, but also contains a .files list.
+        """
+        if not self._conn or not self.session:
+            raise RuntimeError("Client is not connected. Call connect() or use 'async with'.")
+            
+        self._internal_client.current_response_chunks = []
+        self._internal_client.received_files = []
+        
+        # Sends the prompt. The library blocks here until the 'turn' is finished.
+        await self._conn.prompt(
+            session_id=self.session.session_id,
+            prompt=[text_block(message)],
+            message_id=str(uuid4())
+        )
+        
+        # Wait for any background downloads to finish
+        if self._internal_client.active_tasks:
+            await asyncio.gather(*self._internal_client.active_tasks)
+            self._internal_client.active_tasks = []
+
+        full_text = "".join(self._internal_client.current_response_chunks)
+        full_files = list(self._internal_client.received_files)
+        
+        # New: Auto-request files marked with [FILEPATH: ...]
+        import re
+        explicit_paths = re.findall(r'\[FILEPATH:\s*<?([a-zA-Z0-9\._\-/]+)>?\]', full_text)
+        
+        for path in explicit_paths:
+            # We call the underlying logic to fetch the file without resetting the whole session state
+            self._internal_client.current_response_chunks = []
+            self._internal_client.received_files = []
+            
+            await self._conn.prompt(
+                session_id=self.session.session_id,
+                prompt=[text_block(f"/filerequest {path}")],
+                message_id=str(uuid4())
+            )
+            
+            # Wait for the streaming download
+            if self._internal_client.active_tasks:
+                await asyncio.gather(*self._internal_client.active_tasks)
+                self._internal_client.active_tasks = []
+                
+            full_files.extend(self._internal_client.received_files)
+            # Note: We don't necessarily need to append the "/filerequest" confirmation text to full_text
+            
+        return ChatResponse(text=full_text, files=full_files)
+
+    async def close(self):
+        """Gracefully closes the connection."""
+        if self._conn:
+            await self._conn.close()
+        if self._writer:
+            self._writer.close()
+            try:
+                await self._writer.wait_closed()
+            except:
+                pass
+
+    async def __aenter__(self):
+        return await self.connect()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge/server.py

@@ -0,0 +1,305 @@
+import asyncio
+import sys
+import json
+import os
+import base64
+import io
+import zipfile
+import mimetypes
+import argparse
+import threading
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+
+# Global state to manage the single persistent process
+process = None
+active_writer = None
+# Track files for the side-channel HTTP server
+served_files = {} # {uuid: full_path}
+
+class FileServerHandler(SimpleHTTPRequestHandler):
+    def do_GET(self):
+        # Path is /<file_id> or /<file_id>/<filename>
+        parts = self.path.strip("/").split("/")
+        file_id = parts[0]
+        if file_id in served_files:
+            full_path = served_files[file_id]
+            filename = os.path.basename(full_path)
+            with open(full_path, 'rb') as f:
+                self.send_response(200)
+                self.send_header("Content-Type", "application/octet-stream")
+                self.send_header("Content-Disposition", f'attachment; filename="{filename}"')
+                self.send_header("Content-Length", str(os.path.getsize(full_path)))
+                self.end_headers()
+                self.wfile.write(f.read())
+            # Optional: remove from served_files after one download
+            # del served_files[file_id]
+        else:
+            self.send_response(404)
+            self.end_headers()
+    def log_message(self, format, *args): pass # Silence logs
+
+def start_http_server(port):
+    httpd = HTTPServer(('0.0.0.0', port), FileServerHandler)
+    threading.Thread(target=httpd.serve_forever, daemon=True).start()
+    return port
+
+async def run_server(host="0.0.0.0", port=18781, is_debug=False, token=None, openclaw_path="openclaw", use_http=True):
+    global process, active_writer
+
+    # Start side-channel HTTP server on port + 1
+    http_port = port + 1
+    if use_http:
+        start_http_server(http_port)
+        print(f"Side-channel HTTP server listening on {host}:{http_port}")
+    else:
+        print("Side-channel HTTP server disabled. Using Base64 blobs for all transfers.")
+
+    # Launch OpenClaw ACP as a persistent subprocess
+    # Using bash -i -c to ensure the user's .bashrc (and NVM paths) are loaded
+    process = await asyncio.create_subprocess_exec(
+        "bash", "-i", "-c", f"{openclaw_path} acp",
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=sys.stderr # Forward stderr to see agent logs
+    )
+    print(f"TCP Bridge listening on {host}:{port}")
+
+    # Start a background task to forward Agent stdout to all active clients
+    async def agent_to_client():
+        try:
+            async for line in process.stdout:
+                line_str = line.decode('utf-8', errors='ignore')
+                if is_debug:
+                    print(f"Agent -> Clients: {line_str.strip()}", file=sys.stderr)
+                
+                if active_writer:
+                    try:
+                        active_writer.write(line)
+                        await active_writer.drain()
+                    except:
+                        pass
+        except Exception as e:
+            print(f"Agent stream error: {e}", file=sys.stderr)
+        except Exception as e:
+            print(f"Agent stream error: {e}", file=sys.stderr)
+
+    asyncio.create_task(agent_to_client())
+
+    async def handle_client(reader, writer):
+        global active_writer
+        addr = writer.get_extra_info('peername')
+        local_ip = writer.get_extra_info('sockname')[0]
+        
+        # Simple token-based authentication
+        expected_token = token
+        if not expected_token:
+            token_path = os.path.join(os.getcwd(), "token.txt")
+            if os.path.exists(token_path):
+                with open(token_path, "r") as f:
+                    expected_token = f.read().strip()
+        
+        if expected_token:
+                try:
+                    auth_line = await reader.readline()
+                    if auth_line.decode('utf-8').strip() != expected_token:
+                        print(f"Failed authentication from {addr}", file=sys.stderr)
+                        writer.close()
+                        return
+                except Exception as e:
+                    if is_debug: print(f"Auth Error: {e}", file=sys.stderr)
+                    writer.close()
+                    return
+
+        if active_writer is not None:
+            print(f"Preempting existing connection from {active_writer.get_extra_info('peername')}", file=sys.stderr)
+            active_writer.close()
+
+        print(f"Client {addr} authenticated and connected successfully", file=sys.stderr)
+        active_writer = writer
+
+        try:
+            while True:
+                if process.returncode is not None:
+                    print("Background process died, closing connection", file=sys.stderr)
+                    break
+                
+                line = await reader.readline()
+                if not line:
+                    break
+                
+                # Debug logging
+                if is_debug:
+                    try:
+                        tmp_data = json.loads(line)
+                        p = tmp_data.get("params", {})
+                        tmp_sid = p.get("sessionId", p.get("session_id", "no-session"))
+                        print(f"[{addr[0]}] [Session: {tmp_sid}] Client -> Agent: {line.decode('utf-8').strip()}", file=sys.stderr)
+                    except:
+                        print(f"[{addr[0]}] Client -> Agent: {line.decode('utf-8').strip()}", file=sys.stderr)
+                
+                # Interception Logic for Special Mode
+                intercepted = False
+                try:
+                    data = json.loads(line)
+                    method = data.get("method", "")
+                    
+                    if method in ["prompt", "session/prompt"]:
+                        params = data.get("params", {})
+                        prompt_list = params.get("prompt", [])
+                        session_id = params.get("sessionId", params.get("session_id", "unknown"))
+                        request_id = data.get("id")
+
+                        for block in prompt_list:
+                            if block.get("type") == "text":
+                                text = block.get("text", "").strip()
+                                if "/filerequest" in text:
+                                    intercepted = True
+                                    print(f"[{addr[0]}] [Session: {session_id}] [Special Mode] Intercepted: {text}", file=sys.stderr)
+                                    
+                                    path_part = text.split("/filerequest")[-1].strip()
+                                    full_path = os.path.abspath(os.path.expanduser(path_part))
+                                    
+                                    if not os.path.exists(full_path):
+                                        msg = {
+                                            "jsonrpc": "2.0", "method": "session/update", 
+                                            "params": {
+                                                "sessionId": session_id, 
+                                                "update": {
+                                                    "sessionUpdate": "agent_message_chunk", 
+                                                    "content": {"type": "text", "text": f"\nError: {path_part} not found.\n"}
+                                                }
+                                            }
+                                        }
+                                        writer.write(json.dumps(msg).encode() + b"\n")
+                                    else:
+                                        # Prepare file data
+                                        if os.path.isdir(full_path):
+                                            buf = io.BytesIO()
+                                            with zipfile.ZipFile(buf, 'w', zipfile.ZIP_DEFLATED) as zf:
+                                                for r, d, fs in os.walk(full_path):
+                                                    for f in fs:
+                                                        fp = os.path.join(r, f)
+                                                        zf.write(fp, os.path.relpath(fp, full_path))
+                                            file_bytes = buf.getvalue()
+                                            m_type = "application/zip"
+                                            fname = os.path.basename(full_path.rstrip("/\\")) + ".zip"
+                                            
+                                            b64 = base64.b64encode(file_bytes).decode('utf-8')
+                                            
+                                            # Send file chunk
+                                            chunk = {
+                                                "jsonrpc": "2.0", "method": "session/update",
+                                                "params": {
+                                                    "sessionId": session_id,
+                                                    "update": {
+                                                        "sessionUpdate": "agent_message_chunk",
+                                                        "content": {
+                                                            "type": "resource",
+                                                            "resource": {"blob": b64, "mimeType": m_type, "uri": f"file://{fname}"}
+                                                        }
+                                                    }
+                                                }
+                                            }
+                                            writer.write(json.dumps(chunk).encode() + b"\n")
+                                            await writer.drain()
+                                            info_text = f"\n[System]: Sent {fname} ({len(file_bytes)} bytes)\n"
+                                        else:
+                                            m_type, _ = mimetypes.guess_type(full_path)
+                                            m_type = m_type or "application/octet-stream"
+                                            fname = os.path.basename(full_path)
+                                            file_size = os.path.getsize(full_path)
+                                            
+                                            if file_size > 10 * 1024 * 1024 and use_http: # > 10MB and HTTP enabled
+                                                import uuid
+                                                file_id = str(uuid.uuid4())
+                                                served_files[file_id] = full_path
+                                                # Include filename in URL so client can extract it easily
+                                                url = f"http://{local_ip}:{http_port}/{file_id}/{fname}"
+                                                
+                                                chunk = {
+                                                    "jsonrpc": "2.0", "method": "session/update",
+                                                    "params": {
+                                                        "sessionId": session_id,
+                                                        "update": {
+                                                            "sessionUpdate": "agent_message_chunk",
+                                                            "content": {
+                                                                "type": "resource",
+                                                                "resource": {"blob": "AAA=", "mimeType": m_type, "uri": url}
+                                                            }
+                                                        }
+                                                    }
+                                                }
+                                                writer.write(json.dumps(chunk).encode() + b"\n")
+                                                await writer.drain()
+                                                
+                                                info_text = f"\n[System]: Serving large file via HTTP stream: {url} ({file_size} bytes)\n"
+                                            else:
+                                                # Standard Base64 blob (used if small OR if HTTP is disabled)
+                                                with open(full_path, 'rb') as f:
+                                                    file_bytes = f.read()
+                                                b64 = base64.b64encode(file_bytes).decode('utf-8')
+                                                
+                                                chunk = {
+                                                    "jsonrpc": "2.0", "method": "session/update",
+                                                    "params": {
+                                                        "sessionId": session_id,
+                                                        "update": {
+                                                            "sessionUpdate": "agent_message_chunk",
+                                                            "content": {
+                                                                "type": "resource",
+                                                                "resource": {"blob": b64, "mimeType": m_type, "uri": f"file://{fname}"}
+                                                            }
+                                                        }
+                                                    }
+                                                }
+                                                writer.write(json.dumps(chunk).encode() + b"\n")
+                                                await writer.drain()
+                                                info_text = f"\n[System]: Sent {fname} ({len(file_bytes)} bytes)\n"
+                                        
+                                        # Send confirmation text
+                                        info = {
+                                            "jsonrpc": "2.0", "method": "session/update",
+                                            "params": {
+                                                "sessionId": session_id,
+                                                "update": {
+                                                    "sessionUpdate": "agent_message_chunk",
+                                                    "content": {"type": "text", "text": info_text}
+                                                }
+                                            }
+                                        }
+                                        writer.write(json.dumps(info).encode() + b"\n")
+                                        await writer.drain()
+                                        print(f"[{addr[0]}] [Session: {session_id}] [Special Mode] Initiated transfer of {fname}.", file=sys.stderr)
+
+                                    # Increased delay for perfect sync with large files
+                                    await asyncio.sleep(0.5)
+                                    
+                                    # End the turn for this request
+                                    res = {"jsonrpc": "2.0", "id": request_id, "result": {"stop_reason": "end_turn"}}
+                                    writer.write(json.dumps(res).encode() + b"\n")
+                                    await writer.drain()
+                                    break
+                except Exception as e:
+                    if is_debug: print(f"Processing error: {e}", file=sys.stderr)
+
+                if intercepted:
+                    continue
+
+                # Forward standard request to the agent
+                if is_debug and method in ["prompt", "session/prompt"]:
+                    print(f"[{addr[0]}] [Session: {session_id}] Forwarding to Agent...", file=sys.stderr)
+                
+                process.stdin.write(line)
+                await process.stdin.drain()
+
+        except Exception as e:
+            if is_debug: print(f"Connection error: {e}", file=sys.stderr)
+        finally:
+            print(f"Client {addr} disconnected", file=sys.stderr)
+            if active_writer == writer:
+                active_writer = None
+            writer.close()
+
+    server = await asyncio.start_server(handle_client, host, port)
+    async with server:
+        await server.serve_forever()

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: openclaw-acp-bridge
+Version: 0.3.2
+Summary: A high-performance persistent TCP bridge and async client for OpenClaw ACP
+Author: sunshinejnjn@github
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/sunshinejnjn/openclaw-acp-bridge
+Project-URL: Bug Tracker, https://github.com/sunshinejnjn/openclaw-acp-bridge/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Dynamic: license-file
+
+# OpenClaw ACP Bridge
+
+A high-performance, persistent TCP bridge and client for the OpenClaw Agent Control Protocol (ACP).
+
+The **OpenClaw ACP Bridge** solves the challenge of maintaining persistent agent sessions over standard TCP while providing a high-speed "side-channel" for large-scale file transfers. It is designed for high-performance agentic workflows where large binary assets (images, videos, datasets) need to be moved efficiently between remote agents and local clients.
+
+## 🚀 Key Features
+
+- **Persistent Agent Session**: Unlike standard ACP tools that may restart agents per request, the bridge maintains a single persistent agent process across multiple client turns.
+- **High-Speed HTTP Side-Channel**: Automatically switches to HTTP streaming for large files (GB-sized), bypassing JSON-RPC/Base64 overhead and memory bloat.
+- **Explicit File Interception**: Use `/filerequest <path>` to instantly fetch any file from the remote agent's filesystem.
+- **Auto-File Retrieval**: Intelligently detects the `[FILEPATH: /path/to/file]` pattern in agent responses and automatically initiates a high-speed transfer.
+- **Async/Non-Blocking**: Built from the ground up for `asyncio`, utilizing `httpx` for reliable binary streaming.
+- **Environment Consistency**: Server-side agent launching utilizes interactive shells (`bash -i`) to ensure `.bashrc`, NVM, and local paths are correctly resolved.
+
+## 📦 Installation
+On the server (host where your openclaw gateway runs on) side, as the acp_server_bridge.
+And the client side if you want to run with our client interface. Or you can use acp directly to connect to the acp_server_bridge using TCP directly (pip install agent-client-protocol).
+```bash
+pip install openclaw-acp-bridge
+```
+
+## 🛠️ Usage
+
+### 1. Launch the Bridge Server
+On your remote server (where OpenClaw is installed), start the bridge using the provided helper script:
+
+```bash
+chmod +x run_acp_server.sh
+./run_acp_server.sh
+```
+
+Or run the module directly:
+
+```bash
+python -m openclaw_acp_bridge --host 0.0.0.0 --port 18781 --debug
+```
+
+*Note: The bridge will also open a side-channel HTTP server on `port + 1` (default 18782).*
+
+### 2. Connect the Async Client
+On your local machine, use the `OpenClaw` client to interact with the remote agent:
+
+```python
+import asyncio
+from openclaw_acp_bridge import OpenClaw
+
+async def main():
+    # Connect to the remote bridge
+    async with OpenClaw(host="10.71.253.132", download_dir="my_assets") as client:
+        # 1. Standard Chat
+        response = await client.chat("Hello, who are you?")
+        print(f"Agent: {response.text}")
+
+        # 2. Explicit File Request
+        # This uses the high-speed side-channel automatically
+        response = await client.chat("/filerequest /path/to/large_dataset.zip")
+        if response.files:
+            print(f"Received file: {response.files[0]}")
+
+        # 3. Auto-Retrieval Pattern
+        # Ask the agent to generate something and return the path
+        response = await client.chat("Generate a report and return path in [FILEPATH: /path] format.")
+        # The client automatically detects the pattern and fetches the file!
+        for file in response.files:
+            print(f"Auto-downloaded: {file}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 🔌 Using with Standard ACP Clients
+
+The bridge is fully compatible with any standard ACP-compliant client or SDK. To use it, simply point your client to the bridge's TCP address (default port `18781`).
+
+### Why use the Bridge with standard clients?
+1. **Persistence**: Even with a standard client, the bridge keeps your remote agent process alive across sessions.
+2. **Environment**: The bridge handles the complex `bash -i` shell environment setup for you.
+3. **Special Commands**: You can still use `/filerequest <path>` in your prompts. The bridge will intercept these and return a standard ACP `resource` block.
+
+*Note: When using a standard client, the high-speed HTTP side-channel will return a `resource` block with a `uri` starting with `http://`. Ensure your client can handle HTTP-based resources or use our provided `openclaw_acp_bridge` client for automatic handling.*
+
+## ⚙️ Advanced Configuration
+
+### Bridge Server Options
+You can customize the server behavior using CLI arguments:
+
+```bash
+python -m openclaw_acp_bridge --port 18781 --token "my-secret-key" --openclaw-path "/usr/local/bin/openclaw"
+```
+
+| Parameter | Description |
+| :--- | :--- |
+| `--host` | Host to bind the TCP server to (default: `0.0.0.0`) |
+| `--port` | Port to listen on (default: `18781`) |
+| `--token` | Optional authentication token. If set, clients must provide this token to connect. |
+| `--openclaw-path` | Path to the `openclaw` binary on the server (default: `openclaw`) |
+| `--no-http` | Disable the high-speed HTTP side-channel. When set, the bridge uses standard Base64 blobs for all file transfers. |
+| `--debug` | Enable verbose logging for debugging. |
+
+### Authentication
+The bridge supports simple token-based authentication. You can either pass the token via the `--token` CLI argument or place a `token.txt` file in the server's working directory. The `--token` argument takes precedence.
+
+### Download Directory
+The client allows you to specify where downloaded assets should be stored:
+```python
+client = OpenClaw(host="...", download_dir="./downloads")
+```
+
+## 🧪 Testing
+The package includes a comprehensive test suite `test_bridge.py` that demonstrates chat, small file blobs, and large-scale (100MB+) HTTP streaming.
+
+```bash
+python test_bridge.py --tests 1,2,3,4
+```
+
+## 📜 License
+BSD 3-Clause

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+openclaw_acp_bridge/__init__.py
+openclaw_acp_bridge/__main__.py
+openclaw_acp_bridge/client.py
+openclaw_acp_bridge/server.py
+openclaw_acp_bridge.egg-info/PKG-INFO
+openclaw_acp_bridge.egg-info/SOURCES.txt
+openclaw_acp_bridge.egg-info/dependency_links.txt
+openclaw_acp_bridge.egg-info/requires.txt
+openclaw_acp_bridge.egg-info/top_level.txt

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.24.0

openclaw_acp_bridge-0.3.2/openclaw_acp_bridge.egg-info/top_level.txt

@@ -0,0 +1 @@
+openclaw_acp_bridge

openclaw_acp_bridge-0.3.2/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openclaw-acp-bridge"
+version = "0.3.2"
+authors = [
+    { name = "sunshinejnjn@github" },
+]
+license = { text = "BSD-3-Clause" }
+description = "A high-performance persistent TCP bridge and async client for OpenClaw ACP"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Topic :: Communications :: Chat",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/sunshinejnjn/openclaw-acp-bridge"
+"Bug Tracker" = "https://github.com/sunshinejnjn/openclaw-acp-bridge/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["openclaw_acp_bridge*"]

openclaw_acp_bridge-0.3.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+