Metadata-Version: 2.4
Name: agents-ui-sdk
Version: 0.2.0
Summary: Python SDK for the agents-ui terminal workspace application
License: AGPL-3.0-or-later
Project-URL: Homepage, https://agents-ui.com/
Project-URL: Repository, https://github.com/FusionbaseHQ/agents-ui-python-sdk
Project-URL: Documentation, https://github.com/FusionbaseHQ/agents-ui-python-sdk#readme
Project-URL: Parent Project, https://github.com/FusionbaseHQ/agents-ui
Project-URL: Bug Tracker, https://github.com/FusionbaseHQ/agents-ui-python-sdk/issues
Keywords: terminal,agents,sdk,automation,pty
Classifier: Development Status :: 4 - Beta
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: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-timeout>=2; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# agents-ui Python SDK

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

Python SDK for the [agents-ui](https://agents-ui.com/) terminal workspace application. Provides complete programmatic access to the full agents-ui API — 100+ methods across 18 namespaces: terminal sessions, projects, files, SSH, the embedded browser and file viewer, screenshots, shell integration, recordings, real-time events, and more.

This is the official Python client for [agents-ui](https://github.com/FusionbaseHQ/agents-ui), a terminal workspace for AI coding agents.

## Installation

```bash
pip install agents-ui-sdk
```

From source:

```bash
git clone https://github.com/FusionbaseHQ/agents-ui-python-sdk.git
cd agents-ui-python-sdk
pip install -e ".[dev]"
```

## Quick Start

### Async

```python
import asyncio
from agents_ui import AgentsUIClient

async def main():
    async with AgentsUIClient() as client:
        # List projects
        projects = await client.projects.list()
        print(f"Projects: {[p.title for p in projects]}")

        # Create a session and run a command
        session = await client.sessions.create(projects[0].id, name="sdk-demo")
        await client.sessions.write(session.id, "echo hello world\r")

        # Subscribe to output events
        async with client.subscribe(["sessions.output"], session_id=session.id) as stream:
            async for event in stream:
                print(event.data.get("output", ""))
                break

asyncio.run(main())
```

### Sync

```python
from agents_ui import SyncAgentsUIClient

with SyncAgentsUIClient() as client:
    info = client.app.info()
    print(f"Connected to {info.name} v{info.version}")

    projects = client.projects.list()
    for project in projects:
        print(f"  - {project.title} ({project.id})")
```

## Architecture

The SDK communicates with the [agents-ui](https://agents-ui.com/) desktop application over a Unix domain socket using JSON-RPC 2.0. Connection parameters are automatically discovered from `~/.agents-ui/api.json`.

```
Your Python code
      |
      v
 AgentsUIClient  (this SDK)
      |
      v  JSON-RPC 2.0 over Unix socket
      |
 agents-ui desktop app  (Tauri/Rust)
      |
      v  PTY / SSH / filesystem
      |
 Terminal sessions, files, SSH hosts
```

### Key Features

- **Async-first** with a full synchronous wrapper — use whichever fits your project
- **Auto-discovery** — connection parameters are read from `~/.agents-ui/api.json` automatically
- **Complete coverage** — 100+ API methods across 18 namespaces
- **Agent-grade terminal control** — `send_command`, `send_signal`, and `wait_for_*` helpers built on OSC 133 shell integration
- **Typed models** — frozen dataclasses for every domain object with full IDE autocompletion
- **Event streaming** — subscribe to real-time terminal output, command completion, session exits, and more
- **Zero dependencies** — stdlib only (asyncio, json, socket)

### Namespaces

The client organizes methods into namespaces matching the API categories:

| Namespace | Methods | Description |
|-----------|---------|-------------|
| `client.sessions` | 21 | Terminal session lifecycle, I/O, and high-level control helpers |
| `client.persistent_sessions` | 3 | Background persistent sessions |
| `client.projects` | 8 | Workspace project management |
| `client.prompts` | 7 | Reusable command prompts |
| `client.environments` | 5 | Environment configurations |
| `client.assets` | 7 | Project asset templates |
| `client.recordings` | 6 | Session recording playback |
| `client.ssh` | 4 | SSH connection management |
| `client.files` | 7 | Local file operations |
| `client.ssh_files` | 8 | Remote SSH file operations |
| `client.split_views` | 4 | Terminal split panes |
| `client.shell` | 5 | Terminal screen/scrollback and shell-integration state |
| `client.file_viewer` | 7 | File/editor and embedded browser tabs |
| `client.browser` | 6 | Embedded browser navigation |
| `client.capture` | 1 | Screenshot capture of viewer/browser surfaces |
| `client.ui` | 7 | UI control, state, and theme |
| `client.app` | 4 | App info and event subscriptions |
| `client.api` | 2 | API introspection |

### Connection Override

```python
# Use explicit connection parameters instead of auto-discovery
client = AgentsUIClient(
    socket_path="/path/to/api.sock",
    token="your-auth-token",
)
```

### Error Handling

All API errors map to typed exceptions:

```python
from agents_ui import AgentsUIClient, NotFoundError, RateLimitError

async with AgentsUIClient() as client:
    try:
        session = await client.sessions.get("nonexistent")
    except NotFoundError:
        print("Session not found")
    except RateLimitError:
        print("Too many requests")
```

### Driving a terminal like an agent

The `sessions` namespace includes high-level helpers built on OSC 133 shell
integration, so you can run a command and reliably capture its result:

```python
session = await client.sessions.create(project_id, name="agent")

# Run a command and wait for it to finish (captures exit code + output).
import asyncio
wait = asyncio.create_task(client.sessions.wait_for_command_complete(session.id))
await asyncio.sleep(0.2)              # let the subscription register first
await client.sessions.send_command(session.id, "pytest -q")
result = await wait
print(result.exit_code, result.output)

# Interrupt a runaway command, then wait for the prompt to come back.
await client.sessions.send_command(session.id, "sleep 60")
await client.sessions.send_signal(session.id, "SIGINT")   # Ctrl+C
await client.sessions.wait_for_idle(session.id)
```

Inspect live terminal state with the `shell` namespace:

```python
screen = await client.shell.read_screen(session.id)   # visible viewport + cursor
print(screen.content)

status = await client.shell.status(session.id)         # idle / running, cwd, exit
history = await client.shell.command_history(session.id, limit=10)
```

> Shell integration must be active in the session for `wait_for_command_complete`,
> `wait_for_idle`, `command_history`, and `last_result`. `read_screen`,
> `read_scrollback`, and `send_command`/`send_signal` work in any session.

### Embedded browser, file viewer & screenshots

Open file/editor and browser tabs in the workspace, drive the embedded browser,
and capture PNG screenshots — all separate from terminal sessions:

```python
# Open and navigate an embedded browser tab.
await client.file_viewer.open_browser("https://example.com")
await client.browser.navigate("https://www.python.org")
snap = await client.browser.snapshot()

# Save a screenshot of the rendered page.
shot = await client.capture.screenshot(target="browser", max_width=1200)
shot.save("page.png")                  # or use shot.png_bytes

# Open a file in the viewer and read its current text.
await client.file_viewer.open_file("/proj/README.md", mode="markdown")
fv = await client.file_viewer.snapshot()
print(fv.content)
```

### Themes

```python
current = await client.ui.get_theme()
await client.ui.set_theme("midnight")
# dawn, sepia, ember, slate, midnight, cobalt, neon, forest
```

### Event Subscriptions

```python
async with client.subscribe(["sessions.output", "sessions.exit"]) as stream:
    async for event in stream:
        if event.event == "sessions.output":
            print(f"[{event.session_id}] {event.data['output']}")
        elif event.event == "sessions.exit":
            print(f"Session {event.session_id} exited")
            break
```

Useful event names include `sessions.output`, `sessions.exit`,
`shell.command_complete` (fires with `command`, `exitCode`, `output`,
`durationMs`), `shell.prompt_ready`, and the `*.created`/`*.updated`/`*.deleted`
lifecycle events for projects, prompts, sessions, and more. Subscribe with
`["*"]` to receive everything, or pass `session_id=` to filter to one session.

### Utilities

Raw PTY output includes ANSI escape sequences. Use `strip_ansi()` for clean text:

```python
from agents_ui import strip_ansi

clean = strip_ansi(raw_terminal_output)
```

## Examples

The [`examples/`](examples/) directory contains runnable scripts covering every major feature:

| Example | Description |
|---------|-------------|
| [`01_quickstart.py`](examples/01_quickstart.py) | Connect, list projects and sessions (async) |
| [`02_quickstart_sync.py`](examples/02_quickstart_sync.py) | Same as above using the synchronous client |
| [`03_run_command.py`](examples/03_run_command.py) | Create a session, run a command, capture output |
| [`04_file_operations.py`](examples/04_file_operations.py) | List, read, write, rename, and delete files |
| [`05_event_stream.py`](examples/05_event_stream.py) | Subscribe to real-time session output events |
| [`06_project_management.py`](examples/06_project_management.py) | Create, update, list, and delete projects |
| [`07_ssh_hosts.py`](examples/07_ssh_hosts.py) | List SSH hosts and connection history |
| [`08_prompts_and_environments.py`](examples/08_prompts_and_environments.py) | Manage reusable prompts and environment configs |
| [`09_recordings.py`](examples/09_recordings.py) | List and load session recordings |
| [`10_api_introspection.py`](examples/10_api_introspection.py) | Discover all available API methods at runtime |
| [`11_ui_and_theme.py`](examples/11_ui_and_theme.py) | Control UI state, themes, and panel visibility |
| [`12_error_handling.py`](examples/12_error_handling.py) | Typed exceptions and error handling patterns |
| [`13_shell_control.py`](examples/13_shell_control.py) | Run commands, wait for completion, read screen, send signals |
| [`14_workspace_browser.py`](examples/14_workspace_browser.py) | Open file/browser tabs, navigate, and capture screenshots |

Run any example (requires a running [agents-ui](https://agents-ui.com/) instance):

```bash
python examples/01_quickstart.py
```

## Development

```bash
git clone https://github.com/FusionbaseHQ/agents-ui-python-sdk.git
cd agents-ui-python-sdk
pip install -e ".[dev]"

# Run tests (no running app needed — uses a mock server)
pytest

# Type checking
mypy src/agents_ui/
```

## What's new in 0.2.0

Full coverage of the agents-ui API surface — the SDK can now drive every part of the app:

- **`client.shell`** — read the live terminal screen, scrollback, shell status, and OSC 133 command history
- **`client.file_viewer`** — open, focus, close, and snapshot file/editor and embedded browser tabs
- **`client.browser`** — navigate embedded browser tabs (`navigate`, `back`/`forward`/`reload`, `snapshot`)
- **`client.capture`** — capture PNG screenshots of the viewer/browser (`Screenshot.save()` / `.png_bytes`)
- **`client.ui.get_theme` / `set_theme`** — read and switch the UI theme
- **`client.sessions`** — agent-style control helpers: `send_command`, `send_signal`, `wait_for_output`, `wait_for_command_complete`, `wait_for_idle`
- New typed models for all of the above, plus full IDE autocompletion across every namespace

## Requirements

- Python 3.10+
- A running [agents-ui](https://agents-ui.com/) desktop application
- Zero runtime dependencies (stdlib only)

## Related Projects

- [agents-ui](https://github.com/FusionbaseHQ/agents-ui) — The terminal workspace application (Tauri/Rust + React)
- [agents-ui.com](https://agents-ui.com/) — Project homepage and downloads

## License

This project is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0).

See the [LICENSE](LICENSE) file for the full license text.
