calendar-mgmt

name

calendar-mgmt

description

Google Calendar integration for end-user schedule management at runtime. Use when the user wants to view, create, update, or delete calendar events, or get a week summary ("show my schedule", "book a meeting tomorrow at 3pm", "what's on my calendar this week"). MVP supports Google Calendar API (OAuth2). On first use, guide Google Cloud OAuth setup, collect client_secret via hidden shell prompt, run setup.py --oauth, and store tokens in ~/.libragent/calendar_config.json. Not for LibrAgent agent cron automation (schedule / session-schedule). Triggers on: "일정 보여줘", "캘린더 확인", "미팅 예약", "show my calendar", "schedule a meeting".

Calendar Management

Manage the user's Google Calendar from LibrAgent — read and write events, summarize the week.

This is an end-user daily work skill (like email-integration, telegram-cli, x-cli). It is not for LibrAgent internal development or agent-only cron tasks.

Not This Skill

Skill	Use for
schedule / session-schedule	Wake an assistant on a cron (automation harness)
email-integration	Mail read/send (separate OAuth; IMAP, not Gmail API)
recruit / boost	Create or strengthen assistant configurations

CalDAV (Nextcloud, Apple, Fastmail) is planned for a later release. MVP is Google Calendar API only.

Path conventions

Paths are relative to this skill's Base Directory. Replace <skill-base-dir> with its absolute path in commands.

Security (mandatory)

• NEVER ask for client_secret, access tokens, or refresh tokens in chat
• NEVER display or repeat ~/.libragent/calendar_config.json
• Collect client_secret only via a single hidden shell prompt (requireUserInput=true, inputType=password), then pass --client-secret-env LIBRAGENT_GOOGLE_CLIENT_SECRET
• If the user pastes a secret in chat, do not echo it — run setup immediately

Prerequisites

pip install google-auth google-auth-oauthlib google-api-python-client

On Linux/macOS use pip3 if pip is unavailable.

Workflow

1. Detect config

python "<skill-base-dir>/scripts/validate_config.py"

Exit code	Meaning	Next step
0	Connected	Step 3
1	Not configured	Step 2
2	Incomplete / expired / corrupt	Step 2 (see action in JSON)

2. Setup (first time or re-auth)

See references/google-setup.md for Google Cloud Console steps and references/setup-flow.md for the LibrAgent hidden-prompt pattern.

Summary:

1. User creates a Desktop OAuth client in Google Cloud (Calendar API enabled).
2. Collect client_id in chat (not secret).
3. Hidden prompt → set LIBRAGENT_GOOGLE_CLIENT_SECRET.
4. Run OAuth:

python "<skill-base-dir>/scripts/setup.py" \
  --client-id "YOUR_CLIENT_ID.apps.googleusercontent.com" \
  --client-secret-env LIBRAGENT_GOOGLE_CLIENT_SECRET \
  --oauth

Re-auth only (credentials already saved):

python "<skill-base-dir>/scripts/setup.py" --oauth

Reset and reconnect:

python "<skill-base-dir>/scripts/setup.py" \
  --reset \
  --client-id "..." \
  --client-secret-env LIBRAGENT_GOOGLE_CLIENT_SECRET \
  --oauth

A browser window opens for Google consent. Tokens persist under ~/.libragent/calendar_config.json.

3. Dispatch action

Classify the request and call calendar_cli.py:

Action	When	Command
week_summary	"이번 주 일정", "my week"	--action week_summary [--timezone Asia/Seoul]
list_events	Range listing	--action list_events --from ISO --to ISO [--limit N]
get_event	One event by ID	--action get_event --event-id ID
create_event	Book / schedule	--action create_event --title T --start ISO --end ISO [--location L] [--description D] [--attendees [e-mail],[e-mail]]
update_event	Reschedule / edit	--action update_event --event-id ID [--title] [--start] [--end] ...
delete_event	Cancel	--action delete_event --event-id ID

Use RFC 3339 datetimes (e.g. 2026-06-12T15:00:00+09:00). For all-day events add --all-day and use YYYY-MM-DD dates.

Examples: references/request-patterns.md.

Before create/update/delete: confirm title, time, and timezone with the user when the request is ambiguous.

4. Present results

Format for humans per references/output-format.md. Errors: references/error-handling.md.

Config shape

{
  "provider": "google",
  "google": {
    "client_id": "...",
    "client_secret": "...",
    "tokens": { }
  },
  "caldav": null
}

caldav is reserved for a future release.

Guidelines

• User calendar, not agent cron — distinguish from schedule skill.
• OAuth is multi-step — similar friction to telegram-cli, not email-integration app passwords.
• No Gmail API synergy in v1 — email uses IMAP; cross-skill "mail → event" uses agent reasoning, not shared tokens.
• Confirm destructive actions — delete and attendee-affecting updates.
• Timezone explicit — ask or infer user timezone for week_summary and new events.

Builtin Tools

Step	Tool
Validate config	workspace__runCommand → validate_config.py
Setup / OAuth	workspace__runCommand → setup.py
Calendar ops	workspace__runCommand → calendar_cli.py
Open OAuth help URL	browser (optional, user-facing docs only)

References

• google-setup.md — Google Cloud OAuth client setup
• setup-flow.md — hidden prompt + setup commands
• request-patterns.md — natural language → actions
• output-format.md — presentation guidelines
• error-handling.md — recovery steps
• caldav-setup.md — future CalDAV (not in MVP)