slotlock 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,287 @@
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and semantic
 versioning.
 
+## 0.9.0 - 2026-11-11
+
+### Added
+
+- Each hold's payment is kept apart from the hold (new table `hold_payments`, under RLS, erased with
+  the tenant), so `slotlock_mark_hold_paid` with the same payment answers `replayed: true` however
+  the hold ended: confirmed in place or booked as an event. Before, a confirmed hold answered
+  `404 hold_not_found`, which `@slotlock/payments-stripe` with `refundRefused` refunded: a customer
+  reloading the return page, or Stripe redelivering a webhook, got a booked time refunded (found by
+  the security audit). The adapter now refunds only `hold_expired`, `payment_conflict` and
+  `payment_amount_mismatch`.
+- Three integration packages in `packages/` (RFC 0004 P3), each its own process with its own
+  schema and secrets, talking to Slotlock over its API:
+  - `@slotlock/sync` (C1, C4, T2): busy time from Google freeBusy, Microsoft getSchedule and
+    iCalendar URLs, recorded as each source's busy time; confirmed bookings written back to Google
+    and Microsoft calendars, times only. OAuth with PKCE, then a signed page where the tenant's person
+    chooses which calendar blocks which resource; tokens, URLs and keys sealed with AES-256-GCM. A
+    booking changed in the calendar is reported on the feed (`coverage.conflict`), never applied. A
+    provider's 429 or 503 is retried when it says, else with backoff; a feed cursor that expired
+    while the sync was down is recovered by reconciling each calendar with the bookings as they are.
+  - `@slotlock/notify` (C2): confirmations, moves, cancellations and reminders by Postmark,
+    Resend or SES, and Twilio SMS and WhatsApp, each send recorded under its key (change id,
+    channel, recipient) before it is made. Consent per channel; test tenants go to a capture inbox.
+    Recipients are kept only as digests, except an event's attendees, kept sealed until a day after
+    it ends so a cancellation reaches them.
+  - `@slotlock/payments-stripe` (C3, T2): a PaymentIntent read back from the tenant's own Stripe
+    account marks its hold paid, with the amount received; a payment for an expired hold is refused
+    and, if asked, refunded.
+  - Each runs as its own process (`slotlock-sync`, `slotlock-notify`, `slotlock-payments-stripe`,
+    each with `migrate` and `serve`), and `packages/integrations.Dockerfile` builds one image with
+    all three.
+- What integrations build on (RFC 0004 P3, D1's recommendation: core keeps primitives, packages
+  outside it send and sync). Feed type `reminder.due`: maintenance puts each event reminder on the
+  feed once, when it comes due (within the last day, before the event starts), and again if the
+  occurrence moves; `reminders_due` in its answer. A change's `id` is the key a sender sends it
+  once by. Events take `notify` (`slotlock_create_event`'s `notify: false`): no reminders, and a
+  sender tells no one. Reservations take `reminder_minutes` (up to five, minutes before the start),
+  each said once as `reminder.due` for the contact the reservation names, and again if it moves.
+- Contacts (P3, T2): new table `contacts`, the people a booking may name to be told about it, by
+  the tenant's own reference, with email, phone and WhatsApp numbers (E.164), locale and consent
+  per channel. `slotlock_put_contact`, `slotlock_get_contact`, `slotlock_delete_contact`
+  (`/v1/contacts/{contact_ref}`); deleting one also takes its reference off every booking. At most
+  100,000 a tenant. `slotlock_list_contacts` (`GET /v1/contacts`) lists them a page at a time, and
+  each answers `consent_at`: when each channel's answer was given, kept while it stands. The
+  dashboard's Contacts page lists them and forgets one, for an erasure request. Reservations take
+  `contact_ref` and `notify`, both on the feed with each change; neither is ever the person.
+- Holds that wait for payment (RFC 0004 C3, T2): `payment_required` on `slotlock_acquire_hold`
+  (time to live at most 30 minutes). Confirming one answers `409 payment_required` until
+  `slotlock_mark_hold_paid` (`POST /v1/holds/{hold_id}/paid`) records the payment's reference at
+  the integrator's processor: the same reference again answers the same hold, another
+  `payment_conflict`, an expired hold `hold_expired`. New feed type `hold.paid`. Slotlock records
+  payment state and never moves money. A hold may name what the payment must be (`payment`:
+  `amount_minor` and `currency`); `slotlock_mark_hold_paid` then takes what was `received`, and
+  less, or another currency, is `409 payment_amount_mismatch`. Holds answer `payment_amount` and
+  `paid_amount`. Agents' `slotlock_hold_slots` takes `payment_required` and `payment` too.
+- Busy time from calendars that give no events (RFC 0004 C1, T2): `slotlock_put_source_busy`
+  (`PUT /v1/resources/{resource_id}/coverage/{source}/busy`) records a source's coverage of a
+  window and the busy time in it (at most 5,000 intervals, merged), replacing what it said of that
+  window. New table `source_busy`. Every read counts it (free/busy, a resource's busy time,
+  searches and waitlist offers), and every booking Slotlock makes is refused
+  over it (`overlap`). A confirmed booking the source newly reports busy time over is left alone
+  and reported once as `coverage.conflict` (named by `source_id`, never the source). Retiring the
+  source forgets its busy time. `slotlock_report_coverage_conflict`
+  (`POST /v1/resources/{resource_id}/coverage/{source}/conflicts`) lets a calendar sync report a
+  booking it wrote that was moved (`changed_in_calendar`) or removed (`removed_from_calendar`) in
+  the calendar, as `coverage.conflict` with the booking left as it is.
+- Hours that inherit (RFC 0004 B2). The tenant and each location store weekly hours
+  (`setTenantAvailability`, the new `setLocationAvailability`; `PUT /v1/availability`,
+  `PUT /v1/locations/{location}/availability`, `GET /v1/availability`). A resource without its own
+  uses its location's (the nearest up the chain), then the tenant's, then the server's, and a
+  resource added later inherits too. Resources carry `inherited_availability`. The dashboard has
+  "Your hours" and an Hours page for each location; the CLI has `hours set --location`.
+- Closures and special days (RFC 0004 B1, T2): new table `availability_exceptions`, for the tenant,
+  a location (and everything inside it) or one resource. Each replaces whole local days, read in
+  each resource's time zone: `closed` empties them, `open` gives them 1-4 windows of their own.
+  The nearest scope wins on a day. One evaluator (`openWindows`) serves search, pool availability,
+  approval policies' `outside_hours`, and writes under `enforceHours`. At most 5,000 a tenant
+  (`availability_exceptions_limit_reached`). API: list, create and delete under
+  `/v1/availability/exceptions`. Dashboard: a Closures page. CLI: `slotlock closures
+  list|add|delete|import`.
+- Holiday calendars (B1): `slotlock_import_holidays` (`POST /v1/availability/holidays`) and
+  `closures import` close the days an iCalendar file's all-day events cover, recurring ones
+  expanded over a bounded span. `serve` fetches an `https` URL through the guarded fetch (no
+  private addresses, 1 MB, 10 seconds); the store-backed application backend fetches none unless
+  given `holidayFetch`. Each import is a calendar (new table `holiday_calendars`, under RLS, erased
+  with the tenant), kept by name where it applies: its `name`, else its own `X-WR-CALNAME`, else
+  the URL. Importing it again updates its closures and removes those it no longer names in the
+  span (`removed`), so a holiday a calendar dropped goes too; a closure imported before calendars
+  were kept becomes the calendar's that names it. With `subscribe`, the URL is kept and maintenance
+  imports it again every 30 days (`holidayFetch` on `maintainSlotlockTenant` and the scheduler;
+  `serve` and `slotlock maintain` pass the guarded fetch), a failed import keeping its closures,
+  noting why (`last_error`) and trying again a day later. `slotlock_list_holiday_calendars`
+  (`GET /v1/availability/holiday-calendars`) and `slotlock_delete_holiday_calendar`
+  (`DELETE …/{calendar_id}`, its closures with it); closures answer `calendar_id`; at most 50
+  calendars a tenant. The dashboard's Closures page takes a file upload (the form was limited to
+  8 KB, too small for most calendars, and now takes 1 MB), a paste or, where the server fetches
+  them (`serve`, Cloud), an address with "Import it again every 30 days", and lists the calendars
+  with their next import, a failed one's error, and Delete. `closures import` names the calendar
+  with `--label`.
+- Durations and hires (RFC 0004 B3). Booking rules gain `minDurationMinutes`, `maxDurationMinutes`,
+  `allowedDurations` and `defaultDurationMinutes`, and for a booking from one local day to another
+  `pickupTimes` and `returnTimes` (it starts and ends in them, and under `enforceHours` needs only
+  its start and end inside the hours). `turnaroundMinutes` goes up to a week. Refusals:
+  `booking_rule_min_duration`, `booking_rule_max_duration`, `booking_rule_duration_not_allowed`,
+  `booking_rule_pickup_time`, `booking_rule_return_time`. Searches offer only allowed lengths, and
+  take `defaultDurationMinutes` when they name none (`400 duration_required` otherwise).
+  `hoursApply` (`hours_apply`) says how the hours hold a hire: `whole` (all of it) or `ends` (its
+  start and end only), by default `ends` with pick-up or return times, else `whole`. Writes follow
+  it under `enforceHours`; `slotlock_find_available_slots` and `slotlock_find_next_available`
+  follow it always, so with `ends` they offer slots from one day to another, judged as the write
+  would be, and `slotlock_find_available_ranges` judges ranges as the write would where hours are
+  enforced. A pick-up or return refusal comes with alternatives, as other refusals of a time do.
+- Zone rule changes reach everything (RFC 0004 B9): `followZoneRules` also re-checks a recurring
+  series' occurrences to come (each kept with its wall time, reported once as
+  `event.timezone_shifted` with its `recurrence_id`; with `move`, the whole series moves at its
+  next revision in one transaction, each occurrence and its booking keeping its `recurrence_id`,
+  but only where the server's zone rules agree with the database's, else each is reported with
+  `reason: "rules_disagree"`; something in the way keeps its times, said once as
+  `event.timezone_conflict`), and reservations written with the new
+  optional `local_start` (`localStart`), reported as `reservation.timezone_shifted` or, with
+  `move`, moved at the next revision (`reservation.timezone_conflict` when something is in the
+  way). A `local_start` that does not name the reservation's start is `400 invalid_local_start`.
+- Holds across resources (RFC 0004 B7, T2): `slotlock_hold_together` (`POST /v1/slot-holds/together`),
+  the 19th agent tool, holds one time on 2-20 resources all or nothing, as one group whose holds
+  expire together. `slotlock_book_together` takes its `hold_group_id` and books the set from those
+  holds in one transaction. The application API gains `slotlock_tenant_book_together`
+  (`POST /v1/tenant/bundles`) and `slotlock_tenant_book_pool` (`POST /v1/tenant/pool-bookings`), the
+  agents' bundle and pool bookings for the tenant's own systems. Their events are the tenant's
+  (owner `internal`), not the key's: no agent's event quota counts them, and revoking the key
+  leaves them. Approval policies hold them only when they say `include_application: true` (new,
+  false by default), and a grant books them as the tenant's again; a key that `requires_approval`
+  still waits for a person whatever it books.
+- Waitlists that match (RFC 0004 B6): an entry may wait for any slot of a length within its
+  window (`duration_minutes`, `durationMs`), on a resource or a pool, and is offered the earliest
+  free one. Offers end `accepted`, `declined` (new `slotlock_decline_waitlist_offer`,
+  `POST /v1/waitlist/{entry_id}/decline`) or `lapsed`, decided by what becomes of their hold, by a
+  database trigger whatever path takes it. New feed types `waitlist.joined`, `.accepted`,
+  `.declined`, `.lapsed` and `.left`. Entries answer `duration_minutes` and `decided_at`.
+- A written booking lifecycle (RFC 0004 B4, T2): `src/lifecycle.ts` names each status, the move
+  each action makes and the refusal every other gets, and a test holds the store to it. A
+  tombstone keeps why the booking ended (`end_reason`: `cancelled` or `no_show`). New feed types:
+  `reservation.rescheduled` (a move, as well as `reservation.updated`) and `reservation.completed`,
+  which maintenance writes once for each booking whose end passed in the last week
+  (`bookings_completed` in its answer).
+- Cancellation and reschedule policies (RFC 0004 B5, T2): rules `cancelCutoffMinutes` and
+  `rescheduleCutoffMinutes` (`booking_rule_cancel_cutoff`, `booking_rule_reschedule_cutoff`), which
+  an admin may go past with `override_reason`, kept on the tombstone and the feed; and
+  `cancellationFee`, recorded on a late cancellation for the integrator to charge.
+- `slotlock_find_available_ranges` (`GET /v1/available-ranges`), the 18th agent tool: hires across
+  days for named resources or a pool's members, the earliest range on each from a pick-up window,
+  lasting N days or ending in a return window.
+- VAVAILABILITY carries RDATE and EXDATE (B1): the export adds the next year's closures as EXDATEs
+  and special hours as AVAILABLEs with RDATEs. The import reads them, and single AVAILABLEs, as
+  the resource's own exceptions, replacing those an earlier import made.
+
+- **Chats in the dashboard assistant.** Each conversation is a chat a member keeps:
+  - it is titled by its first message, at its own address (`<root>/assistant?c=<id>`);
+  - chats are listed beside the one shown, most recent first, grouped by day (Today, Yesterday,
+    Previous 7 days, Previous 30 days, Older), with a search box, and **Rename** and **Delete**
+    behind each one's menu;
+  - **New chat** starts another, and on a narrow screen the list is a page of its own
+    (`<root>/assistant/chats`);
+  - the page opens on the chat used in the past two hours, else on a new one;
+  - a streamed reply tells the page which chat it went to, so a new one gets its address and its
+    place in the list without a reload.
+
+  Chats are kept until the member deletes one, at most 100 per member (`SLOTLOCK_ASSISTANT_MAX_CHATS`;
+  past it, the least recently used goes, even with many started at once). A chat deleted while its
+  reply is being written stays deleted. They live in the new table `slotlock.assistant_chats`,
+  under forced RLS, erased with the tenant. `slotlock migrate` makes each member's 0.8 conversation
+  their first chat, once. Run `slotlock migrate`.
+- **Finding a resource by name.** `slotlock_list_resources` takes `query` and ranks the resources
+  that match what a person calls one, best first:
+  - each word is looked for in the name, reference, labels, kind, location and description;
+  - case and accents are ignored, and a typo, a word cut short or words run together are forgiven
+    (`mercedez`, `merc 2025` and `mercedesbenz` all find "Mercedes-Benz 2025");
+  - numbers match exactly;
+  - a search does bounded work, whatever the resources hold: past a budget of typo checks, it
+    matches exactly, by prefix and by words run together only.
+
+  `resource_not_found` for a name or reference given where an id belongs names the likeliest
+  resources in `details.candidate_1` to `candidate_3`.
+
+### Changed
+
+- The tenant's hours are stored, not copied onto every resource (RFC 0004 B2), and resources
+  without their own inherit them, those added later too. `storeTenantAvailability` stores them and
+  answers `{ inheriting, ownHours }`. `setTenantAvailability` keeps its 0.8.0 contract, deprecated:
+  every resource uses the hours afterwards, and it answers how many. `PUT /v1/availability` keeps
+  the hours resources have of their own by default; its `override_resources` is `none`, `all`
+  (clear them) or `matching` (clear those the same as the tenant's were or as the new ones: the
+  copies earlier versions made, while hours set apart on purpose stay), as are
+  `hours set --all --override` and `--matching`. It answers `resources_updated` (resources the
+  hours now apply to) and `resources_with_own_hours`. The dashboard's "Your hours" names the
+  resources that keep their own, with the same three choices, and `/resources?hours=own` lists
+  them.
+- `slotlock_run_maintenance` answers `bookings_completed`; the five clients' checks of its keys
+  include it. `slotlock_cancel_reservation` and `slotlock_cancel_tenant_event` answer
+  `cancellation_fee` (null when none).
+- `parseVAvailability` answers `days` as well as `rules`, and no longer refuses RDATE, EXDATE or an
+  AVAILABLE without RRULE.
+
+- **The dashboard assistant's store** (`SlotlockAssistantStore`) keeps chats. `listChats`,
+  `getChat`, `putChat`, `renameChat` and `deleteChat` replace `getConversation`,
+  `putConversation` and `deleteConversation`, and `settleAction` takes the chat's id. The tenant
+  store has `listAssistantChats`, `getAssistantChat`, `putAssistantChat`, `renameAssistantChat`
+  and `deleteAssistantChat`, and `settleAssistantAction` takes `chatId`.
+- **Conversation lifetime.** `conversationTtlMs` no longer defaults to 2 hours: without it, chats
+  are kept until deleted. Given, it may be up to 3,650 days.
+- **New conversation is New chat.** It starts another chat and deletes nothing. A form of 0.8 that
+  posts `<root>/assistant/reset` does the same.
+- **The assistant's system prompt** lists the workspace's resources (up to 50, with the ids tools
+  take) and says how to find others. The tool descriptions and the MCP instructions say that
+  `resource_id` takes an id and how to find one, and that a filter leaves out resources that state
+  nothing.
+
+### Fixed
+
+- Enforced hours (`enforceHours`) judged a write inside `withTenant` against no hours when its
+  resource used the server's default (`defaultAvailabilityRules`, `SLOTLOCK_AVAILABILITY` under
+  `serve`): every such booking was refused `booking_rule_outside_hours`. The tenant's store now
+  carries the server's hours.
+
+- **The assistant's chips stream.** "What's on today" and "Find free time" were forms that waited
+  for the whole turn and then reloaded the page; they now send through the box, so their reply
+  streams.
+
+- The dashboard assistant's Stop stops the turn on any runtime. Cancelling the streamed reply now
+  aborts the turn itself, which keeps what it had. Before, only `request.signal` stopped it, and a
+  runtime that does not abort it when the client goes kept the turn running. On Workers, the
+  request's database connection now closes only once the stopped turn is kept.
+- The Overview never shows a change by its type. A change it has no words for, from a newer server,
+  reads "Something changed", on its resource when it names one. A type such as `constructor` no
+  longer finds an inherited entry.
+- The assistant page's script keeps live steps in a map with no prototype, so a provider's tool-call
+  id of `__proto__` names nothing.
+
+## 0.8.0 - 2026-11-10
+
+### Added
+
+- **Usage** in the dashboard's navigation on hosted Slotlock, with or without Stripe: the plan (or
+  the default it moves to, and when) against its limits, this month's operations, bookings and
+  holds against the quotas, and which key used what. Without Stripe, an owner asks for another plan
+  at `SLOTLOCK_PLAN_CONTACT`. `createSlotlockDashboard` takes `plans` (`plan`, `enrol`,
+  `planDefault`, `contact`); `billing` still brings its own.
+
+### Changed
+
+- The Overview leads with what needs a person (approvals waiting, a failed payment, a quota nearly
+  or fully used, a coming plan the workspace is over), then the week ahead and the activity as
+  sentences ("Booking agent booked room-3", passive for what Slotlock did, repeats counted on one
+  line), never a change's type. Get started walks a new workspace from its first resource to an
+  agent that has used a key, folds to one line half way and goes once done. The plan's use and the
+  MCP and A2A endpoints (with the Claude Code command) sit beside the activity.
+- The Plan page is Usage, and a limit refused says "see Usage".
+
+- The dashboard assistant is a chat. A reply streams into the page as the model writes it (the
+  dashboard's own script reads `POST <root>/assistant/stream`, one JSON object a line; the CSP
+  allows `connect-src 'self'` for it), with a Stop button. Without script, a message still posts
+  and the page shows the reply. Replies are Markdown, rendered by one renderer on the server and,
+  from its source, in the page as they stream: everything escaped first, links http(s) only. The
+  page is one centred column, with the box at the centre when the conversation is empty and five
+  things to ask beside it. Each run of reads folds into one line ("Read resources, checked
+  availability") that names, in words, a step that could not run and why. A proposed change is a
+  card that leads with when, which resource and its title, and keeps every other argument one click
+  away; its button says what it does ("Book", "Cancel booking"), and once decided it folds into
+  one line. A provider failure ends the conversation with Retry.
+- Settings is a page a section (Assistant, Endpoints, Hours, Account). The assistant's section
+  shows what is connected, with Test and its result in place, then one form: the provider as tiles
+  (a named one brings its own URL and API format; Custom takes both), the model with Load models,
+  and the key as its last four characters with Replace. Disconnect stands apart.
+
+### Fixed
+
+- A message sent twice (a double click, a reload) no longer ends on "That form was already
+  sent": the second lands on the conversation, and the turn runs once. The same holds for
+  approving, declining and New conversation.
+- A success notice (Saved, Connected) was shown in the error colour: notices are alerts only on
+  an error page, and a status otherwise.
+
 ## 0.7.0 - 2026-11-10
 
 ### Added

package/agent-server.d.ts

@@ -39,6 +39,8 @@ export declare const SLOTLOCK_A2A_TASK_PAGE_SIZE: Readonly<{
 }>;
 /** The A2A 1.0 `TaskState` names, as a `ListTasks` status filter spells them in JSON. */
 export declare const SLOTLOCK_A2A_TASK_STATES: readonly ["TASK_STATE_UNSPECIFIED", "TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED"];
+/** The longest resource search (resource-search.ts SLOTLOCK_RESOURCE_SEARCH_MAX; a test holds them equal). */
+export declare const SLOTLOCK_AGENT_RESOURCE_SEARCH_MAX = 200;
 /** The tools' copy of the profile's kinds and bounds, for the test that holds it to resource-profile.ts. */
 export declare const SLOTLOCK_AGENT_RESOURCE_PROFILE: Readonly<{
     kinds: ("desk" | "equipment" | "machine" | "other" | "person" | "room" | "service" | "space" | "vehicle")[];
@@ -62,7 +64,7 @@ export declare const SLOTLOCK_MAX_ALTERNATIVES = 3;
  * Operation (MCP tool / A2A skill) names. They use only `[a-z_]`, so they are valid tool names for the
  * Claude Messages API (`^[a-zA-Z0-9_-]{1,128}$`), OpenAI function calling and every MCP host.
  */
-export type SlotlockAgentOperation = 'slotlock_list_resources' | 'slotlock_get_free_busy' | 'slotlock_find_next_available' | 'slotlock_find_available_slots' | 'slotlock_hold_slots' | 'slotlock_release_slots' | 'slotlock_confirm_slot' | 'slotlock_reschedule' | 'slotlock_cancel' | 'slotlock_book_together' | 'slotlock_book_pool' | 'slotlock_get_pool_availability' | 'slotlock_create_event' | 'slotlock_get_event' | 'slotlock_list_events' | 'slotlock_update_event' | 'slotlock_delete_event';
+export type SlotlockAgentOperation = 'slotlock_list_resources' | 'slotlock_get_free_busy' | 'slotlock_find_next_available' | 'slotlock_find_available_slots' | 'slotlock_find_available_ranges' | 'slotlock_hold_slots' | 'slotlock_hold_together' | 'slotlock_release_slots' | 'slotlock_confirm_slot' | 'slotlock_reschedule' | 'slotlock_cancel' | 'slotlock_book_together' | 'slotlock_book_pool' | 'slotlock_get_pool_availability' | 'slotlock_create_event' | 'slotlock_get_event' | 'slotlock_list_events' | 'slotlock_update_event' | 'slotlock_delete_event';
 /**
  * Names earlier builds published, which every entry point still accepts and dispatches as the same
  * operation; nothing advertises them. The dotted names came first, before tool names had to be
@@ -189,6 +191,12 @@ export interface SlotlockAgentCalendarBackend {
      * (`slotlock_hold_slots`); a tool without it answers `holds_unavailable`.
      */
     holdSlots?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Optional. Hold one time on 2-20 resources all or nothing, as one group with one time to live
+     * (`slotlock_hold_together`, RFC 0004 B7), else `holds_unavailable`. `slotlock_book_together`
+     * with its `hold_group_id` books the set.
+     */
+    holdTogether?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Optional. Book any one free member of a pool (`slotlock_book_pool`), else `pools_unavailable`. */
     bookPool?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
     /**
@@ -228,6 +236,18 @@ export interface SlotlockAgentCalendarBackend {
         }[];
         certain: boolean;
     }>;
+    /**
+     * Optional. Hires across days (`slotlock_find_available_ranges`, RFC 0004 B3): each resource's, or
+     * each pool member's, earliest range from a pick-up window to a return window, else
+     * `ranges_unavailable`.
+     */
+    findAvailableRanges?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Optional. The length a search for these resources offers when it is asked for none: their
+     * booking rules' `defaultDurationMinutes` when they all give the same one, else null. Without it,
+     * a search names its length.
+     */
+    defaultDuration?(context: SlotlockAgentInvocationContext, resourceIds: readonly string[]): Promise<number | null>;
 }
 /**
  * OAuth 2.0 discovery for the MCP endpoint (MCP 2025-11-25 authorization, RFC 9728). Slotlock only
@@ -593,11 +613,11 @@ export declare function slotlockOpenApi(options?: {
     application?: boolean;
 }): Record<string, unknown>;
 export declare function slotlockAgentTools(): {
-    name: "slotlock_book_pool" | "slotlock_book_together" | "slotlock_cancel" | "slotlock_confirm_slot" | "slotlock_create_event" | "slotlock_delete_event" | "slotlock_find_available_slots" | "slotlock_find_next_available" | "slotlock_get_event" | "slotlock_get_free_busy" | "slotlock_get_pool_availability" | "slotlock_hold_slots" | "slotlock_list_events" | "slotlock_list_resources" | "slotlock_release_slots" | "slotlock_reschedule" | "slotlock_update_event";
-    title: "Book from a pool" | "Book resources together" | "Cancel an event" | "Confirm a held slot" | "Create resource event" | "Delete resource event" | "Find available slots" | "Find next available interval" | "Get free-busy" | "Get pool availability" | "Get resource event" | "Hold candidate slots" | "List calendar resources" | "List resource events" | "Release held slots" | "Reschedule an event" | "Update resource event";
-    description: "Book a resource for a time, as an event of up to 3,660 days (a booking, lease or long rental). The database refuses a time already taken: 409 overlap, with alternatives (the earliest free times of the same length) and, when the booking in the way is yours, its id. A booking rule that refuses the time answers booking_rule_… with alternatives too. To book a time you hold, pass its hold_id, or use slotlock_confirm_slot. A retry with the same idempotency_key answers the same event." | "Book a time you hold (a hold_id from slotlock_hold_slots): the held resource and time exactly, with the title and details you give, and the rest of its group released. 409 hold_expired when the hold lapsed first; 404 hold_not_found when it was released, booked or is not yours. A retry answers the same event (replayed)." | "Book any one member of a pool (a vehicle class, a room type) for a time: members are tried in the pool's order (by id, fewest bookings in the last 30 days first, or in turn, as the tenant sets it) and the first that is free and allows the booking is booked, in one transaction, so a class sells out exactly at its number of members. The event names the member booked. 409 pool_full when none is free; 404 pool_not_found when the pool has no member you may book. A retry with the same idempotency_key answers the same event." | "Book the same time on 2-20 resources at once, all or none: a van with its driver, a room with its projector. If any of them is taken, nothing is booked, and the refusal names that resource_id. Find such a time with slotlock_find_available_slots and require_free. A retry with the same idempotency_key answers the same events." | "Cancel one of your events at the revision you last read (expected_revision); a stale one is 409 revision_conflict. It cannot come back at that revision, so an old copy synced later does not restore it. slotlock_cancel does the same with fewer fields." | "Cancel one of your events at the revision you last read (expected_revision); a stale one is 409 revision_conflict. Its time is free at once. A retry answers the same cancellation (replayed)." | "Change one of your events at the revision you last read (expected_revision): its time, resource or details, all or nothing. A time already taken is 409 overlap with alternatives; a stale revision is 409 revision_conflict (read the event again). With expected_resource_id, the resource you read it on, an event since moved elsewhere is not found. To change only the time, slotlock_reschedule is simpler." | "Find the earliest certain interval that satisfies the requested duration (up to the 367-day search window, so a multi-month rental slot can be found). Name the resources with resource_ids, or select them as slotlock_get_free_busy does: at most 100." | "Hold up to five candidate slots for a short time (30-900 seconds) while a person chooses, as alternatives in one group: each free one is held, the others are listed with why not. Book one by passing its hold_id to slotlock_create_event, which releases the rest; unbooked holds expire on their own. A hold is yours alone, and you may have 20 live at once. A candidate refused for its time comes with alternatives (the earliest free times of its length). slotlock_confirm_slot books a held time." | "How many members of a pool (a vehicle class, a room type) are free across a window, each only where its booking rules let a booking start: the window split where that number changes, each part with how many are free, and coverage certainty. Book one with slotlock_book_pool. 404 pool_not_found when the pool has no member you may book." | "List resources visible to the authenticated tenant principal, with what each says about itself: its name (show it rather than the reference), description, kind, capacity and labels, where it is (location), the groups it is in (a team, a department), and the pool it belongs to (a vehicle class, a room type). With kind, only resources of that kind; with labels, only those with every label given; with location, only those there or at a location in it; with group, only that group's. With pool, only that pool's members, in the order slotlock_book_pool tries them." | "List up to `limit` certain slots of the requested duration, earliest first across the resources, each one free of busy time and inside the resource's hours, to offer a person a choice. With require_free, only times when at least that many of the resources are free together, each slot naming them in resource_ids: every resource for a booking that needs them all (book it with slotlock_book_together), or any n of them. No slot is listed unless every resource's coverage is certain. Name the resources with resource_ids, or select them as slotlock_get_free_busy does: at most 20." | "List your events that meet a time window, earliest first." | "Move one of your events to a new time, and to another resource if you give one, at the revision you last read (expected_revision). A time already taken is 409 overlap with alternatives; a stale revision 409 revision_conflict. A retry answers the same move (replayed)." | "Read one of your events by its id, with its revision (pass it as expected_revision to change or cancel it)." | "Release one of your holds, and the rest of its group, at once instead of letting them expire. `released` is false when it was already gone." | "When each resource is busy in a window, as busy intervals only (never whose or what), and whether that is certain (coverage: \"uncertain\" where a calendar feeding it has not been read lately). Name the resources with resource_ids, or select them instead by location (and every location in it), group, labels (every one), kind or pool: at most 100 (more answers selection_too_large, none selection_empty), named in selected_resource_ids.";
+    name: "slotlock_book_pool" | "slotlock_book_together" | "slotlock_cancel" | "slotlock_confirm_slot" | "slotlock_create_event" | "slotlock_delete_event" | "slotlock_find_available_ranges" | "slotlock_find_available_slots" | "slotlock_find_next_available" | "slotlock_get_event" | "slotlock_get_free_busy" | "slotlock_get_pool_availability" | "slotlock_hold_slots" | "slotlock_hold_together" | "slotlock_list_events" | "slotlock_list_resources" | "slotlock_release_slots" | "slotlock_reschedule" | "slotlock_update_event";
+    title: "Book from a pool" | "Book resources together" | "Cancel an event" | "Confirm a held slot" | "Create resource event" | "Delete resource event" | "Find available ranges" | "Find available slots" | "Find next available interval" | "Get free-busy" | "Get pool availability" | "Get resource event" | "Hold candidate slots" | "Hold resources together" | "List calendar resources" | "List resource events" | "Release held slots" | "Reschedule an event" | "Update resource event";
+    description: "Book a resource for a time, as an event of up to 3,660 days (a booking, lease or long rental). The database refuses a time already taken: 409 overlap, with alternatives (the earliest free times of the same length) and, when the booking in the way is yours, its id. A booking rule that refuses the time answers booking_rule_… with alternatives too. To book a time you hold, pass its hold_id, or use slotlock_confirm_slot. A retry with the same idempotency_key answers the same event." | "Book a time you hold (a hold_id from slotlock_hold_slots): the held resource and time exactly, with the title and details you give, and the rest of its group released. 409 hold_expired when the hold lapsed first; 404 hold_not_found when it was released, booked or is not yours. A retry answers the same event (replayed)." | "Book any one member of a pool (a vehicle class, a room type) for a time: members are tried in the pool's order (by id, fewest bookings in the last 30 days first, or in turn, as the tenant sets it) and the first that is free and allows the booking is booked, in one transaction, so a class sells out exactly at its number of members. The event names the member booked. 409 pool_full when none is free; 404 pool_not_found when the pool has no member you may book. A retry with the same idempotency_key answers the same event." | "Book the same time on 2-20 resources at once, all or none: a van with its driver, a room with its projector. If any of them is taken, nothing is booked, and the refusal names that resource_id. Find such a time with slotlock_find_available_slots and require_free. With hold_group_id, it books the set slotlock_hold_together held, from those holds. A retry with the same idempotency_key answers the same events." | "Cancel one of your events at the revision you last read (expected_revision); a stale one is 409 revision_conflict. It cannot come back at that revision, so an old copy synced later does not restore it. slotlock_cancel does the same with fewer fields." | "Cancel one of your events at the revision you last read (expected_revision); a stale one is 409 revision_conflict. Its time is free at once. A retry answers the same cancellation (replayed)." | "Change one of your events at the revision you last read (expected_revision): its time, resource or details, all or nothing. A time already taken is 409 overlap with alternatives; a stale revision is 409 revision_conflict (read the event again). With expected_resource_id, the resource you read it on, an event since moved elsewhere is not found. To change only the time, slotlock_reschedule is simpler." | "Find hires across days, such as a car from Friday to Monday: for each resource named, or each member of a pool, the earliest range that starts between pickup_start and pickup_end and either lasts `days` days (ending at the same local time) or ends between return_start and return_end. Each range is free throughout with its buffers, allowed by the resource's booking rules (pick-up and return times, lengths, notice, step) and starts and ends inside its bookable hours. Up to `limit` ranges, earliest first, one per resource; none unless every resource's coverage is certain. Book one with slotlock_create_event, or a pool's with slotlock_book_pool, at its start and end." | "Find the earliest certain interval that satisfies the requested duration (up to the 367-day search window, so a multi-month rental slot can be found). Name the resources with resource_ids, or select them as slotlock_get_free_busy does: at most 100." | "Hold one time on 2-20 resources at once, all or none, such as a car with its driver while a person decides: if any is taken, nothing is held and the refusal names that resource_id. The holds are one group with one time to live (ttl_seconds, the earliest of them). Book the set with slotlock_book_together and its hold_group_id; release them with slotlock_release_slots and any hold_id. A retry with the same idempotency_key answers the same holds." | "Hold up to five candidate slots for a short time (30-900 seconds) while a person chooses, as alternatives in one group: each free one is held, the others are listed with why not. Book one by passing its hold_id to slotlock_create_event, which releases the rest; unbooked holds expire on their own. With payment_required, a hold is booked only once the system you book for records its payment (the person pays there): booking it before then answers payment_required, so send the person to pay and try again. A hold is yours alone, and you may have 20 live at once. A candidate refused for its time comes with alternatives (the earliest free times of its length). slotlock_confirm_slot books a held time." | "How many members of a pool (a vehicle class, a room type) are free across a window, each only where its booking rules let a booking start: the window split where that number changes, each part with how many are free, and coverage certainty. Book one with slotlock_book_pool. 404 pool_not_found when the pool has no member you may book." | "List resources visible to the authenticated tenant principal, with what each says about itself: its name (show it rather than the reference), description, kind, capacity and labels, where it is (location), the groups it is in (a team, a department), and the pool it belongs to (a vehicle class, a room type). With kind, only resources of that kind; with labels, only those with every label given; with location, only those there or at a location in it; with group, only that group's. With pool, only that pool's members, in the order slotlock_book_pool tries them. With query, the resources that best match what a person calls one, best first, at most limit and with no next_cursor: each word is looked for in the name, reference, labels, kind, location and description, ignoring case and accents, and forgiving a typo, a word cut short or words run together (\"mercedez\", \"merc 2025\" and \"mercedesbenz\" find \"Mercedes-Benz 2025\"); numbers match exactly. It is the way to find the id of a resource a person names, since other tools take ids only. When several match about equally, ask which one is meant. A resource that states no kind, labels or location is left out by those filters, so search without them before saying a resource does not exist." | "List up to `limit` certain slots of the requested duration, earliest first across the resources, each one free of busy time and inside the resource's hours, to offer a person a choice. With require_free, only times when at least that many of the resources are free together, each slot naming them in resource_ids: every resource for a booking that needs them all (book it with slotlock_book_together), or any n of them. No slot is listed unless every resource's coverage is certain. Name the resources with resource_ids, or select them as slotlock_get_free_busy does: at most 20." | "List your events that meet a time window, earliest first." | "Move one of your events to a new time, and to another resource if you give one, at the revision you last read (expected_revision). A time already taken is 409 overlap with alternatives; a stale revision 409 revision_conflict. A retry answers the same move (replayed)." | "Read one of your events by its id, with its revision (pass it as expected_revision to change or cancel it)." | "Release one of your holds, and the rest of its group, at once instead of letting them expire. `released` is false when it was already gone." | "When each resource is busy in a window, as busy intervals only (never whose or what), and whether that is certain (coverage: \"uncertain\" where a calendar feeding it has not been read lately). Name the resources with resource_ids, or select them instead by location (and every location in it), group, labels (every one), kind or pool: at most 100 (more answers selection_too_large, none selection_empty), named in selected_resource_ids.";
     annotations: {
-        title: "Book from a pool" | "Book resources together" | "Cancel an event" | "Confirm a held slot" | "Create resource event" | "Delete resource event" | "Find available slots" | "Find next available interval" | "Get free-busy" | "Get pool availability" | "Get resource event" | "Hold candidate slots" | "List calendar resources" | "List resource events" | "Release held slots" | "Reschedule an event" | "Update resource event";
+        title: "Book from a pool" | "Book resources together" | "Cancel an event" | "Confirm a held slot" | "Create resource event" | "Delete resource event" | "Find available ranges" | "Find available slots" | "Find next available interval" | "Get free-busy" | "Get pool availability" | "Get resource event" | "Hold candidate slots" | "Hold resources together" | "List calendar resources" | "List resource events" | "Release held slots" | "Reschedule an event" | "Update resource event";
         readOnlyHint: boolean;
         destructiveHint: boolean;
         idempotentHint: true;