hermes-baikal
A Hermes Agent plugin for calendar events
and todos on a Baïkal server, or any other RFC 4791 CalDAV
server. It lists, reads and searches your calendars, expands recurring events, and answers
free/busy questions. Creating, editing, completing and deleting items is off until you turn
it on.
Independent community plugin, not affiliated with the Baïkal or sabre/dav projects.
Disclosure
- Network: the plugin talks only to the server in
BAIKAL_CALDAV_URL. That must be
https; plainhttpis accepted only forlocalhost. Every request carries
BAIKAL_USERNAME/BAIKAL_PASSWORD(Basic auth, or Digest when the server asks for it).
It follows no redirects and ignores proxy environment variables. There are no other
endpoints and no telemetry. - Credentials: read through Hermes (
agent.secret_scope.get_secret), stored wherever
Hermes stores secrets (your profile's.env). The plugin never reads credential files
itself and stores nothing. - Writes are opt-in. With
allow_writeoff (the default) only the six read tools are
registered. With it on, the agent can create, change, complete and delete events and
todos on your server. Deletes are permanent and the plugin keeps no copy. Changes reach
everyone who shares or subscribes to that calendar. - Who can use it: the tools are offered on every surface where the
baikaltoolset is
enabled, gateways included. Anyone allowed to talk to your Hermes gateway can read your
calendar (and write to it ifallow_writeis on). Turn surfaces off withhermes tools. - Untrusted text: event and todo text written by other people (meeting invites, shared
calendars) reaches the agent as tool output. - No files, no shell, no background processes. Nothing is written outside the CalDAV
server.
Install
hermes plugins install hermes-baikal # from the plugin catalog, once listed
# or: hermes plugins install https://github.com/tedlefter/hermes-baikal
hermes plugins enable hermes-baikal
Put the credentials in your profile's .env (or fill in the Desktop plugin settings form):
BAIKAL_CALDAV_URL=https://dav.example.com/dav.php/calendars/<user>/ # the calendar home
BAIKAL_USERNAME=<user>
BAIKAL_PASSWORD=<password>
BAIKAL_CALDAV_URL is your calendar home, the collection that contains your
calendars. It is not one calendar. On Baïkal it is /dav.php/calendars/<user>/.
To enable the write tools:
hermes config set plugins.entries.hermes-baikal.settings.allow_write true
Start a new session after enabling the plugin or changing allow_write. Turning
allow_write off takes effect immediately, because every write re-checks it.
Requires Hermes 0.23.1 or later and httpx>=0.25,<1. Hermes already ships httpx.
Tools
| Read (always) | Write (allow_write: true) |
|---|---|
baikal_list_calendars | baikal_create_event |
baikal_list_events | baikal_update_event |
baikal_get_event | baikal_delete_event |
baikal_list_todos | baikal_create_todo |
baikal_get_todo | baikal_update_todo |
baikal_free_busy | baikal_complete_todo |
baikal_delete_todo |
list_events,list_todosandfree_busysearch every calendar that supports the item
type unlesscalendaris given.- Recurring events come back as individual occurrences by default (
expand=falsereturns
the stored series instead). - Updates and deletes use
If-Match. Pass theetagyou read, and the server rejects the
change if the item was modified since. - Event tools touch only events (VEVENT) and todo tools only todos (VTODO).
Known limitations
- Client-side expansion. If the server cannot expand recurrences itself, the plugin
does it. Baïkal answers HTTP 500 for expand and free-busy when a calendar's
calendar-timezoneproperty is a bare TZID such asAmerica/Chicago, which is what
calendars created in Baïkal's web admin get. The client-side expander supports
DAILY/WEEKLY/MONTHLY/YEARLY rules with INTERVAL, COUNT, UNTIL, BYDAY (with ordinals for
monthly/yearly), BYMONTHDAY, BYMONTH and WKST, plus RDATE, EXDATE and per-occurrence
overrides. Any other rule comes back as the stored series with anexpand_errornote.
Free/busy then falls back to the expanded events (TRANSP:TRANSPARENTand
STATUS:CANCELLEDcount as free). - Recurring items. Events with per-occurrence overrides can be read but not edited.
Editing a recurring event changes the whole series. Completing a recurring todo is
refused. - Timezones.
TZIDs that are not IANA names (e.g. Outlook'sCentral Standard Time)
are returned without an offset, and the event carries atzidfield.
Security model
- Every request must stay on the configured origin and under the calendar home. Item
hrefs must be exactly<calendar>/<item>below the home, so no tool can address the home
or a whole calendar. - These are rejected before any request is made: dot segments (raw or percent-encoded),
encoded slashes, backslashes, whitespace and control characters, queries and fragments.
Hrefs returned by the server get the same check. - Response bodies are streamed and capped at 4 MiB. XML that declares a DTD or entities is
refused. - Text written into iCalendar is escaped, so it can't inject properties; control
characters are refused. Edits keep unknown properties, alarms and timezones intact. - Tool errors never include the password, server response bodies, or tracebacks.
Development
pip install pytest radicale "httpx>=0.25,<1"
pytest
The integration tests start a throwaway Radicale server
automatically. The client-side recurrence expander is cross-checked against Radicale's own
server-side expansion. To run the integration tests against another server instead, set
BAIKAL_TEST_URL, BAIKAL_TEST_USER and BAIKAL_TEST_PASSWORD. Every test creates its own
hb-test-* calendar and deletes it afterwards, so don't point them at a calendar home
whose contents you can't afford to have touched.
License
MIT, see LICENSE.
README from the reviewed commit 645e4a3; it updates when the author re-pins.

tedlefter