google_calendar

An authentication failure: a Calendar API call came back 401/403 — Google rejected the access token the runtime resolved (revoked before its stored expiry, or scoped too narrowly for the call). Retrying the SAME token does not help, but replaying the call recovers without any app-owned escalation: catch it in a converter that signals replay.interrupted — the re-run asks get_access_token afresh, the runtime refreshes the credential once its stored lifetime passes, and a credential the runtime cannot refresh parks the run on a prelude.oauth.authorize escalation (the admin console's re-authorization prompt) instead of failing. message carries the status and the server's body.

A Calendar API call failed for a non-authentication reason: the endpoint returned a non-2xx status that is not 401/403 (a bad request, a not-found calendar, a quota or server error). message carries the status and the server's body so the model can read what went wrong and adjust. Distinct from auth_error so a program can tell a request the service faulted on (back off and replay as-is) from a token Google rejected (the replay's re-resolution is what fixes it).

A watch was wired with a poll interval WIDER than its lead window, so the gap (T+lead, T+poll) between one poll's window and the next is covered by no window and events starting there would be silently dropped. This is a program defect — a bad constant at the call site, not a runtime condition — and would be a panic if a Katari program could raise one; since it cannot, watch throws this at entry instead. message names both values. It is NOT a calendar_error (nothing failed at Google); fix the constants rather than composing a retry around it.

A calendar event trimmed to what an assistant needs: the id, the summary (title), start / end (an RFC3339 timestamp for a timed event, a date for an all-day one), and the html_link that opens it in a browser.

A timed event's moment: an RFC3339 instant (start.dateTime / end.dateTime), e.g. "2026-07-11T15:00:00+09:00".

An all-day event's moment: a bare YYYY-MM-DD date (start.date / end.date), with no time of day and no timezone.

Neither dateTime nor date was present — an unexpected event shape. The explicit stand-in for a genuinely absent moment, so downstream dispatches on the variant instead of guessing from a sentinel string.

Classify a Calendar start / end object into the moment sum at the ONE parse boundary: its dateTime (a timed instant) if present, else its date (an all-day date), else undated. Google nests the moment as one of dateTime / date, so this dispatch — not a "" sentinel test downstream — is where timed and all-day part ways.

Render a moment as the string the event carries for the model: a timed event's dateTime, an all-day event's date, or the empty string when the moment is genuinely absent (there is no instant to show — the only place a "" is honest, at the string boundary rather than as an internal sentinel).

Get a usable Google access token, served by provider for the extent of a continuation — the capability the tools require (with … get_access_token). Each ask resolves the provider's named credential through the runtime (oauth.token): the runtime returns the stored token while its recorded lifetime holds and refreshes it against the stored token endpoint once due, so no token bookkeeping lives in the program. The token is a string of private — it flows only toward a submission sink (the Bearer header). A credential that needs a human (never authorized, or refresh-dead) never throws: the ask PARKS the run on a prelude.oauth.authorize escalation and resumes once the browser flow completes. A transient resolution failure throws oauth.server_error at the provider.

Provide the Google credential for the extent of the continuation: use google_calendar.provider(), or provider(name = "…") to pick a non-default credential. It serves get_access_token by resolving name through the runtime's credentials core (oauth.token) on every ask — the runtime owns the token material, its cache and its refresh, so this provider holds no secret and keeps no state. name must be registered and authorized out of band (the README's setup: register the Google OAuth client, then log in via the admin console); an unauthorized credential parks the run on a prelude.oauth.authorize escalation rather than failing, and a transient token-resolution failure throws oauth.server_error.

The Authorization: Bearer <token> header every Calendar API call carries. The token is a string of private (the runtime-resolved credential); concatenation propagates the taint, and the header record is a private-capable submission sink, so the secret leaves only toward Google's server.

Classify a failed Calendar API response into the error sum, at the ONE boundary where the split is decided. A 401 or 403 is an authentication failure — Google rejected the resolved access token (revoked, or scoped too narrowly) — surfaced as auth_error, which a replay converter turns into a fresh token resolution (and, when the credential is refresh-dead, the runtime's re-authorization park). Every other non-2xx is an api_error. (403 is read as auth even though Google also returns it for quota exhaustion; the access-rejection reading is the one worth composing the re-resolution around, and a quota 403 that is replayed simply fails again.) context names the call for the message.

Format an epoch-millisecond instant as an RFC3339 UTC timestamp (YYYY-MM-DDTHH:MM:SSZ) — the shape Calendar's timeMin / timeMax require, produced from the epoch milliseconds time.now returns. The civil date is Howard Hinnant's civil_from_days algorithm (a closed-form, leap-rule-correct days -> year/month/day with no month-length tables), read in UTC; sub-second precision is dropped (the API does not need it). Assumes a non-negative instant (post-1970, which time.now always is) and a four-digit year (any realistic wall-clock instant). Pure Katari keeps the package sidecar-free; the algorithm is validated against Date.toISOString across the whole range.

Parse an RFC3339 timestamp back to an epoch-millisecond instant — the inverse of to_rfc3339, used by watch to place a Calendar event's start.dateTime on the same numeric line as its tick's epoch window. Reads the fixed-position civil fields (YYYY-MM-DDTHH:MM:SS) and folds them to days with Hinnant's days_from_civil (the exact inverse of to_rfc3339's civil_from_days), then applies the trailing zone: Z is UTC, and a ±HH:MM offset (always the last six characters Google emits for a timed event) is subtracted so the result is a true UTC instant regardless of the event's timezone — a string compare would be wrong, since 09:00+09:00 and 00:00Z are the same moment. Sub-second precision is ignored (it never affects a minute-or-coarser window). A malformed field degrades to 0 in the total-reader idiom, so a garbled timestamp sorts to the epoch rather than throwing.

