Metadata-Version: 2.4
Name: borgee-hermes-plugin
Version: 0.3.1
Summary: Borgee messaging platform adapter for Hermes Agent
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hermes-agent==0.18.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: websockets==15.0.1
Provides-Extra: test
Requires-Dist: build==1.2.2.post1; extra == "test"
Requires-Dist: mypy==1.17.0; extra == "test"
Requires-Dist: pytest==9.0.3; extra == "test"
Requires-Dist: pytest-asyncio==1.3.0; extra == "test"
Requires-Dist: pytest-timeout==2.4.0; extra == "test"
Requires-Dist: ruff==0.12.4; extra == "test"
Requires-Dist: twine==6.1.0; extra == "test"
Dynamic: license-file

# Borgee platform for Hermes Agent

`borgee-hermes-plugin` connects one Hermes Agent 0.18.2 gateway profile to one Borgee agent over BPP. It carries its own copy of the Borgee Python SDK, so it installs without `borgee-plugin-sdk` from PyPI.

## Compatibility

Each row identifies one supported runtime boundary.

| Component | Supported version |
| --- | --- |
| Python | 3.11, 3.12, or 3.13 |
| Hermes distribution | `hermes-agent==0.18.2` |
| Hermes release source | `9de9c25f620ff7f1ce0fd5457d596052d5159596` |
| Borgee Python SDK | vendored from `packages/sdk/plugin-py` |

This package and the SDK are licensed under the MIT License. The repository provides a manual workflow for publishing them to TestPyPI and PyPI; this documentation does not imply that a registry release has occurred.

## Install

Vendor the SDK source into the package before building it from a checkout:

```bash
uv venv .venv
.venv/bin/python packages/plugins/hermes/scripts/vendor_plugin_sdk.py
uv pip install --python .venv/bin/python packages/plugins/hermes
```

Enable the entry-point plugin and configure the platform in the active Hermes profile's `config.yaml`:

```yaml
plugins:
  enabled:
    - borgee

group_sessions_per_user: false

display:
  busy_input_mode: queue

streaming:
  enabled: true

borgee:
  enabled: true
  base_url: https://chat.example.com
  # Set true only for an explicit http://127.0.0.1 or http://localhost server.
  allow_insecure_loopback: false
  max_concurrent_dispatches: 4
  drain_timeout_seconds: 30
```

`streaming.enabled` is a global Hermes setting; it applies to every connected platform by default. To disable streaming for a specific platform, set `platforms.<name>.display.streaming.enabled: false` in that platform's config block.

Put the agent API key in the active profile's `.env`:

```dotenv
BORGEE_API_KEY=bgr_replace_with_the_agent_key
```

`base_url` is non-secret and belongs in `config.yaml`. The API key is accepted only through `BORGEE_API_KEY`; values in `config.yaml` are rejected. Hermes loads each profile's own `.env`, so the same variable name remains profile-isolated without profile-suffixed secret names.

Run one Hermes process and one Borgee socket per `HERMES_HOME`. Leave `gateway.multiplex_profiles` disabled. The adapter takes two Hermes-scoped interprocess locks in a fixed order: a canonical real-`HERMES_HOME` hash, then the Borgee origin plus credential fingerprint. It releases credential then profile. An owner-token registry applies the same exclusions within one process where Hermes locks are PID-reentrant.

## Delivery and session behavior

Borgee authenticates the BPP socket as one agent and applies channel membership and require-mention policy before sending an event. The adapter therefore sets Hermes `authorization_is_upstream=True`; it does not maintain a second local allowlist.

Hermes DMs use `agent:main:borgee:dm:<channel-id>`. Channel conversations use `agent:main:borgee:channel:<channel-id>`. The required top-level `group_sessions_per_user: false` makes two authors in one channel share that channel session while preserving their names on each inbound event.

The plugin checkpoints BPP only after it commits the complete receipt to `$HERMES_HOME/plugins/borgee/inbox.sqlite3`. The SDK cursor advances after that commit, while pending work remains in the durable inbox. A scheduler claims a receipt in SQLite before calling Hermes, preserves FIFO within each ordinary session, and permits bounded concurrency across sessions.

Ingress stores an `ordinary`, `control`, or `urgent_stop` dispatch class using Hermes' real command, plugin-command, and clarify state before the receipt commit. If classification fails, the delivery fails without a checkpoint.

SQLite open, close, and every submitted actor operation settle before cancellation is rethrown. Cancelling open closes any connection created in the worker, shuts down that executor, and makes the actor non-reusable. Close is idempotent and always finishes connection and worker shutdown, including when concurrent lifecycle callers are cancelled.

