feat: agentic flows, error handling, API robustness, search, profile, event types, reschedule & more

[dhairyashiil]

Summary

Adds guided cancellation, reschedule, and confirm/decline flows to the chat agent, a comprehensive error handling & API robustness overhaul, booking search enhancement with attendee/date filtering, an "Am I Free?" availability flow, a profile management flow with Redis cache sync, an event type CRUD flow with expanded schemas, no-show/unlink account flows, a full agentic reschedule flow with slot exclusion and auto-confirmation, eliminates the keyword-based tool gating system entirely, adds exponential backoff retry logic with AbortSignal timeouts to all Cal.com API calls, gates agentic (AI-powered) features behind the Cal.com Organizations plan, and adds a get_event_type tool for fetching single event types — across 7 files (agent.ts, bot.ts, client.ts, types.ts, slack.ts, user-linking.ts, callback/route.ts).

Cancel booking flow

1. client.ts — cancelBooking now accepts an optional cancelSubsequentBookings param, forwarded to the Cal.com API for recurring booking cancellation.
2. agent.ts — system prompt — New ## Cancelling a Booking section with a 2-step flow (identify → confirm+reason), fast-path for clear intent, recurring booking handling, and batch cancellation capped at 3 per turn.
3. agent.ts — cancel_booking tool — Fetches booking details via getBooking before cancelling, returns enriched response (title, start, end, attendees), adds cancelSubsequentBookings schema param.
4. agent.ts — list_bookings tool — Adds eventType (id/title/slug) and description to response.
5. agent.ts — get_booking tool — Same enrichment as list_bookings.

Reschedule booking flow

6. agent.ts — system prompt — New ## Rescheduling a Booking section (~70 lines) with 4-step flow: identify booking → determine new time → check availability (mandatory, with bookingUidToReschedule) → confirm and reschedule. Includes fast-path, recurring booking handling (single occurrence only), and rescheduledBy auto-confirmation guidance.
7. agent.ts — check_availability tool — Added optional bookingUidToReschedule param to Zod schema; passed through to getAvailableSlots() in both primary and extended (no-slots fallback) calls.
8. agent.ts — check_availability_public tool — Same bookingUidToReschedule param added; passed through to getAvailableSlotsPublic() in both primary and extended calls.
9. client.ts — GetPublicSlotsParams — Added bookingUidToReschedule?: string; wired into query string in getAvailableSlotsPublic().
10. agent.ts — reschedule_booking tool — Enhanced: fetches original booking via getBooking before rescheduling (returns previousStart/previousEnd + newStart/newEnd + attendees), adds rescheduledBy param for auto-confirmation on confirmation-required event types. Description updated.
11. types.ts — CalcomBooking — Added recurringBookingUid: string | null to detect recurring bookings.
12. agent.ts — list_bookings + get_booking responses — Now surface recurringBookingUid in each booking object.
13. agent.ts — CRITICAL RULES — Added rule 11: "NEVER call reschedule_booking without first checking availability. Always pass bookingUidToReschedule."

Confirm/decline booking flow

14. agent.ts — system prompt — New ## Confirming or Declining a Booking section with the same patterns: 2-step flow (identify pending → confirm/decline), fast-path, batch cap at 3, and post-action guidance.
15. agent.ts — confirm_booking tool — Fetches booking details via getBooking before confirming, returns enriched response with start/end/attendees.
16. agent.ts — decline_booking tool — Same enrichment, plus returns reason in response.
17. agent.ts — Behavior section — Replaced the old confirm/decline one-liner with a reference to the new dedicated section.

Error handling & API robustness

Part A — Fix misleading error messages:
18. bot.ts — Added friendlyCalcomError helper that maps CalcomApiError status codes (400/401/403/404/409/422/429/5xx) to user-friendly messages.
19. bot.ts — CalcomApiError branch in withBotErrorHandling now runs after getCustomErrorMessage, so callers (e.g. the booking modal) can provide context-specific messages first. Previously CalcomApiError was caught before getCustomErrorMessage, making context-aware handlers like friendlyCalcomError(err, "booking") dead code.
20. bot.ts — Softened Slack auth error message: now says "I'm having trouble connecting to Slack" instead of the alarming "token has expired or been revoked".
21. slack.ts — Added isSlackAuthError guard to /cal slash command and retry_response action handlers (previously missing, causing false "token expired" messages).
22. slack.ts — Sanitized confirm_booking error: no longer exposes raw API error messages; shows status-specific messages (409 → "slot no longer available", 422 → "details incomplete").
23. slack.ts — App Home catch-all now only suggests "reconnect" on 401/403; otherwise shows "Could not load bookings. Please try again later."

