Metadata-Version: 2.4
Name: cave-harness
Version: 0.1.0
Summary: Code Agent Virtualization Environment - Virtualize any terminal-based code agent
Author-email: Isaac <isaac@example.com>
License: GPBL-1.0
Project-URL: Homepage, https://github.com/sancovp/cave
Project-URL: Documentation, https://github.com/sancovp/cave#readme
Project-URL: Repository, https://github.com/sancovp/cave
Keywords: ai,agents,claude,virtualization,harness
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic==2.10.6
Requires-Dist: fastapi==0.136.1
Requires-Dist: uvicorn==0.46.0
Requires-Dist: httpx==0.28.1
Requires-Dist: sanctuary-dna>=0.3.5
Requires-Dist: beartype
Requires-Dist: deepmerge
Requires-Dist: svix-ksuid==0.7.0
Requires-Dist: networkx
Requires-Dist: pydash
Requires-Dist: pyee
Requires-Dist: sorcery
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# CAVE — Code Agent Virtualization Environment

**Package:** `cave-harness`

CAVE virtualizes any terminal-based code agent (e.g. Claude Code) behind an HTTP server, so it can be
driven, observed, and orchestrated as a service instead of an interactive terminal. It is the agent
runtime that PromptWorld and the other *Worlds are built on.

## What it gives you

- **An HTTP server around a code agent** — start a long-lived agent process and talk to it over HTTP
  instead of a TTY: inject prompts, stream output, and run it inside a loop.
- **A hook harness** — a registry + dispatch layer for Claude Code hooks (session-start / per-turn /
  stop), so behavior can be layered onto the agent from outside.
- **Loop infrastructure** — the autopoiesis / guru loops that keep an agent working across turns.

## Install

```bash
pip install cave-harness
```

Optional extras:

```bash
pip install "cave-harness[sdna]"   # + sanctuary-dna integration
pip install "cave-harness[dev]"    # + pytest / pytest-asyncio
```

## Run the server

```bash
cave-server
```

This launches the HTTP server (`cave.server.http_server:run_server`, FastAPI + uvicorn). Point your
client at it to register hooks, inject prompts, and drive the virtualized agent.

## Where it sits

CAVE is the **runtime** layer of the SANCREV / GNOSYS stack: the *Worlds (PromptWorld, …) compile their
agents and run them on top of the CAVE harness. See the ecosystem docs for the full picture.

## Docs

Full documentation and the ecosystem map: **https://sancovp.github.io/aisaac/**

## License

GPBL-1.0 — see `LICENSE`.