Hermes slash commands and pending clarify answers bypass an active ordinary turn. For `/queue <payload>` and `/q <payload>`, the adapter removes the prefix in the receipt transaction and keeps the payload as a durable ordinary turn until the session becomes idle. A bare `/queue` follows Hermes' normal inline usage response.

The scheduler can find a persisted control past an arbitrarily deep ordinary backlog, then rechecks the live Hermes bypass state before dispatch. If the session became idle during that check, the receipt must wait for the ordinary FIFO head.

Ordinary and control work have independent bounded lanes, and `/stop` has a separately reserved urgent slot. A timed-out control or urgent execution releases its lane slot, suspends the matching Hermes session when it exists, and quarantines the claimed receipt for explicit remediation.

## Crash recovery

A receipt moves through this state machine:

```text
pending -> processing -> completed | failed
                    \-> in_doubt -> quarantined
```

The `pending -> processing` claim and its unique token commit before Hermes runs. A crash after the claim may have performed tools or sent side effects, so restart never replays that receipt automatically. Startup marks leftover `processing` rows `in_doubt`, suspends every matching Hermes session before the BPP SDK connects, and quarantines the rows.

A missing Hermes session needs no suspension because the next turn cannot continue its old tool tail, but its receipt is still quarantined.

The host can expose the adapter's remediation library method to an operator:

```python
await adapter.remediate_receipt(ingest_seq, "discard")

await adapter.remediate_receipt(
    ingest_seq,
    "requeue",
    confirm_duplicate_side_effect_risk=True,
)
```

Both actions reset an existing Hermes session first. `discard` records an operator decision and never runs the message. `requeue` requires explicit confirmation that tools, provider requests, or outbound effects might occur a second time. There is no automatic requeue path.

During shutdown, the adapter stops admission, drains Hermes processing for the configured bound, and then closes the BPP client, inbox, and both ownership locks. Work that does not finish by the bound becomes `in_doubt` for the same startup quarantine path.

A quarantined receipt blocks later ordinary turns only on its own Hermes session lane until the operator discards or explicitly requeues it. Other sessions remain schedulable; active session keys are excluded before the database query applies its global candidate limit.

## Channel and Zone tools

The plugin registers Borgee domain tools with Hermes' `borgee` toolset. Each registered function has its own parameter schema, and synchronous host dispatch forwards work onto the running gateway loop and BPP client. Tool availability follows the active adapter and `BORGEE_API_KEY`.

`borgee_channel_create` requires the current `guild_id`, a `name`, and explicit nullable `parent_id`. The agent takes the Server ID from the canonical Borgee conversation context. Default (no Zone) is JSON null; a named Zone uses its ID. Placement cannot be edited after creation, and grouping grants no conversation access.

```json
{"guild_id":"server-id","name":"lobby","parent_id":null}
```

`borgee_list_zones` discovers named Zone IDs for one Server. It returns `{zones:[{id,name}],next_after}` in ascending ID order; `next_after: null` marks the end. The default limit is 20, with explicit values from 1 through 50. Pass a returned non-null cursor as `after` only when more discovery is needed. The virtual Default group is not a returned Zone, and a named “Default” remains an ordinary named Zone.

```json
{"guild_id":"server-id","limit":20}
```

The server authorizes the acting agent's current membership on every discovery page and validates its membership, `channel.create` capability, target Organization, and selected Zone when creating a channel. The plugin does not select a remembered Server or inherit the agent owner's membership.

Creation preserves JSON null; missing or malformed placement fails visibly. Update rejects any supplied `parent_id` or `channel_type`, including null and unchanged values. Malformed discovery responses fail through the SDK's checked decoder. There are no model-facing Zone create, rename, or delete tools, and Zone IDs are not conversation targets.

## Outbound behavior

Hermes `send`, `edit_message(finalize=...)`, and `delete_message` map to BPP semantic actions. Edit-based Hermes streaming creates a preview with `send`, updates it with `edit_message`, and accepts the final `finalize=True` call. Typing is a no-op because BPP task lifecycle frames already report real work; the adapter does not invent a typing signal.

Every outbound message ID is persisted for echo filtering. The resolved Borgee agent ID is also filtered, which closes the race where the server broadcasts an agent-authored message before the outbound ID transaction completes.

Agent config updates are acknowledged as `rejected` with a legal BPP reason; Borgee model, prompt, and tool changes are not applied to a running Hermes conversation. Disabling the Borgee agent stops new intake and the connection without claiming cancellation of a turn already executing inside Hermes. `/stop` remains Hermes' real current-turn cancellation command.

## Limits

The inbound adapter handles only text messages and mentions. Attachments, inbound history retrieval, server `read_file` requests, REST side channels, multi-agent routing, and multi-profile multiplexing are outside its boundary. Model tools separately support conversation history reads. Edited, deleted, and reaction events receive durable terminal receipts but do not start inference.