Issue an authenticated GET to a Calendar API url and return its parsed JSON body. The one place the Bearer header, the 2xx check and the error classification live, shared by list_events and watch's pager. A non-2xx becomes classify_api_error(@context@, ...) (401/403 → auth_error, else api_error); context names the caller for the message.

Tool: list the upcoming events on a calendar. calendar_id is the calendar's id ("primary" for the user's own, or an address like "teamexample.com"); time_min@ / time_max bound the window as RFC3339 timestamps (e.g. "2026-07-11T00:00:00Z"); max_results caps how many come back. Returns the events trimmed to id / summary / start / end / link — small enough to feed straight back to the model.

Tool: create an event on a calendar. calendar_id is the target calendar ("primary" for the user's own); summary is the title; start / end are RFC3339 timestamps (e.g. "2026-07-11T15:00:00Z"); description is optional detail. Returns the created event (its id and the link to open it).

Deliver one event and record its (id, start) pair the INSTANT its deliver_to returns — the per-event dedup commit. Handled inside watch; the pair is looked up in the durable already_notified var (absent → deliver and append, present → skip), so a mid-tick failure never re-delivers an event already delivered in the same tick. Internal to watch; an app does not handle it.

Prune the dedup memory to keys — the (id, start) pairs of the current window — dropping events that have left it, so the memory stays bounded to one window. Performed once per tick before delivery. Internal to watch; an app does not handle it.

Watch a calendar for upcoming TIMED events and deliver each one, once per activation, as it enters the lead window — shaped like time.watch / discord.watch_messages so it composes under parallel [ … ]. Every poll_interval_milliseconds it lists the events whose START lies within lead_time_milliseconds ahead of the tick and calls deliver_to for each not yet notified. All-day events are NOT covered (they have no instant to place in the lead window); this watch is for timed events only.

Delivery is AT-LEAST-ONCE, exactly-once per (event id, start time) only WITHIN a single activation: an event whose start has not moved is delivered a single time while the watch keeps running, and an event whose start moved is a different pair, so it re-notifies. A crash-recovery restart resumes the durable dedup memory and does not re-notify; but a replay re-run (a replay.forever / replay.exponential around the watch re-invokes its continuation, giving a fresh activation whose memory starts empty) re-delivers every event still inside the lead window, and a deliver_to failure re-delivers the events after it in that tick on the next run. watch never resolves; deliver_to's effects E flow to the caller's handlers unchanged.

poll_interval_milliseconds must not exceed lead_time_milliseconds — a wider interval leaves the gap (T+lead, T+poll) covered by no window, silently dropping events that start there. That is a program defect, rejected at entry with watch_misconfigured (a panic in spirit; a Katari program cannot raise one).

No retry is built in — a poll failure (an http error, a rejected token, a deliver_to that throws) propagates and kills the watch, exactly as an uncaught failure in any callee does. Compose resilience by wrapping the watch in a replay provider (replay.forever with a converter that replays the transient blips AND auth_error — the re-run re-resolves the token, and a credential needing a human parks on the runtime's authorize escalation rather than failing). The first poll is one poll_interval in (a time.watch occurrence fires one interval after the start).

List every timed event whose START lies in the window [window_start, window_start + lead), across ALL result pages — watch's per-poll listing. Paginates on nextPageToken so a busy window is delivered in full rather than truncated at one page. The recursion depth is the number of pages in one poll (small and bounded — a single lead window rarely spans more than a page), not the daemon's lifetime, so it does not accumulate like a per-tick loop would. Internal to watch.

Fetch one page of the window listing, accumulate its deliverable events, and recurse on nextPageToken until Google stops sending one. page_token is null for the first page. Internal to watch's pager (list_window).

The timed events on one events.list page whose START lies in [window_start, window_start + lead) — the client-side re-filter that corrects the coarse server query. Dispatches each event's start moment: a timed instant is parsed (from_rfc3339) and kept only if it falls in the window; an all_day or undated event is dropped (the watch covers timed events only). Internal to watch.

Every event in a Calendar events.list reply, trimmed to event. A reply that carries no items array (an error shape the caller already branched away from, or an empty calendar) degrades to an empty list rather than throwing.

One Calendar event object as an event. Google nests the moment under start / end as either a dateTime (timed) or a date (all-day); read_moment classifies it and moment_text renders the string the model reads.