Part B — Fix API schema mismatches:
24. client.ts — Fixed getAvailableSlots to use cal-api-version: 2024-09-04 (was using default 2024-08-13; /v2/slots endpoint requires 2024-09-04).
25. types.ts + agent.ts — Renamed responses → bookingFieldsResponses to match the OpenAPI spec. Removed phantom notes field from CreateBookingInput and CreatePublicBookingInput (notes should go via bookingFieldsResponses.notes).
26. client.ts — Added rescheduledBy param to rescheduleBooking for auto-confirm when rescheduler is the host.
27. client.ts — Added bookingUidToReschedule to GetSlotsParams to exclude the current booking from busy-time calculations during reschedule.

Part C — Structural improvements:
28. bot.ts + slack.ts — All 6 getCustomErrorMessage callbacks now check lastStreamErrorRef.current instanceof CalcomApiError and return friendlyCalcomError(...) messages, so stream errors from Cal.com API calls surface specific messages rather than generic fallbacks.

Booking search enhancement

29. client.ts — Expanded GetBookingsParams with attendeeEmail, attendeeName, afterStart, beforeEnd, sortStart and wired them through as query params in getBookings().
30. agent.ts — list_bookings tool — Added all 5 new optional params to the Zod schema (attendeeEmail, attendeeName, afterStart, beforeEnd, sortStart) and passes them to getBookings().
31. agent.ts — tool description — Updated to mention attendee/date filtering and notes that attendee filters only match attendees, not hosts.
32. agent.ts — system prompt — New FINDING PAST MEETINGS WITH SOMEONE section with attendee/host fallback strategy: if attendee filters return no results, does an unfiltered call and scans the hosts field.
33. agent.ts — list_bookings + get_booking responses — Now include hosts array (name + email) alongside attendees, enabling the agent to find meetings where the person was the host.

"Am I Free?" availability flow

34. agent.ts — system prompt — New ## Checking Your Availability / "Am I Free?" section with a 3-step flow: determine time range → fetch bookings via list_bookings with afterStart/beforeEnd → answer the question. Covers specific-time checks, daily schedules, weekly overviews, and edge cases (past dates, duration-based gaps, "block off" requests).
35. agent.ts — check_busy_times tool description — Updated to note credential limitations and steer the agent toward list_bookings for availability checks.
36. agent.ts — CRITICAL RULES — Added rule 10: "For 'am I free?' questions, use list_bookings with afterStart/beforeEnd date filters — do NOT use check_busy_times."

Profile management flow

37. agent.ts — system prompt — New ## Profile Management section with guidance for viewing profile (use cached "Your Account" data, only call get_my_profile for full details), updating profile (confirm before changes, resolve timezone abbreviations to IANA, warn about email verification), field reference list, and fast-path for clear-intent updates.
38. agent.ts — update_profile tool — After a successful updateMe() call, syncs changed email and timeZone back to the LinkedUser in Redis via linkUser(). This fixes a stale cache bug where the system prompt's "Your Account" section and all subsequent timezone conversions would use outdated values after a profile update.
39. agent.ts — imports — Added linkUser to imports from user-linking.
40. agent.ts — get_my_profile description — Updated to steer the agent toward using cached system prompt data for basic info (email, username, timezone) and only calling the API for full profile fields (bio, time format, week start, locale).
41. agent.ts — update_profile description — Updated to require user confirmation before calling and to use IANA timezone strings. Notes that email changes require verification.

Event type CRUD flow

