# Dirigent

<p align="center">
  <img src="dirigent.svg" alt="Dirigent" width="64" height="64">
</p>

<p align="center">Core libraries for the Dirigent agent orchestration platform.</p>

> [!CAUTION]
> **Alpha software.** Dirigent is in early active development and not fully battle-tested. Most crates are experimental — APIs will change without notice. There is nothing to install from this repository yet. The standalone tools listed below have their own repositories and maturity levels.

---

## Standalone Tools

These tools are developed in this monorepo but distributed as independent repositories. Install them from their own repos:

| Tool | Repository | Maturity | Description |
|------|-----------|----------|-------------|
| **fermata** | [git.g4b.org/dirigence/fermata](https://git.g4b.org/dirigence/fermata) | production (core), beta (toml config) | Policy gate for AI coding agents — `.botignore` enforcement |
| **anth** | [git.g4b.org/dirigence/dirigent_anth](https://git.g4b.org/dirigence/dirigent_anth) | production (library), beta (CLIs) | Tools for working with Claude Code session data |
| **dirigate** | [git.g4b.org/dirigence/dirigate](https://git.g4b.org/dirigence/dirigate) | beta (bridge/mock), concept (connect/ingest) | ACP bridge connecting stdio agents to Dirigent |

---

## Architecture

<p align="center">
  <img src="architecture.svg" alt="Dirigent package architecture" width="720">
</p>

**Layers top-to-bottom:**
- **Consumers** *(shadow)* — server assembly, web app, integrations — not in this repo
- **Standalone Tools** — installable from their own repositories; depend on these crates
- **Orchestration** — connector runtime, ACP server
- **Foundation** — protocol types, tool sandbox, configuration, auth

---

## Core Runtime

`dirigent_core` is the central crate. It manages long-lived connections to external agent systems through a **Connector** abstraction — each connector wraps a bidirectional communication channel to an agent (Claude Code over stdio, OpenCode.ai over HTTP+SSE, or an incoming ACP connection).

<p align="center">
  <img src="core-architecture.svg" alt="dirigent_core internal architecture" width="720">
</p>

**Key concepts:**

- **CoreRuntime** is a stateless orchestrator. It owns the connector registry, the event bus, and lifecycle hooks — but never caches session state. The external agent is always authoritative.
- **Connectors** implement a common trait (`command_tx()` to send commands, `subscribe()` to receive events) and run as independent background tasks. Four implementations ship today: ACP (stdio/HTTP JSON-RPC), Gateway (local echo + session transfer), OpenCode (REST+SSE), and AcpAcceptor (incoming connections).
- **SharingBus** is the event backbone. Every connector event is published once and fan-out to filtered subscribers — archivist, web UI, stream integrations — without the bus knowing about any of them.
- **Lifecycle Hooks** let the server assembly inject services (inspector, process manager, archivist) at connector creation time. Core defines abstract traits (`ConnectorInspector`, `ProcessGroupManager`) and never depends on their implementations directly.

---

## Crates

| Crate | Maturity | Description |
|-------|----------|-------------|
| `dirigent_core` | beta | Multi-connector orchestration runtime |
| `dirigent_protocol` | beta | ACP protocol types — messages, events, and RPC definitions |
| `dirigent_acp_api` | beta | ACP server for incoming agent connections |
| `dirigent_config` | beta | Configuration management |
| `dirigent_auth` | concept | User authorization model |
| `dirigent_tools` | concept | Tool sandbox and execution abstractions |
| `opencode_client` | beta | OpenCode.ai HTTP client |

---

## Library Usage

Add a crate to your `Cargo.toml`:

```toml
[dependencies]
dirigent_protocol = { git = "https://git.g4b.org/dirigence/dirigent", path = "crates/dirigent_protocol" }
dirigent_core     = { git = "https://git.g4b.org/dirigence/dirigent", path = "crates/dirigent_core" }
```

Replace the crate name and path with the one you need. All crates follow the same pattern.

> [!CAUTION]
> **Expect breakage.** These are internal library crates under active development. Pin to a specific commit if you depend on stability.

---

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
- MIT License ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)

at your option.