Google Calendar

Script Reference

All operations use a single CLI script that returns JSON:

• Success: { "ok": true, "data": ... }
• Failure: { "ok": false, "error": "..." }

Usage Examples

bashCopy code
# List events in a date range
bun scripts/gcal.ts list --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-22T00:00:00Z"

# Get full details of a specific event
bun scripts/gcal.ts get --event-id "abc123"

# Create a new event (gates on assistant ui confirm)
bun scripts/gcal.ts create --summary "Team Meeting" --start "2024-01-15T09:00:00-05:00" --end "2024-01-15T10:00:00-05:00" --timezone "America/New_York"

# Check availability for a day
bun scripts/gcal.ts availability --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-15T23:59:59Z"

# RSVP to an event invitation
bun scripts/gcal.ts rsvp --event-id "abc123" --response accepted

# Target a specific connected account (see "Multiple Accounts" below)
bun scripts/gcal.ts list --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-22T00:00:00Z" --account "work@example.com"

Every subcommand accepts --account <email> to select which connected Google account the request runs against. When omitted, the request runs against a single account chosen automatically — safe only when exactly one Google account is connected. Each JSON envelope echoes the queried account in an account field when it is reported by the OAuth layer, so an empty result is self-describing (e.g. No events found in the specified time range for work@example.com.).

Connection Setup

1. Check connection health first. Run assistant oauth status google. This checks whether the user's Google account is connected and the token is valid. Google Calendar shares the same OAuth connection as Gmail — if the user already connected Gmail, calendar access is included.
   • If the status output shows more than one active connection, you MUST pass --account <email> on every scripts/gcal.ts invocation, matching the calendar the user is asking about. When the user references a calendar by name or company (e.g. "my Acme calendar"), map it to the connected account email before querying. Omitting --account with multiple connections silently queries one arbitrary account — an empty or partial result then looks like a genuinely free calendar when it is really the wrong account. Confirm the account field in each response matches the account you intended.
2. If no connection is found or the status check fails: Load the vellum-oauth-integrations skill. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.

Scheduling Playbook

When the user wants to schedule something:

1. Always check availability first before proposing times. Use bun scripts/gcal.ts availability to find free slots.
2. Propose 2-3 available time options to the user.
3. Once the user picks a time, create the event with bun scripts/gcal.ts create.
4. If adding other attendees, mention that they'll receive an invitation email.

Date & Time Handling

• Use ISO 8601 format for dates and times (e.g., 2024-01-15T09:00:00-05:00).
• For all-day events, use date-only format (e.g., 2024-01-15).
• Always ask the user for their timezone if it's not already known from context or their profile.
• When listing events, display times in the user's local timezone.

Confidence & Safety

Create and RSVP are medium-risk operations:

• Create: The create subcommand gates on assistant ui confirm — it presents a confirmation dialog to the user and only proceeds if approved. Pass --skip-confirm when the user has already given explicit confirmation in the conversation.
• RSVP: The rsvp subcommand gates on assistant ui confirm — it presents a confirmation dialog showing the event, current status, and new response. Pass --skip-confirm when the user has already given explicit confirmation in the conversation.

Error Recovery

When a calendar script fails with a token or authorization error:

1. Try to reconnect silently. Run assistant oauth ping google. This often resolves expired tokens automatically.
2. If reconnection fails, go straight to setup. Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Google Calendar needs to be reconnected - let me set that up") and immediately load the vellum-oauth-integrations skill. The user came to you to get something done, not to troubleshoot - make it seamless.
3. Never try alternative approaches. Don't use curl, browser automation, or any workaround. If the scripts can't do it, the reconnection flow is the answer.
4. Never expose error details. The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.