plugins/caldav
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

one CRUD, three callers — the browser and the agent stop writing iCalendar

Browse Source 
the skill told an agent how to hand-write a .ics: escape the commas, fold at 75
octets, CRLF, DTSTAMP is required, and DTEND is the day after. all true, all
silent when wrong, and the browser had learned the same lesson separately in its
own copy of the code. this makes the sidecar the only thing that knows the
format, and gives everyone else fields.

WHAT WAS MISSING BEFORE THE SKILL COULD CHANGE. reading was already JSON, and
create-event landed this morning. this adds PATCH /_officer/item — change some
fields of an event or a card — and POST /_officer/contact. delete already worked.
with those the skill has no reason left to mention iCalendar, so it does not.

PATCH IS READ-PATCH-PUT, SERVER SIDE. it reads the stored text, replaces only the
lines it owns, and puts the whole thing back, so alarms, attendees, RRULEs and
every X- property a phone invented survive an edit made from a form that cannot
show them. that logic came out of the browser, where it had needed a duplicate of
the escaping and folding rules to live; the agent would have been a third copy in
bash. the web bundle now contains no iCalendar literals at all.

AND LIVE TESTING FOUND THE BUG THAT MATTERS. an event with a TZID is stored with
a VTIMEZONE block beside it, and that block has DTSTART lines of its own — the
rule for when summer time starts. taking the first DTSTART in the file rewrote
the TIMEZONE DEFINITION, left the event where it was, and answered ok. the
calendar showed the old time and the file was quietly corrupt. every write is now
confined to the first VEVENT or VCARD, and the file that caught it is a test.

three more traps handled rather than documented: a patch that reuses an all-day
event's stored DTEND must subtract the exclusive day first or the holiday drifts
every time the title is edited; moving a timed event must DROP a stale TZID
rather than preserve it, because a TZID and a Z together are a contradiction
clients resolve by moving the event; and a move bumps SEQUENCE, which is how a
phone tells an update from a duplicate.

contacts got the create form the calendar had, so both screens now do all four.
editing a card sends the other emails and phones back untouched — the form shows
the first of each, and sending only that would delete the rest.

