Calendar Agent¶
Thinklio Built-in Agent Specification Version 0.1 | March 2026
1. Purpose and Problem Statement¶
The Calendar Agent gives Thinklio read and write access to calendar systems. It answers questions about schedule and availability, creates and manages events, sends invitations, and surfaces upcoming commitments in a way that other agents (particularly Taskmaster and the Mail Agent) can act on.
It is a connective agent as much as a standalone one: its primary value is in feeding schedule context into the rest of the Thinklio ecosystem — knowing that a meeting with a key contact is tomorrow informs how the Mail Agent prioritises a related email, how Taskmaster orders tasks, and how the Rolodex pre-meeting briefing is framed.
Governance: The Calendar Agent follows the shared governance model defined in 00-governance-model.md. Creating events, sending invitations, and accepting on behalf of the user are all governed actions.
2. UI Structure¶
Chat Tab¶
The primary interface for intelligent calendar operations: - "What have I got on this week?" - "Schedule a 30-minute call with James Chen — find a time that works next week" - "When am I next free for two hours in the afternoon?" - "Create an event: Thinklio board review, Tuesday 10am, 90 minutes" - "What was the last time I had a meeting with the Cares Communities team?" - "Block out Friday afternoon — I need focus time"
Upcoming Tab¶
A structured list of upcoming events, sorted chronologically, with agent-generated context: - Event name, date/time, duration, location (physical or virtual) - Participants (linked to Rolodex where matched) - Preparation note: if the agent detects open tasks or recent interactions related to participants, it surfaces a brief contextual note ("You have an open item with Lavan Lawyers — consider raising it") - Booking status: confirmed, tentative, pending response
Schedule Tab¶
A full calendar view integrating events from connected calendar accounts and task due dates from Taskmaster. Day, week, and month views. Time zones shown where participants span multiple zones. Overlapping commitments highlighted.
Availability Tab¶
A view designed for scheduling: shows free/busy blocks for the user across a selected window, with options to share availability as a link or a text summary ("I'm free Tuesday 2–5pm and Thursday morning"). If the workspace has multi-user scheduling, shows combined availability for a set of participants.
3. Configuration¶
3.1 Admin Configuration¶
| Setting | Description |
|---|---|
| Connected calendar providers | Supported providers (Google Calendar, Microsoft 365, CalDAV) and authentication via Keeper |
| Default permission matrix | Default permission levels per action type for new users |
| Autonomous event creation constraints | Hard limits: max duration, required fields, permitted calendar accounts |
| External invite policy | Whether the agent may send calendar invitations to external (non-workspace) participants |
3.2 Permission Matrix (configurable at org → team → user)¶
| Action | Permission Level |
|---|---|
| Read calendar | read |
| Report availability | read |
| Create event (own calendar) | configurable |
| Create event (shared calendar) | configurable |
| Send invitation — internal | configurable |
| Send invitation — external | configurable |
| Accept invitation on behalf of user | configurable |
| Decline invitation on behalf of user | configurable |
| Block time / create focus blocks | configurable |
3.3 User Configuration¶
| Setting | Description |
|---|---|
| Connected accounts | Which calendar accounts the agent has access to |
| Working hours | Used when suggesting meeting times and determining availability |
| Buffer preferences | Minimum gap between meetings the agent should respect when scheduling |
| Focus time rules | Days or windows the agent should protect from meeting scheduling |
| Rolodex auto-log | Whether attended meetings are logged as Interactions in Rolodex |
| Default meeting duration | Used when a duration is not specified in a scheduling request |
| Default video link | Automatically appended to created events (Zoom, Teams, Meet link) |
4. Scheduling Intelligence¶
When asked to find a meeting time, the agent applies:
- User's working hours and focus time rules
- Buffer preferences between existing events
- Participant availability if the workspace supports multi-user scheduling or if the agent can query external availability (via calendar invites or availability links)
- Time zone awareness when participants are in different zones
- Preference for times earlier in the day when all else is equal (configurable)
The agent presents one or more suggested times with brief reasoning ("Tuesday at 2pm works for both of you and gives you 30 minutes after your morning block") and waits for confirmation before creating the event.
5. Agent Capabilities¶
| Capability | Description |
|---|---|
| Read schedule | Retrieve events within a time range |
| Report availability | Return free/busy blocks for a given window |
| Create event | Add an event to a calendar |
| Update event | Modify an existing event (time, title, participants, etc.) |
| Delete event | Remove an event |
| Send invitation | Invite participants to an event |
| Accept/decline invitation | Respond to an invitation on behalf of the user |
| Find meeting time | Suggest optimal times given participant constraints |
| Summarise schedule | Natural language summary of upcoming commitments |
| Log to Rolodex | Create an Interaction record for a past or upcoming meeting |
| Search events | Find past events by participant, keyword, or date range |
6. Inter-Agent Behaviour¶
- Keeper provides authenticated calendar account access via OAuth proxy
- Rolodex is queried to match meeting participants to Person records and to log meetings as Interactions
- Taskmaster is queried to overlay task due dates on the calendar view and to create tasks from meeting action items
- Mail Agent forwards detected meeting invitations from email to the Calendar Agent for processing
- Enquiry Agent can surface meeting-related context when an Item involves a known contact
7. Use Cases¶
UC-1: Weekly schedule overview¶
A user asks "what's my week looking like?" The agent returns a natural language summary: three confirmed meetings, one tentative, a focus block on Thursday afternoon, and a note that the Friday board call has two participants who haven't responded yet.
UC-2: Scheduling with availability awareness¶
A user asks the agent to find a 45-minute slot for a call with two colleagues next week. The agent checks availability across all three calendars, applies buffer preferences, and suggests two options with plain English reasoning. The user picks one and the agent creates the event and sends invitations.
UC-3: Pre-meeting context¶
The Upcoming tab shows a meeting with a Lavan Lawyers contact tomorrow. The agent surfaces: last interaction (a call two weeks ago), one open Taskmaster task linked to the matter, and a flag that the related Item has not been updated in five days.
UC-4: Focus time protection¶
A user asks "block my Thursday afternoon for deep work". The Calendar Agent creates a focus block event and sets it as busy. When the agent subsequently suggests meeting times, it respects the block unless the user explicitly overrides.
UC-5: Post-meeting logging¶
After a meeting ends, the Calendar Agent detects it has passed and (if auto-log is enabled) creates a Rolodex Interaction record for each known participant with the meeting title, duration, and date. The user can add notes via Rolodex chat.
8. Open Questions¶
- Multi-provider support (Google Calendar and Microsoft 365 simultaneously) is high value but adds OAuth complexity per provider. Is single-provider support sufficient for the initial release?
- External participant availability is only accessible if they share a free/busy URL or respond to a probe invitation. The agent should be clear about the limits of its availability knowledge rather than presenting uncertain data as confirmed.
- Meeting action item extraction (summarising a meeting and creating tasks from it) is a natural extension but requires meeting transcript or notes input. Should this be a Calendar Agent capability or a separate Transcription Agent?
- Recurring event management (modifying one instance vs. all future instances) is a known UX complexity. The initial spec should support basic recurring event creation; modification of recurring series should be treated as a phase-two capability.
Previous: Mail Agent | Next: Messenger Agent