42. agent.ts — system prompt — New ## Managing Event Types section with guidance for creating (auto-generate slug from title, show booking URL after creation), updating (identify → confirm → update), deleting (always confirm first, warn irreversible), listing (show booking URLs), and common requests (hide/unhide, buffers, notice, slot intervals). Redirects advanced settings to the web UI.
43. agent.ts — CRITICAL RULES — Relaxed rule ci: add 6 new workflows, Blacksmith runners, and CI speed optimizations #9 from "NEVER call unless explicitly asked" to "NEVER call during a booking flow or unless explicitly asked to manage an event type. For delete, ALWAYS confirm first." Keeps the safety guard for booking flows without making the tools sound forbidden.
44. agent.ts — create_event_type tool — Added minimumBookingNotice, beforeEventBuffer, afterEventBuffer, slotInterval, scheduleId to Zod schema. Updated description to mention buffers/notice/intervals.
45. agent.ts — update_event_type tool — Same 5 new fields added to Zod schema. Execute function refactored to use { eventTypeId, ...rest } destructuring. Updated description to list all configurable fields.
46. agent.ts — delete_event_type tool — Description updated to "This is irreversible -- always confirm with the user first."
47. types.ts — Added minimumBookingNotice, beforeEventBuffer, afterEventBuffer, slotInterval, scheduleId to both CreateEventTypeInput and UpdateEventTypeInput interfaces.
48. agent.ts — list_event_types tool — Now fetches LinkedUser in parallel with the access token and includes bookingUrl ({CALCOM_APP_URL}/{username}/{slug}) in each event type's response.

No-show & unlink account flows

49. client.ts — markNoShow — Now accepts optional host (boolean) and attendees (array of { email, absent }) parameters and passes them in the request body. Previously sent an empty POST body which the API likely ignored.
50. agent.ts — mark_no_show tool — Expanded schema with host (boolean, mark host as absent) and attendeeEmails (string array, emails of absent attendees). Execute function maps emails to { email, absent: true } objects before calling client. Description updated to explain host vs attendee no-show marking.
51. agent.ts — system prompt — New MARKING NO-SHOWS section: identify past booking → ask who was absent (host or attendee, skip if clear from context) → call mark_no_show → confirm. Notes that no-shows only work for past bookings.
52. agent.ts — unlink_account tool description — Updated from bare "Unlink the user's Cal.com account." to include consequences (removes OAuth connection, re-auth required) and "always confirm before calling".
53. agent.ts — system prompt — New UNLINKING ACCOUNT section: always confirm with explicit warning about consequences → on "yes" call unlink_account → confirm disconnection and explain how to reconnect.

Eliminate keyword-based tool gating

54. agent.ts — Deleted CORE_TOOL_NAMES, ADMIN_KEYWORDS, detectToolSet(), and filterTools() entirely. All 28+ tools are now always exposed to the model. The system prompt's critical rules are the guardrail against misuse, not keyword filtering.
55. agent.ts — Removed toolSet from AgentStreamOptions interface. runAgentStream now directly uses createCalTools() output without filtering.
56. bot.ts — Removed all detectToolSet() calls and toolSet arguments from the 3 runAgentStream call sites (telegram freeform, mention handler, thread follow-up). Removed detectToolSet import.

API retry and timeouts

57. client.ts — Added constants: FETCH_TIMEOUT_MS (10s), MAX_RETRIES (2 = 3 total attempts), RETRY_BASE_MS (500ms), RETRY_MULTIPLIER (3), RETRYABLE_STATUS_CODES (500, 502, 503, 504).
58. client.ts — Added fetchWithRetry() helper that wraps fetch with AbortSignal.timeout(FETCH_TIMEOUT_MS), retries on server errors (5xx) and network/timeout errors with exponential backoff (500ms → 1500ms), and throws CalcomApiError with code "FETCH_RETRY_EXHAUSTED" after all attempts fail. Added sleep() helper.
59. client.ts — Updated calcomFetch to accept an optional retries parameter (default MAX_RETRIES) and use fetchWithRetry instead of raw fetch.
60. client.ts — All mutating calls (POST/PATCH/DELETE) now pass retries: 0 — timeout protection only, no retry. This includes: createBooking, createBookingPublic, addBookingAttendee, cancelBooking, rescheduleBooking, updateMe, createSchedule, updateSchedule, deleteSchedule, confirmBooking, declineBooking, createEventType, updateEventType, deleteEventType, markNoShow. Only GET calls use full retry.
61. client.ts — Replaced raw fetch() with fetchWithRetry() in 3 public (unauthenticated) functions: getAvailableSlotsPublic (full retry), createBookingPublic (retries: 0), getEventTypesByUsername (full retry).

get_event_type tool

62. client.ts — Fixed getEventType to normalize the length field (raw.length ?? raw.lengthInMinutes ?? 0), matching the existing getEventTypes behavior.
63. agent.ts — Added get_event_type tool definition (import, Zod schema, execute function) for fetching a single event type by ID. Returns bookingFields, duration, description, bookingUrl, etc. Added system prompt guidance in CUSTOM BOOKING FIELDS and UPDATING AN EVENT TYPE sections.