47 tests across the writer and the patcher. verified live against a real event
carrying an alarm, an attendee, an RRULE and an X- property: all four intact
after a rename, a relocation and a move to a different day.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
This commit is contained in:
pastilhas
2026-08-27 10:51:22 +00:00
co-authored by Claude Opus 5
parent 25c8502c4b
commit 43cb531dc2
10 changed files with 871 additions and 348 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/calendar-and-contacts/SKILL.md
+88 -117
View File
@@ -1,180 +1,151 @@
---
name: Calendar and contacts
description: Use when the owner asks you to add, move, cancel or look up an event, or to add, remove or find a contact — "dinner Saturday with my wife", "cancel that", "when am I seeing the CEO", "add Peter Griffin, this number". Carries the working recipes, the two credentials, and the timezone trap that puts every event an hour out.
version: 1
description: Use when the owner asks you to add, move, cancel or look up an event, or to add, remove or find a contact — "dinner Saturday with my wife", "move that to 9", "when am I seeing the CEO", "add Peter Griffin, this number". Carries the JSON routes, the one credential, and the timezone trap that puts every event an hour out.
version: 2
---
You can read and write the owner's calendars and address book directly. **Reading goes through Officer's
API. Writing goes through the DAV door.** Both use credentials you already have; there is nothing to ask
for and no password to be given.
You can read and write the owner's calendars and address books. **It is a JSON API and you already have
the key.** Nothing to ask for, no password to be given, no XML.
## The two doors
You do not write iCalendar or vCard by hand. You did once, and the recipes were long because the format
is full of things that fail silently — escaping, 75-octet line folding, an end date that is exclusive,
a timezone definition with dates of its own. All of that now happens on the server. Send fields.
**Read — Officer's own API, with `$OFFICER_AGENT_KEY`.** Parsed JSON, no XML.
## The one door
```bash
curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
"$OFFICER_API_URL/api/caldav/_officer/collections"
```
**Write — the DAV door, HTTP Basic, the SAME key as the password.**
```bash
ME=$(curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
"$OFFICER_API_URL/api/auth/me" | python3 -c 'import json,sys; print(json.load(sys.stdin)["email"])')
AUTH="$ME:$OFFICER_AGENT_KEY"
OFFICER=(-H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST"
-H 'content-type: application/json')
curl -s "${OFFICER[@]}" "$OFFICER_API_URL/api/caldav/_officer/collections"
```
Your key is bound to ONE account — the owner's. You cannot reach anyone else's calendar with it and you
do not need to guard against doing so: another principal answers 403, and naming a different user in the
Basic header answers 401. Write the owner's own paths and stop thinking about it.
do not need to guard against doing so: another user's path answers 400. Write the owner's own paths and
stop thinking about it.
## Find the collections first — never guess a path
```bash
curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
"$OFFICER_API_URL/api/caldav/_officer/collections"
# {"collections":[{"path":"/dav/1/personal/","displayName":"Personal","kind":"calendar", ...},
# {"path":"/dav/1/contacts/","displayName":"Contacts","kind":"addressbook"}]}
# {"collections":[{"path":"/dav/1/personal/","name":"personal","displayName":"Personal","kind":"calendar"},
# {"path":"/dav/1/contacts/","name":"contacts","displayName":"Contacts","kind":"addressbook"}]}
```
`kind` is `calendar` or `addressbook`. There are usually several calendars — **"Personal" is the default
for anything the owner does not place**, and Tasks holds VTODOs that show up in Reminders on a phone.
`kind` is `calendar` or `addressbook`. Pass the **`path`** to every route below. There are usually
several calendars — **"Personal" is the default for anything the owner does not place** — and Tasks holds
VTODOs, which show up in Reminders on a phone.
## THE TIMEZONE TRAP — read this before writing any time
The owner says "Saturday at 8". Calendars store UTC. **`date -u -d` does not convert** — `-u` makes GNU
date parse the input as UTC *and* print UTC, so "8pm" becomes 20:00Z, which is 21:00 in Lisbon. Every
event lands an hour out and nothing errors.
The owner says "Saturday at 8". The API takes UTC. **`date -u -d` does not convert** — `-u` makes GNU
date parse the input as UTC *and* print it as UTC, so "8pm" becomes 20:00Z, which is 21:00 in Lisbon.
Every event lands an hour out and nothing errors.
```bash
# WRONG — prints 20260829T200000Z
date -u -d 'saturday 20:00' +%Y%m%dT%H%M%SZ
# RIGHT — prints 20260829T190000Z, via epoch so the local zone is applied
date -u -d "@$(date -d 'saturday 20:00' +%s)" +%Y%m%dT%H%M%SZ
# WRONG — prints 2026-08-29T20:00:00Z
date -u -d 'saturday 20:00' +%Y-%m-%dT%H:%M:%SZ
# RIGHT — prints 2026-08-29T19:00:00Z, via epoch so the local zone is applied
date -u -d "@$(date -d 'saturday 20:00' +%s)" +%Y-%m-%dT%H:%M:%SZ
```
The machine's clock is the owner's timezone. Parse what they said with plain `date -d`, convert through
`+%s`, and **say the LOCAL time back to them** when you confirm — never the UTC you stored.
## Create an event
**The short way, for an ordinary event.** One POST, and the sidecar writes the file — it mints the UID
and the filename, converts to UTC, escapes the text and folds any line over 75 octets. All the parts
below that are easy to get subtly wrong.
## Look something up
```bash
curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
-H 'content-type: application/json' -X POST "$OFFICER_API_URL/api/caldav/_officer/event" \
curl -s "${OFFICER[@]}" "$OFFICER_API_URL/api/caldav/_officer/events?collection=%2Fdav%2F1%2Fpersonal%2F"
# {"events":[{"uid":"…","href":"/dav/1/personal/….ics","summary":"Dinner with my wife",
# "start":"2026-08-29T19:00:00Z","location":"Cervejaria Ramiro","allDay":false}]}
```
Contacts are the same shape at `_officer/contacts`, returning `fullName`, `emails` and `phones`.
**Search every calendar, not just Personal** — the answer is often in another one. `start` and `end` are
UTC, so convert before speaking: `date -d '2026-08-29T19:00:00Z' '+%A %-d %B, %H:%M'`.
`rrule` present means the event REPEATS and the listed `start` is the series start, not the next
occurrence. Do not compute occurrences yourself — say it repeats and give the rule in words.
**`href` is how you change or delete a thing, and it only ever comes from a read.** Never build one. A
file is only conventionally named after its UID: everything a phone wrote is named something else, and a
constructed href finds nothing or, worse, finds something.
## Add an event
```bash
curl -s "${OFFICER[@]}" -X POST "$OFFICER_API_URL/api/caldav/_officer/event" \
-d '{"collection":"/dav/1/personal/","summary":"Dinner with my wife","location":"Cervejaria Ramiro",
"start":"2026-08-29T19:00:00Z","end":"2026-08-29T21:00:00Z","allDay":false}'
# {"href":"/dav/1/personal/<uuid>.ics"}
```
All-day takes plain dates and no times: `{"start":"2026-08-29","allDay":true}`. `end` is the LAST day as
a person means it — the exclusive DTEND is this route's problem, not yours.
a person means it — a two-day trip is `"start":"2026-08-29","end":"2026-08-30"`. No end means one hour,
or one day.
It writes a minimal VEVENT and nothing else. **Anything with a recurrence rule, an alarm or attendees
has to be written by hand**, below.
## Create an event by hand
The filename must be `<UID>.ics`, and iCalendar lines are **CRLF-terminated**. `DTSTAMP` is required.
## Add a contact
```bash
UID="officer-$(date +%s)-$RANDOM"
S=$(date -u -d "@$(date -d 'saturday 20:00' +%s)" +%Y%m%dT%H%M%SZ)
E=$(date -u -d "@$(date -d 'saturday 22:00' +%s)" +%Y%m%dT%H%M%SZ)
printf "BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//Officer//agent//EN\r\nBEGIN:VEVENT\r\nUID:$UID\r\nDTSTAMP:$(date -u +%Y%m%dT%H%M%SZ)\r\nDTSTART:$S\r\nDTEND:$E\r\nSUMMARY:Dinner with my wife\r\nLOCATION:Cervejaria Ramiro\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n" \
| curl -s -o /dev/null -w '%{http_code}\n' -u "$AUTH" -X PUT \
-H 'Content-Type: text/calendar; charset=utf-8' --data-binary @- \
"$OFFICER_API_URL/dav/1/personal/$UID.ics"
# 201 created
curl -s "${OFFICER[@]}" -X POST "$OFFICER_API_URL/api/caldav/_officer/contact" \
-d '{"collection":"/dav/1/contacts/","fullName":"Peter Griffin",
"emails":["peter@quahog.example"],"phones":["+351912345678"],"org":"Pawtucket Brewery"}'
```
An **all-day** event uses dates, not times, and DTEND is the day AFTER:
`DTSTART;VALUE=DATE:20260829` with `DTEND;VALUE=DATE:20260830`. Writing the same day produces a
zero-length event that some clients simply do not draw.
`fullName` is what a phone displays and is required. Phone numbers keep their international prefix.
Two more that bite when writing by hand, and are why the JSON route above exists: a comma, semicolon or
backslash inside a SUMMARY must be backslash-escaped or it splits the value, and a content line over 75
octets must be folded onto a continuation line starting with one space.
## Change something
## Look something up
"When am I having dinner with the CEO?" — read, filter, answer in local time.
One PATCH, with only the fields that change. Everything else in the file is left exactly as it was —
including alarms, attendees, recurrence rules and anything a phone put there that Officer has no idea
about.
```bash
curl -s -H "Authorization: Bearer $OFFICER_AGENT_KEY" -H "Host: $OFFICER_API_HOST" \
"$OFFICER_API_URL/api/caldav/_officer/events?collection=%2Fdav%2F1%2Fpersonal%2F"
# {"events":[{"uid":"…","summary":"Dinner with my wife","start":"2026-08-29T19:00:00Z","end":"…",
# "location":"Cervejaria Ramiro","allDay":false}]}
curl -s "${OFFICER[@]}" -X PATCH "$OFFICER_API_URL/api/caldav/_officer/item" \
-d '{"href":"/dav/1/personal/….ics","start":"2026-08-29T20:00:00Z","end":"2026-08-29T22:00:00Z"}'
# {"ok":true,"item":{…the whole thing, as it now reads…}}
```
`start` and `end` are UTC. **Convert before speaking**: `date -d '2026-08-29T19:00:00Z' '+%A %-d %B, %H:%M'`.
- **Events**: `summary`, `location`, `description`, `start`, `end`, `allDay`.
- **Contacts**: `fullName`, `emails`, `phones`, `org`, `title`.
- `null` REMOVES a field. `""` leaves it there and empty. Omit it to leave it alone.
- `emails` and `phones` replace the whole list. To add a number, send the existing ones back with the new
one — read first.
Search every calendar, not just Personal — the answer is often in another one. `location` is where
"where did I set it up" is answered from; if it is empty, say so rather than inventing somewhere.
**Moving an event is a PATCH, not a new event.** Creating a second one and leaving the first is the most
common way this goes wrong, and the owner finds out when two of them ring.
`rrule` present means the event REPEATS and the listed `start` is the series start, not the next
occurrence. Do not compute occurrences yourself — say it repeats and give the rule in words.
**Confirm from `item`, not from what you sent.** It is the file re-read after the write.
## Move an event
**Same UID, same filename, new times.** A new UID creates a second event and leaves the first in place,
which is the most common way this goes wrong.
## Delete
```bash
# fetch the current copy, so nothing else in it is lost
curl -s -u "$AUTH" "$OFFICER_API_URL/dav/1/personal/$UID.ics" > /tmp/ev.ics
# then PUT a version with new DTSTART/DTEND and SEQUENCE bumped by one
```
Bump `SEQUENCE` (add `SEQUENCE:1`, or increment what is there). Phones use it to tell an update from a
duplicate. A successful update answers **204**, not 201 — 201 means you created something new, so check
your filename.
## Delete an event, or a contact
```bash
curl -s -o /dev/null -w '%{http_code}\n' -u "$AUTH" -X DELETE "$OFFICER_API_URL/dav/1/personal/$UID.ics"
# 200
```
**Find the UID by reading first — never guess.** The file is normally `<UID>.ics`, and if that 404s, list
the collection and match on href:
```bash
curl -s -u "$AUTH" -X PROPFIND -H 'Depth: 1' "$OFFICER_API_URL/dav/1/personal/" | grep -o '<D:href>[^<]*'
curl -s "${OFFICER[@]}" -X DELETE "$OFFICER_API_URL/api/caldav/_officer/item" \
-d '{"href":"/dav/1/personal/….ics"}'
```
**Confirm before deleting when the match is not exact.** "Cancel dinner on Saturday" with one dinner on
Saturday is unambiguous — do it. Two dinners, or a recurring one, is a question: deleting the wrong event
cannot be undone from here, and the owner will discover it when someone is stood up.
Saturday is unambiguous — do it. Two dinners, or a recurring one, is a question: this cannot be undone
from here, and the owner discovers it when somebody is stood up.
Deleting one occurrence of a REPEATING event is not a DELETE — it needs an EXDATE added to the series.
If that is what they meant, say so rather than removing every occurrence.
Deleting one occurrence of a REPEATING event is not a delete — it needs an EXDATE on the series. Say so
rather than removing every occurrence.
## Add or remove a contact
## What this API deliberately cannot do
Same shape, `.vcf` in the addressbook collection.
It writes ordinary events and ordinary cards. **Recurrence rules, alarms, attendees, EXDATEs and photos
are not in it** — not an oversight, but the same rule that makes a PATCH safe: a field the screens cannot
show is a field an editor should not invent.
```bash
UID="officer-$(date +%s)-$RANDOM"
printf "BEGIN:VCARD\r\nVERSION:3.0\r\nUID:$UID\r\nFN:Peter Griffin\r\nN:Griffin;Peter;;;\r\nTEL;TYPE=CELL:+351912345678\r\nEMAIL;TYPE=INTERNET:peter@quahog.example\r\nEND:VCARD\r\n" \
| curl -s -o /dev/null -w '%{http_code}\n' -u "$AUTH" -X PUT \
-H 'Content-Type: text/vcard; charset=utf-8' --data-binary @- \
"$OFFICER_API_URL/dav/1/contacts/$UID.vcf"
```
`FN` is what shows on a phone and is REQUIRED. `N` is `Family;Given;Middle;Prefix;Suffix` — fill what you
know and leave the rest empty rather than omitting the line. Read contacts back with
`_officer/contacts?collection=…`, which returns `fullName`, `emails` and `phones` already parsed.
When the owner genuinely needs one, the DAV door is still there — HTTP Basic, their email as the
username and `$OFFICER_AGENT_KEY` as the password, PUT the whole `.ics` to its href. Read the file first
with `_officer/item?href=…`, change what you must, and put it back with the same UID and the same
filename. **Bump `SEQUENCE`** so a phone reads an update rather than a duplicate. If you are doing this,
say so — it is the part where a mistake is silent.
## Confirm in one line, in their words
"Added — Dinner with my wife, Saturday 29 August, 20:00, Cervejaria Ramiro." Local time, the name they
used, and where. Not the UID, not the UTC, not the HTTP status.
used, and where. Not the href, not the UTC, not the HTTP status.
If a write fails, say what failed and stop. **Never retry a PUT with a new UID** — the usual cause of a
failure is that the first one partly worked, and a retry leaves two.
If a write fails, say what failed and stop. **Never retry a create after a failure** — the usual cause is
that the first one partly worked, and a retry leaves two.