All plugins

hermes-baikal

Read, search and (opt-in) edit events and todos on a Baïkal or other CalDAV server, with recurrence expansion and free/busy. Disclosure — sends every request to the https URL in BAIKAL_CALDAV_URL (plain http only for localhost) with BAIKAL_USERNAME and BAIKAL_PASSWORD read through Hermes, follows no redirects and ignores proxy variables; only the six read tools register unless the plugin setting allow_write is true, and with it the agent can create, change, complete and permanently delete events and todos, visible to everyone sharing those calendars; the tools are offered on every surface where the baikal toolset is enabled, gateways included, so anyone allowed on your gateway reads your calendar; event text written by other people reaches the agent as tool output; no other endpoint, no telemetry, no file or shell access, no background process. Independent community plugin, not affiliated with Baïkal or sabre/dav.

tedlefterToolsv0.2.0Updated 3 days ago

About

Read, search and (opt-in) edit events and todos on a Baïkal or other CalDAV server, with recurrence expansion and free/busy. Disclosure — sends every request to the https URL in BAIKAL_CALDAV_URL (plain http only for localhost) with BAIKAL_USERNAME and BAIKAL_PASSWORD read through Hermes, follows no redirects and ignores proxy variables; only the six read tools register unless the plugin setting allow_write is true, and with it the agent can create, change, complete and permanently delete events and todos, visible to everyone sharing those calendars; the tools are offered on every surface where the baikal toolset is enabled, gateways included, so anyone allowed on your gateway reads your calendar; event text written by other people reaches the agent as tool output; no other endpoint, no telemetry, no file or shell access, no background process. Independent community plugin, not affiliated with Baïkal or sabre/dav.

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; plain http is accepted only for localhost. 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_write off (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 baikal toolset is
    enabled, gateways included. Anyone allowed to talk to your Hermes gateway can read your
    calendar (and write to it if allow_write is on). Turn surfaces off with hermes 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_calendarsbaikal_create_event
baikal_list_eventsbaikal_update_event
baikal_get_eventbaikal_delete_event
baikal_list_todosbaikal_create_todo
baikal_get_todobaikal_update_todo
baikal_free_busybaikal_complete_todo
baikal_delete_todo
  • list_events, list_todos and free_busy search every calendar that supports the item
    type unless calendar is given.
  • Recurring events come back as individual occurrences by default (expand=false returns
    the stored series instead).
  • Updates and deletes use If-Match. Pass the etag you 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-timezone property is a bare TZID such as America/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 an expand_error note.
    Free/busy then falls back to the expanded events (TRANSP:TRANSPARENT and
    STATUS:CANCELLED count 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's Central Standard Time)
    are returned without an offset, and the event carries a tzid field.

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.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section