Org plan agentic gating

64. user-linking.ts — Added calcomOrganizationId and calcomOrgIsPlatform to LinkedUser interface. Added isOrgPlanUser() helper that returns true when calcomOrganizationId != null && calcomOrgIsPlatform === false. Org metadata is re-synced via /v2/me on every token refresh (non-fatal on failure).
65. callback/route.ts — Expanded local CalcomMe to capture organizationId and organization.isPlatform at OAuth link time.
66. client.ts — Updated shared CalcomMe interface with organizationId and organization fields.
67. bot.ts — Added org plan check in runAgentHandler() after token validation — covers all agentic paths (Slack mentions, Telegram DMs/mentions, thread follow-ups). After getValidAccessToken, re-reads LinkedUser from Redis so freshly synced org data is used. Slack upgrade message is wrapped in withSlackToken to avoid not_authed errors.
68. handlers/slack.ts — Gated the two direct runAgentStream calls that bypass runAgentHandler: /cal book @user fallback (no modal) and /cal <natural language> default case. The default case correctly shows the OAuth link prompt for unlinked users instead of conflating with the upgrade message.

Gating logic (from /v2/me response):

organizationId	isPlatform	Agentic?
null	—	No
non-null	true	No (Platform/API tier)
non-null	false	Yes (Org plan)

Code quality improvements

69. agent.ts + user-linking.ts — Extracted named constants replacing magic numbers: MAX_HISTORY_MESSAGES, MAX_AGENT_STEPS, MAX_SLOTS_RETURNED, MAX_NEXT_AVAILABLE_SLOTS, EXTENDED_SEARCH_DAYS, MS_PER_DAY, LINKED_USER_TTL_SECONDS, BOOKING_FLOW_TTL_SECONDS, TOOL_CONTEXT_TTL_SECONDS, REFRESH_LOCK_WAIT_MS, REFRESH_LOCK_TTL_SECONDS.

Other changes (from prior pushes)

• isAIToolCallError now catches "tool choice is none" errors
• onError broadened to store all stream errors in onErrorRef (not just rate-limit and tool-call); preserves original Error instances for instanceof checks
• Custom booking fields prompt: bookingFieldsResponses must never be empty {} for required fields; default "Notes" slug is "notes"
• bookingFieldsResponses type tightened from Record<string, unknown> to Record<string, string>

Updates since last revision

Addressed review comments in the latest commit:

1. Disabled retries for ALL mutating API calls (client.ts): Previously only createBooking, createBookingPublic, and addBookingAttendee had retries: 0. Now all POST/PATCH/DELETE calls (cancel, reschedule, confirm, decline, updateMe, create/update/deleteSchedule, create/update/deleteEventType, markNoShow) also pass retries: 0. A timed-out cancel or reschedule will no longer silently retry and potentially create duplicates.

2. Reordered error handlers in withBotErrorHandling (bot.ts): Moved the CalcomApiError catch block after getCustomErrorMessage. Previously, a 409 booking conflict in the Slack modal was caught by the generic CalcomApiError handler before the modal's context-aware friendlyCalcomError(err, "booking") could run — that handler was effectively dead code. Now callers get first crack at providing context-specific messages.

3. Re-read linked user after token refresh (bot.ts): Changed const linked to let linked in runAgentHandler. After getValidAccessToken (which may have refreshed the token and synced org data via /v2/me), the linked user is re-read from Redis so the org-plan gate uses fresh data instead of the stale snapshot from before the refresh.

Review & Testing Checklist for Human

