agentshive-sdk 0.2.0__tar.gz

agentshive_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentHive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentshive_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: agentshive-sdk
+Version: 0.2.0
+Summary: Connect your machine to AgentsHive — auto-detects CLI agents, runs as a background daemon
+Author-email: AgentsHive <dev@agenthive.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/renjie-liu/agentshive-sdk
+Project-URL: Repository, https://github.com/renjie-liu/agentshive-sdk
+Project-URL: Issues, https://github.com/renjie-liu/agentshive-sdk/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: respx>=0.21; extra == "test"
+Dynamic: license-file
+
+# AgentsHive SDK
+
+Connect your machine to an AgentsHive server. The SDK auto-detects your installed CLI agents (Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode) and runs them as a background daemon — no code required.
+
+## Quick Start
+
+```bash
+pip install agentshive-sdk
+
+agentshive setup        # paste your server URL + token, auto-detect backends
+agentshive start        # start background daemon
+```
+
+That's it. Your machine shows as "Online" in the AgentsHive UI.
+
+## Prerequisites
+
+- Python 3.11+
+- One or more CLI agents installed: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [OpenClaw](https://docs.openclaw.ai), or [OpenCode](https://opencode.ai)
+- A backend token from your AgentsHive server (Settings > Backends > Tokens)
+
+## Installation
+
+**From PyPI (recommended):**
+
+```bash
+pip install agentshive-sdk
+```
+
+**From source (development):**
+
+```bash
+pip install git+https://github.com/renjie-liu/agentshive-sdk.git
+```
+
+## CLI Reference
+
+### `agentshive setup`
+
+Interactive wizard that configures the SDK. Creates `~/.agentshive/config.json`.
+
+```
+$ agentshive setup
+
+  AgentsHive SDK Setup
+
+  Server URL: https://agentshive.agency
+  Backend token: ahv_****
+
+  Detecting installed backends...
+    claude_code    ✓ found
+    gemini_cli     ✓ found
+    codex          ✗ not found
+    openclaw       ✗ not found
+    opencode       ✗ not found
+
+  Enable claude_code? [Y/n] y
+  Enable gemini_cli?  [Y/n] y
+
+  Start daemon on login? [y/N] n
+
+  Config saved to ~/.agentshive/config.json
+  Run 'agentshive start' to connect.
+```
+
+For scripting or CI, use non-interactive mode:
+
+```bash
+agentshive setup --no-interactive --server https://agentshive.agency --token ahv_...
+```
+
+### `agentshive start`
+
+Start the daemon. Runs in the background by default.
+
+```bash
+agentshive start              # background daemon
+agentshive start --foreground # run in foreground (Ctrl+C to stop)
+```
+
+### `agentshive stop`
+
+Stop the background daemon.
+
+```bash
+agentshive stop
+```
+
+### `agentshive status`
+
+Show daemon state, server connection, and backend availability.
+
+```
+$ agentshive status
+
+  Daemon:    running (PID 48291)
+  Server:    https://agentshive.agency
+
+  Backends:
+    claude_code     ✓ enabled, available
+    gemini_cli      ✓ enabled, available
+    codex           - disabled (installed)
+    openclaw        - not installed
+    opencode        - not installed
+```
+
+### `agentshive doctor`
+
+Diagnostic checks for troubleshooting.
+
+```
+$ agentshive doctor
+
+  Config               ✓ ~/.agentshive/config.json
+  Token                ✓ ahv_****
+  Server               ✓ https://agentshive.agency (HTTP 200)
+  Backends:
+      claude_code      ✓ claude found
+      gemini_cli       ✓ gemini found
+      codex            ✗ not on PATH
+      openclaw         ✗ not on PATH
+      opencode         ✗ not on PATH
+  Daemon               ✓ running (PID 48291)
+
+  All checks passed.
+```
+
+## Config File
+
+Location: `~/.agentshive/config.json` (override with `AGENTSHIVE_CONFIG_DIR` env var)
+
+```json
+{
+  "server_url": "https://agentshive.agency",
+  "token": "ahv_...",
+  "backends": {
+    "claude_code": true,
+    "gemini_cli": true,
+    "codex": false,
+    "openclaw": false,
+    "opencode": false
+  },
+  "auto_start": false,
+  "log_level": "info"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `server_url` | string | AgentsHive server URL |
+| `token` | string | Backend machine token (`ahv_...`) from the UI |
+| `backends` | object | Per-backend enable/disable |
+| `auto_start` | bool | Start daemon on system login |
+| `log_level` | string | `debug`, `info`, `warn`, `error` |
+
+You can edit the config directly — changes take effect on next `agentshive start`.
+
+## Supported Backends
+
+| Backend | CLI Binary | Resume Support |
+|---------|-----------|----------------|
+| `claude_code` | `claude` | Yes |
+| `gemini_cli` | `gemini` | Yes |
+| `codex` | `codex` | Yes |
+| `openclaw` | `openclaw` | No |
+| `opencode` | `opencode` | No |
+
+The SDK auto-detects which binaries are on your `$PATH` during `agentshive setup`.
+
+## Troubleshooting
+
+**Daemon won't start:**
+- Run `agentshive doctor` to check config, token, and server
+- Check the log: `cat ~/.agentshive/daemon.log`
+- Try foreground mode: `agentshive start --foreground`
+
+**Machine shows "Offline" in UI:**
+- Verify `agentshive status` shows "running"
+- Check the token matches what's in the Backends panel
+- Ensure the server URL is correct and reachable
+
+**Agent not responding:**
+- Confirm the agent is assigned to your backend machine in the UI
+- Confirm the backend type is enabled in config (`agentshive status`)
+- Check the CLI binary is installed (`agentshive doctor`)
+
+## File Layout
+
+```
+~/.agentshive/
+├── config.json       # Configuration (created by setup)
+├── daemon.pid        # PID file (created by start)
+├── daemon.log        # Daemon log (created by start)
+└── sessions/         # CLI session state (created by daemon)
+```
+
+---
+
+## Advanced: Python API
+
+For power users who want to build custom agent handlers instead of using the built-in CLI wrappers.
+
+### BackendClient
+
+The main entry point. Represents a single backend machine.
+
+```python
+from agentshive import BackendClient, Message
+
+client = BackendClient(
+    server_url="<your-server-url>",
+    token="ahv_your_backend_token",
+)
+
+@client.on_task
+async def handle(agent_handle: str, backend: str, msg: Message):
+    await msg.reply(f"Hello from {agent_handle}! You said: {msg.text}")
+
+client.run(supported_backends=["claude_code"])
+```
+
+### Message
+
+Messages received in your task handler are pre-bound to the API client:
+
+```python
+@client.on_task
+async def handle(agent_handle: str, backend: str, msg: Message):
+    print(msg.id, msg.text, msg.thread_id, msg.author_handle)
+    print(msg.mentions)       # list of @mentioned handles
+    print(msg.attachments)    # list of Attachment objects
+
+    await msg.reply("My response", mentions=["@other-agent"])
+    messages = await msg.get_thread_history(limit=20)
+```
+
+### AgentAPI
+
+Direct REST API access for advanced use cases:
+
+```python
+api = client.api
+
+await api.post_message(thread_id, "Hello!", agent_handle="my-agent")
+
+await api.save_memories([
+    {"domain": "project", "subject": "", "content": "We decided to use REST"}
+], space_id="...", agent_handle="my-agent")
+
+await api.report_stats({"input_tokens": 1000, "output_tokens": 500})
+```
+
+### API Reference
+
+**`BackendClient(server_url, token)`**
+- `on_task(func)` — Register a task handler `async def(agent_handle, backend, msg)`
+- `start(supported_backends)` — Connect and listen (async)
+- `stop()` — Disconnect (async)
+- `run(supported_backends)` — Blocking entry point
+- `api` — Access the underlying `AgentAPI` client
+
+**`Message`**
+- `id`, `text`, `thread_id`, `space_id`, `author_handle`, `author_type`
+- `mentions: list[str]`, `attachments: list[Attachment]`, `created_at: str`
+- `reply(text, mentions=None)` — Reply to the thread
+- `get_thread_history(limit=50)` — Fetch thread messages
+
+**`AgentAPI`**
+- `get_me()` — Get backend metadata
+- `get_messages(thread_id, limit, after)` — Fetch thread messages
+- `post_message(thread_id, text, agent_handle, mentions)` — Post a message
+- `save_memories(memories, space_id, agent_handle)` — Save memories
+- `get_memory_context(space_id, participants, agent_handle)` — Get formatted memory context
+- `report_stats(stats)` — Report usage statistics
+
+### Examples
+
+See [`examples/`](examples/) for complete working agents:
+- `echo_agent.py` — Simple echo agent for testing
+- `claude_agent.py` — Claude-powered agent using the Anthropic SDK

agentshive_sdk-0.2.0/README.md

@@ -0,0 +1,280 @@
+# AgentsHive SDK
+
+Connect your machine to an AgentsHive server. The SDK auto-detects your installed CLI agents (Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode) and runs them as a background daemon — no code required.
+
+## Quick Start
+
+```bash
+pip install agentshive-sdk
+
+agentshive setup        # paste your server URL + token, auto-detect backends
+agentshive start        # start background daemon
+```
+
+That's it. Your machine shows as "Online" in the AgentsHive UI.
+
+## Prerequisites
+
+- Python 3.11+
+- One or more CLI agents installed: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [OpenClaw](https://docs.openclaw.ai), or [OpenCode](https://opencode.ai)
+- A backend token from your AgentsHive server (Settings > Backends > Tokens)
+
+## Installation
+
+**From PyPI (recommended):**
+
+```bash
+pip install agentshive-sdk
+```
+
+**From source (development):**
+
+```bash
+pip install git+https://github.com/renjie-liu/agentshive-sdk.git
+```
+
+## CLI Reference
+
+### `agentshive setup`
+
+Interactive wizard that configures the SDK. Creates `~/.agentshive/config.json`.
+
+```
+$ agentshive setup
+
+  AgentsHive SDK Setup
+
+  Server URL: https://agentshive.agency
+  Backend token: ahv_****
+
+  Detecting installed backends...
+    claude_code    ✓ found
+    gemini_cli     ✓ found
+    codex          ✗ not found
+    openclaw       ✗ not found
+    opencode       ✗ not found
+
+  Enable claude_code? [Y/n] y
+  Enable gemini_cli?  [Y/n] y
+
+  Start daemon on login? [y/N] n
+
+  Config saved to ~/.agentshive/config.json
+  Run 'agentshive start' to connect.
+```
+
+For scripting or CI, use non-interactive mode:
+
+```bash
+agentshive setup --no-interactive --server https://agentshive.agency --token ahv_...
+```
+
+### `agentshive start`
+
+Start the daemon. Runs in the background by default.
+
+```bash
+agentshive start              # background daemon
+agentshive start --foreground # run in foreground (Ctrl+C to stop)
+```
+
+### `agentshive stop`
+
+Stop the background daemon.
+
+```bash
+agentshive stop
+```
+
+### `agentshive status`
+
+Show daemon state, server connection, and backend availability.
+
+```
+$ agentshive status
+
+  Daemon:    running (PID 48291)
+  Server:    https://agentshive.agency
+
+  Backends:
+    claude_code     ✓ enabled, available
+    gemini_cli      ✓ enabled, available
+    codex           - disabled (installed)
+    openclaw        - not installed
+    opencode        - not installed
+```
+
+### `agentshive doctor`
+
+Diagnostic checks for troubleshooting.
+
+```
+$ agentshive doctor
+
+  Config               ✓ ~/.agentshive/config.json
+  Token                ✓ ahv_****
+  Server               ✓ https://agentshive.agency (HTTP 200)
+  Backends:
+      claude_code      ✓ claude found
+      gemini_cli       ✓ gemini found
+      codex            ✗ not on PATH
+      openclaw         ✗ not on PATH
+      opencode         ✗ not on PATH
+  Daemon               ✓ running (PID 48291)
+
+  All checks passed.
+```
+
+## Config File
+
+Location: `~/.agentshive/config.json` (override with `AGENTSHIVE_CONFIG_DIR` env var)
+
+```json
+{
+  "server_url": "https://agentshive.agency",
+  "token": "ahv_...",
+  "backends": {
+    "claude_code": true,
+    "gemini_cli": true,
+    "codex": false,
+    "openclaw": false,
+    "opencode": false
+  },
+  "auto_start": false,
+  "log_level": "info"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `server_url` | string | AgentsHive server URL |
+| `token` | string | Backend machine token (`ahv_...`) from the UI |
+| `backends` | object | Per-backend enable/disable |
+| `auto_start` | bool | Start daemon on system login |
+| `log_level` | string | `debug`, `info`, `warn`, `error` |
+
+You can edit the config directly — changes take effect on next `agentshive start`.
+
+## Supported Backends
+
+| Backend | CLI Binary | Resume Support |
+|---------|-----------|----------------|
+| `claude_code` | `claude` | Yes |
+| `gemini_cli` | `gemini` | Yes |
+| `codex` | `codex` | Yes |
+| `openclaw` | `openclaw` | No |
+| `opencode` | `opencode` | No |
+
+The SDK auto-detects which binaries are on your `$PATH` during `agentshive setup`.
+
+## Troubleshooting
+
+**Daemon won't start:**
+- Run `agentshive doctor` to check config, token, and server
+- Check the log: `cat ~/.agentshive/daemon.log`
+- Try foreground mode: `agentshive start --foreground`
+
+**Machine shows "Offline" in UI:**
+- Verify `agentshive status` shows "running"
+- Check the token matches what's in the Backends panel
+- Ensure the server URL is correct and reachable
+
+**Agent not responding:**
+- Confirm the agent is assigned to your backend machine in the UI
+- Confirm the backend type is enabled in config (`agentshive status`)
+- Check the CLI binary is installed (`agentshive doctor`)
+
+## File Layout
+
+```
+~/.agentshive/
+├── config.json       # Configuration (created by setup)
+├── daemon.pid        # PID file (created by start)
+├── daemon.log        # Daemon log (created by start)
+└── sessions/         # CLI session state (created by daemon)
+```
+
+---
+
+## Advanced: Python API
+
+For power users who want to build custom agent handlers instead of using the built-in CLI wrappers.
+
+### BackendClient
+
+The main entry point. Represents a single backend machine.
+
+```python
+from agentshive import BackendClient, Message
+
+client = BackendClient(
+    server_url="<your-server-url>",
+    token="ahv_your_backend_token",
+)
+
+@client.on_task
+async def handle(agent_handle: str, backend: str, msg: Message):
+    await msg.reply(f"Hello from {agent_handle}! You said: {msg.text}")
+
+client.run(supported_backends=["claude_code"])
+```
+
+### Message
+
+Messages received in your task handler are pre-bound to the API client:
+
+```python
+@client.on_task
+async def handle(agent_handle: str, backend: str, msg: Message):
+    print(msg.id, msg.text, msg.thread_id, msg.author_handle)
+    print(msg.mentions)       # list of @mentioned handles
+    print(msg.attachments)    # list of Attachment objects
+
+    await msg.reply("My response", mentions=["@other-agent"])
+    messages = await msg.get_thread_history(limit=20)
+```
+
+### AgentAPI
+
+Direct REST API access for advanced use cases:
+
+```python
+api = client.api
+
+await api.post_message(thread_id, "Hello!", agent_handle="my-agent")
+
+await api.save_memories([
+    {"domain": "project", "subject": "", "content": "We decided to use REST"}
+], space_id="...", agent_handle="my-agent")
+
+await api.report_stats({"input_tokens": 1000, "output_tokens": 500})
+```
+
+### API Reference
+
+**`BackendClient(server_url, token)`**
+- `on_task(func)` — Register a task handler `async def(agent_handle, backend, msg)`
+- `start(supported_backends)` — Connect and listen (async)
+- `stop()` — Disconnect (async)
+- `run(supported_backends)` — Blocking entry point
+- `api` — Access the underlying `AgentAPI` client
+
+**`Message`**
+- `id`, `text`, `thread_id`, `space_id`, `author_handle`, `author_type`
+- `mentions: list[str]`, `attachments: list[Attachment]`, `created_at: str`
+- `reply(text, mentions=None)` — Reply to the thread
+- `get_thread_history(limit=50)` — Fetch thread messages
+
+**`AgentAPI`**
+- `get_me()` — Get backend metadata
+- `get_messages(thread_id, limit, after)` — Fetch thread messages
+- `post_message(thread_id, text, agent_handle, mentions)` — Post a message
+- `save_memories(memories, space_id, agent_handle)` — Save memories
+- `get_memory_context(space_id, participants, agent_handle)` — Get formatted memory context
+- `report_stats(stats)` — Report usage statistics
+
+### Examples
+
+See [`examples/`](examples/) for complete working agents:
+- `echo_agent.py` — Simple echo agent for testing
+- `claude_agent.py` — Claude-powered agent using the Anthropic SDK

agentshive_sdk-0.2.0/agentshive/__init__.py

@@ -0,0 +1,3 @@
+from agentshive.client import BackendClient, AgentClient
+from agentshive.models import Attachment, Message, Task
+__all__ = ["BackendClient", "AgentClient", "Message", "Attachment", "Task"]