feat(runtimed-py): introduce Python bindings for daemon client

[rgbkrk]

Summary

Introduces the runtimed Python package - PyO3 bindings that enable programmatic notebook execution from Python. This is the foundation for agent tooling, MCP integrations, and automation workflows.

What's included:

• PyO3 bindings exposing daemon operations to Python
• Document-first execution model (cells synced via automerge)
• Multi-client support (multiple sessions can share a notebook)
• Comprehensive integration test suite (24 tests)
• CI workflow for automated testing

New Components

Rust Crate: crates/runtimed-py/

Class	Purpose
DaemonClient	Low-level daemon ops: ping, status, list_rooms, flush_pool, shutdown
Session	High-level notebook execution with kernel lifecycle
Cell	Cell from automerge document (id, type, source, execution_count)
ExecutionResult	Execution result with outputs, success flag, stdout/stderr helpers
Output	Single output (stream, display_data, execute_result, error)
RuntimedError	Exception type for daemon errors

Python Package: python/runtimed/

python/runtimed/
├── pyproject.toml           # Maturin build config
├── src/runtimed/
│   ├── __init__.py          # Public API exports
│   ├── _binary.py           # runt binary discovery
│   ├── _sidecar.py          # Sidecar launcher for rich output
│   └── _ipython_bridge.py   # IOPub bridge for terminal IPython
└── tests/
    ├── test_daemon_integration.py  # 24 integration tests
    ├── test_sidecar.py             # Sidecar unit tests
    ├── test_ipython_bridge.py      # Bridge unit tests
    └── conftest.py                 # Pytest config

API Examples

Session (code execution)

import runtimed

# Basic execution
with runtimed.Session(notebook_id="my-notebook") as session:
    session.start_kernel()
    result = session.run("print('hello')")
    print(result.stdout)  # "hello\n"

# Document-first pattern
session = runtimed.Session()
session.connect()
session.start_kernel()

# Create cell in automerge doc (syncs to all clients)
cell_id = session.create_cell("x = 42")

# Execute reads from document, not passed code
result = session.execute_cell(cell_id)

# Document operations
session.set_source(cell_id, "x = 100")  # Update cell
cell = session.get_cell(cell_id)         # Get cell info
cells = session.get_cells()              # List all cells
session.delete_cell(cell_id)             # Remove cell

DaemonClient (low-level ops)

client = runtimed.DaemonClient()
client.ping()        # True if daemon responding
stats = client.status()  # Pool stats
rooms = client.list_rooms()  # Active notebook rooms

Document-First Execution

The bindings implement the architectural principle that execution reads from the automerge document rather than receiving code directly:

1. session.create_cell(source) - Creates cell in automerge doc
2. session.execute_cell(cell_id) - Daemon reads source from doc
3. All connected clients see the same code being executed

This enables multi-client scenarios where two Python sessions (or a Python session + the notebook app) can share a notebook and see each other's changes.

Integration Tests

24 tests covering:

• Basic connectivity (2 tests) - Session connect, repr
• Document-first execution (8 tests) - Cell CRUD, execute reads from doc
• Multi-client sync (4 tests) - Two sessions sharing a notebook
• Kernel lifecycle (3 tests) - Start, interrupt, shutdown
• Output types (4 tests) - stdout, stderr, display_data, errors
• Error handling (3 tests) - Execute without kernel, missing cells, syntax errors

Test plan

• All 24 integration tests pass locally
• CI workflow added (runtimed-py-integration job)
• Multi-client automerge sync verified
• Document-first execution pattern verified

[captainsafia]

Can we use the CONDUCTOR_WORKSPACE_PATH here as a better fallback?

[rgbkrk]

Good idea! We'll use that in CI too.