• Org plan gating correctness: Verify that /v2/me returns organizationId and organization.isPlatform with the cal-api-version: 2024-08-13 header. Test with a free user (should see upgrade message on @mention / /cal how are you), an Org plan user (should get AI response), and a Platform API-tier user (should see upgrade message). Verify all three can still use /cal bookings, /cal help, /cal availability.
• Existing linked users post-deploy: Users linked before this feature have undefined for org fields in Redis and will be treated as non-org (blocked from agentic) until their next token refresh (roughly hourly for active users) or re-link. Decide if this grace period is acceptable or if a migration is needed.
• Extra /v2/me call on every token refresh (user-linking.ts): Adds one API call per token refresh (~1/hour per active user). Non-fatal on failure. Confirm this overhead is acceptable.
• responses → bookingFieldsResponses rename is the highest-risk change. The OpenAPI spec says bookingFieldsResponses, but if the live API silently accepts responses as an alias and does NOT accept bookingFieldsResponses, all bookings with custom fields will break. Test a real booking with custom fields (including the notes field) end-to-end to confirm the API accepts bookingFieldsResponses.
• All 28+ tools always exposed (keyword gating removed). Verify the model doesn't call admin tools (schedules, no-show, unlink, etc.) inappropriately during simple booking conversations. The system prompt's critical rules are the only guardrail now.
• Retry logic: ALL mutating calls now have retries: 0. Verify that slow-but-successful API responses (>10s) don't get prematurely aborted by the AbortSignal.timeout(10_000). If Cal.com cancel/reschedule endpoints sometimes take >10s, users will see timeout errors. Previously cancel/reschedule/confirm/decline retried on timeout — now they don't.
• Error handler reorder in withBotErrorHandling: Verify that getCustomErrorMessage callbacks in the Slack modal flow (friendlyCalcomError(err, "booking")) now correctly handle 409 conflicts with the context-aware "booking" message, and that generic CalcomApiError still works as a fallback for paths without a custom handler.
• recurringBookingUid on CalcomBooking — Verify the API returns this field on booking objects. If not, recurring booking detection in reschedule prompts won't fire.
• bookingUidToReschedule query param — Verify the /v2/slots API accepts this parameter. If silently ignored, the original time slot appears as "busy" during reschedule.
• rescheduledBy in rescheduleBooking — Verify the API accepts this in the POST /v2/bookings/{uid}/reschedule body for auto-confirmation.
• markNoShow request body — POST /v2/bookings/{uid}/mark-absent now receives { host, attendees }. Verify the API accepts this shape.
• Redis cache sync after profile update — After changing timezone via the bot, verify the system prompt's "Your Account" reflects the new timezone on the next message.
• Test reschedule, cancel, confirm/decline flows end-to-end in Slack — including fast-path, recurring, and batch scenarios.
• Test error handling — Trigger a Cal.com 400 (should not say "token expired"), 409 on confirm_booking (should say "slot no longer available"), App Home when API is down (should say "try again later" not "reconnect").

Notes

• Stacked on PR feat: simplify agent booking flow — pre-resolution, tool filtering, Redis persistence #32 (devin/1773320873-smart-mention-booking-flow)
• Link to Devin Session
• Requested by: @dhairyashiil

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[vercel]

Deployment failed with the following error:

You don't have permission to create a Preview Deployment for this Vercel project: cal-companion-chat.

View Documentation: https://vercel.com/docs/accounts/team-members-and-roles

[cubic-dev-ai]

2 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/chat/lib/handlers/slack.ts">

<violation number="1" location="apps/chat/lib/handlers/slack.ts:944">
P2: This booking-specific Cal.com error mapping never runs because `withBotErrorHandling` handles `CalcomApiError` before `getCustomErrorMessage`. As written, 409 booking conflicts still fall back to the generic Cal.com conflict message instead of the new slot-unavailable text.</violation>
</file>

<file name="apps/chat/lib/calcom/client.ts">

<violation number="1" location="apps/chat/lib/calcom/client.ts:84">
P1: Default retries now reissue mutating Cal.com requests, so timeouts/5xxs can duplicate creates or replay cancel/reschedule actions.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

3 issues found across 6 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/chat/lib/bot.ts">

<violation number="1" location="apps/chat/lib/bot.ts:840">
P2: Re-read the linked user after token refresh before enforcing the org-plan gate.</violation>
</file>

<file name="apps/chat/lib/user-linking.ts">

<violation number="1" location="apps/chat/lib/user-linking.ts:218">
P1: Persist the refreshed tokens before calling `getMe()`. Doing another retried API call inside the refresh lock can make concurrent requests return `null` or trigger a second refresh.</violation>
</file>

<file name="apps/chat/lib/handlers/slack.ts">

<violation number="1" location="apps/chat/lib/handlers/slack.ts:525">
P1: This org-plan gate will falsely block already-linked organizations users whose cached Redis record predates the new org fields.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/chat/lib/calcom/client.ts">

<violation number="1" location="apps/chat/lib/calcom/client.ts:325">
P2: Passing `0` here disables the new retry/backoff logic, so transient Cal.com 5xx or timeout failures still break this mutation after one attempt.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}