slotlock 0.8.0 → 0.10.0

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;

package/agent-server.js

@@ -61,6 +61,8 @@ export const SLOTLOCK_A2A_TASK_STATES = Object.freeze([
 ]);
 const DATE_TIME = z.string().datetime({ offset: true });
 const RESOURCE_ID = z.string().trim().min(1).max(200);
+/** The longest resource search (resource-search.ts SLOTLOCK_RESOURCE_SEARCH_MAX; a test holds them equal). */
+export const SLOTLOCK_AGENT_RESOURCE_SEARCH_MAX = 200;
 const EVENT_ID = z.string().trim().min(1).max(500);
 const HOLD_ID = z.string().uuid();
 const POOL = z.string().regex(/^[a-z0-9][a-z0-9._-]{0,99}$/);
@@ -112,6 +114,18 @@ function bookPool(backend, context, input) {
         throw new SlotlockAgentOperationError('pools_unavailable', 409);
     return backend.bookPool(context, input);
 }
+/** `slotlock_hold_together`, from a backend that holds sets (RFC 0004 B7). */
+function holdTogether(backend, context, input) {
+    if (!backend.holdTogether)
+        throw new SlotlockAgentOperationError('holds_unavailable', 409);
+    return backend.holdTogether(context, input);
+}
+/** `slotlock_find_available_ranges`, from a backend that searches hires (RFC 0004 B3). */
+function findAvailableRanges(backend, context, input) {
+    if (!backend.findAvailableRanges)
+        throw new SlotlockAgentOperationError('ranges_unavailable', 409);
+    return backend.findAvailableRanges(context, input);
+}
 /** `slotlock_get_pool_availability`, from a backend that knows pools, as `holdSlots`. */
 function getPoolAvailability(backend, context, input) {
     if (!backend.getPoolAvailability)
@@ -226,6 +240,8 @@ const ALTERNATIVE_REFUSALS = new Set([
     'booking_rule_max_advance',
     'booking_rule_slot_step',
     'booking_rule_outside_hours',
+    'booking_rule_pickup_time',
+    'booking_rule_return_time',
 ]);
 /** At most this many alternatives, the earliest first. */
 export const SLOTLOCK_MAX_ALTERNATIVES = 3;
@@ -263,7 +279,8 @@ async function alternativesFor(backend, context, want) {
         const found = await findAvailableSlots(backend, { ...context, operation: 'slotlock_find_available_slots' }, {
             resource_ids: resourceIds,
             start: new Date(from).toISOString(),
-            end: new Date(from + ALTERNATIVES_WINDOW_MS).toISOString(),
+            // Starts over the next seven days, however long the booking runs.
+            end: new Date(from + ALTERNATIVES_WINDOW_MS + durationMs).toISOString(),
             duration_minutes: durationMs / 60_000,
             limit: SLOTLOCK_MAX_ALTERNATIVES,
             ...(want.needed !== undefined ? { require_free: Math.min(want.needed, resourceIds.length) } : {}),
@@ -542,7 +559,9 @@ const OPERATION_SCOPES = Object.freeze({
     slotlock_get_free_busy: 'read',
     slotlock_find_next_available: 'read',
     slotlock_find_available_slots: 'read',
+    slotlock_find_available_ranges: 'read',
     slotlock_hold_slots: 'write',
+    slotlock_hold_together: 'write',
     slotlock_book_together: 'write',
     slotlock_book_pool: 'write',
     slotlock_get_pool_availability: 'read',
@@ -614,6 +633,14 @@ const SELECTING_OPERATIONS = new Map([
     ['slotlock_find_available_slots', 20],
 ]);
 const SELECTION_FIELDS = ['location', 'group', 'labels', 'kind', 'pool'];
+/** Searches that take the resources' usual length when they name none. */
+const DEFAULT_LENGTH_OPERATIONS = new Set([
+    'slotlock_find_next_available',
+    'slotlock_find_available_slots',
+]);
+/** The most ranges one search answers. */
+const MAX_LISTED_RANGES = 50;
+const MAX_RANGE_RESOURCES = 100;
 /** Whether a search's input names its resources, or selects them, and not both or neither. */
 function selectsOrNames(input) {
     const selects = SELECTION_FIELDS.some((field) => input[field] !== undefined);
@@ -656,6 +683,8 @@ const EVENT_CREATE_INPUT = z
     recurrence_exceptions: z.array(RECURRENCE_EXCEPTION_INPUT).max(500).optional(),
     /** Book the time one of your holds keeps (slotlock_hold_slots); its alternatives are released. */
     hold_id: HOLD_ID.optional(),
+    /** False: no one should be notified about it, nor reminded (RFC 0004 P3). Default true. */
+    notify: z.boolean().optional(),
 })
     .strict()
     .refine((value) => boundedEventSpan(value.starts_at, value.ends_at));
@@ -663,10 +692,11 @@ const OPERATION_DEFINITIONS = [
     {
         name: 'slotlock_list_resources',
         title: 'List calendar resources',
-        description: '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.',
+        description: '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.',
         input: z
             .object({
             cursor: z.string().max(500).optional(),
+            query: z.string().trim().min(1).max(SLOTLOCK_AGENT_RESOURCE_SEARCH_MAX).optional(),
             limit: z.number().int().min(1).max(100).default(50),
             pool: POOL.optional(),
             kind: RESOURCE_KIND.optional(),
@@ -758,7 +788,8 @@ const OPERATION_DEFINITIONS = [
             pool: POOL.optional(),
             start: DATE_TIME,
             end: DATE_TIME,
-            duration_minutes: z.number().int().min(1).max(MAX_SLOT_MINUTES),
+            /** Left out: the resources' usual length (their booking rules' default_duration_minutes). */
+            duration_minutes: z.number().int().min(1).max(MAX_SLOT_MINUTES).optional(),
         })
             .strict()
             .refine(selectsOrNames, 'Give resource_ids, or select resources by location, group, labels, kind or pool: one or the other')
@@ -791,7 +822,8 @@ const OPERATION_DEFINITIONS = [
             pool: POOL.optional(),
             start: DATE_TIME,
             end: DATE_TIME,
-            duration_minutes: z.number().int().min(1).max(MAX_SLOT_MINUTES),
+            /** Left out: the resources' usual length (their booking rules' default_duration_minutes). */
+            duration_minutes: z.number().int().min(1).max(MAX_SLOT_MINUTES).optional(),
             limit: z.number().int().min(1).max(MAX_LISTED_SLOTS).default(10),
             require_free: z.number().int().min(1).max(MAX_SLOT_RESOURCES).optional(),
         })
@@ -819,6 +851,54 @@ const OPERATION_DEFINITIONS = [
         invoke: findAvailableSlots,
         example: { resource_ids: [EXAMPLE_RESOURCE_ID], ...EXAMPLE_WINDOW, duration_minutes: 60, limit: 10 },
     },
+    {
+        name: 'slotlock_find_available_ranges',
+        title: 'Find available ranges',
+        description: '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.',
+        input: z
+            .object({
+            resource_ids: z.array(RESOURCE_ID).min(1).max(MAX_SLOT_RESOURCES).optional(),
+            pool: POOL.optional(),
+            pickup_start: DATE_TIME,
+            pickup_end: DATE_TIME,
+            days: z.number().int().min(1).max(366).optional(),
+            return_start: DATE_TIME.optional(),
+            return_end: DATE_TIME.optional(),
+            limit: z.number().int().min(1).max(MAX_LISTED_RANGES).default(10),
+        })
+            .strict()
+            .refine((value) => (value.resource_ids !== undefined) !== (value.pool !== undefined), 'Give resource_ids or pool, one of them')
+            .refine((value) => value.days !== undefined
+            ? value.return_start === undefined && value.return_end === undefined
+            : value.return_start !== undefined && value.return_end !== undefined, 'Give days, or return_start and return_end')
+            .refine((value) => {
+            const pickupStart = Date.parse(value.pickup_start);
+            const pickupEnd = Date.parse(value.pickup_end);
+            const last = value.days !== undefined ? pickupEnd + (value.days + 1) * 86_400_000 : Date.parse(value.return_end ?? '');
+            const returnStart = value.return_start === undefined ? pickupStart : Date.parse(value.return_start);
+            return pickupEnd >= pickupStart && last >= returnStart && last - pickupStart <= MAX_AGENT_WINDOW_MS;
+        }, 'The windows must run forward, within the longest window a search reads'),
+        output: z
+            .object({
+            ranges: z
+                .array(z.object({ resource_id: RESOURCE_ID, start: DATE_TIME, end: DATE_TIME }).strict())
+                .max(MAX_LISTED_RANGES),
+            coverage: COVERAGE,
+            /** The pool's members searched, when the call named a pool. */
+            selected_resource_ids: z.array(RESOURCE_ID).max(MAX_RANGE_RESOURCES).optional(),
+        })
+            .strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: findAvailableRanges,
+        example: {
+            pool: 'compact-car',
+            pickup_start: '2027-03-05T09:00:00Z',
+            pickup_end: '2027-03-05T12:00:00Z',
+            return_start: '2027-03-08T09:00:00Z',
+            return_end: '2027-03-08T12:00:00Z',
+            limit: 5,
+        },
+    },
     {
         name: 'slotlock_create_event',
         title: 'Create resource event',
@@ -890,7 +970,7 @@ const OPERATION_DEFINITIONS = [
     {
         name: 'slotlock_book_together',
         title: 'Book resources together',
-        description: '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.',
+        description: '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.',
         input: z
             .object({
             resource_ids: z.array(RESOURCE_ID).min(2).max(MAX_SLOT_RESOURCES),
@@ -898,6 +978,8 @@ const OPERATION_DEFINITIONS = [
             ends_at: DATE_TIME,
             timezone: z.string().min(1).max(100),
             title: z.string().trim().min(1).max(500).optional(),
+            /** The set slotlock_hold_together held, booked from its holds (RFC 0004 B7). */
+            hold_group_id: z.string().uuid().optional(),
             idempotency_key: IDEMPOTENCY_KEY,
         })
             .strict()
@@ -1032,7 +1114,7 @@ const OPERATION_DEFINITIONS = [
     {
         name: 'slotlock_hold_slots',
         title: 'Hold candidate slots',
-        description: '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.',
+        description: '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.',
         input: z
             .object({
             slots: z
@@ -1044,8 +1126,19 @@ const OPERATION_DEFINITIONS = [
                 .max(5),
             ttl_seconds: z.number().int().min(30).max(900).default(300),
             idempotency_key: IDEMPOTENCY_KEY,
+            /** Booked only once the integrator records its payment (RFC 0004 C3). */
+            payment_required: z.boolean().optional(),
+            /** What that payment must be, in the currency's minor unit. */
+            payment: z
+                .object({ amount_minor: z.number().int().min(0).max(1_000_000_000_000), currency: z.string().regex(/^[A-Z]{3}$/) })
+                .strict()
+                .optional(),
         })
-            .strict(),
+            .strict()
+            .refine((value) => value.payment === undefined || value.payment_required === true, {
+            message: 'payment needs payment_required',
+            path: ['payment'],
+        }),
         output: z
             .object({
             group_id: HOLD_ID,
@@ -1057,6 +1150,12 @@ const OPERATION_DEFINITIONS = [
                 start: DATE_TIME,
                 end: DATE_TIME,
                 expires_at: DATE_TIME,
+                payment_required: z.literal(true).optional(),
+                payment_amount: z
+                    .object({ amount_minor: z.number().int().min(0), currency: z.string().regex(/^[A-Z]{3}$/) })
+                    .strict()
+                    .nullable()
+                    .optional(),
             })
                 .strict())
                 .max(5),
@@ -1083,6 +1182,42 @@ const OPERATION_DEFINITIONS = [
             idempotency_key: 'hold-handover-2027-03-02',
         },
     },
+    {
+        name: 'slotlock_hold_together',
+        title: 'Hold resources together',
+        description: '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.',
+        input: z
+            .object({
+            resource_ids: z.array(RESOURCE_ID).min(2).max(MAX_SLOT_RESOURCES),
+            start: DATE_TIME,
+            end: DATE_TIME,
+            ttl_seconds: z.number().int().min(30).max(900).default(300),
+            idempotency_key: IDEMPOTENCY_KEY,
+        })
+            .strict()
+            .refine(boundedAgentWindow),
+        output: z
+            .object({
+            group_id: z.string().uuid(),
+            holds: z
+                .array(z
+                .object({ hold_id: z.string().uuid(), resource_id: RESOURCE_ID, start: DATE_TIME, end: DATE_TIME, expires_at: DATE_TIME })
+                .strict())
+                .min(2)
+                .max(MAX_SLOT_RESOURCES),
+            expires_at: DATE_TIME,
+        })
+            .strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: holdTogether,
+        example: {
+            resource_ids: [EXAMPLE_RESOURCE_ID, '3c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f'],
+            start: '2027-03-02T09:00:00Z',
+            end: '2027-03-02T17:00:00Z',
+            ttl_seconds: 300,
+            idempotency_key: 'hold-van-and-driver-1',
+        },
+    },
     {
         name: 'slotlock_release_slots',
         title: 'Release held slots',
@@ -1633,6 +1768,15 @@ export async function invokeSlotlockAgentOperation(args) {
             input = Object.fromEntries(Object.entries(input).filter(([key]) => !SELECTION_FIELDS.includes(key)));
             input.resource_ids = selected;
         }
+        // A search that names no length takes the resources' usual one (RFC 0004 B3).
+        if (DEFAULT_LENGTH_OPERATIONS.has(operation.name) && input.duration_minutes === undefined) {
+            const usual = backend.defaultDuration
+                ? await backend.defaultDuration(context, (input.resource_ids ?? []))
+                : null;
+            if (usual === null)
+                return { ok: false, status: 400, code: 'duration_required' };
+            input = { ...input, duration_minutes: usual };
+        }
         const asked = input;
         recover = (code) => alternativesForRefusal(backend, context, operation.name, asked, code);
         let answered = await method.call(backend, context, input);
@@ -1990,6 +2134,7 @@ function parseSubscriptionFilter(value) {
 /** Natural-language guidance `server/discover` gives the model on how to use these tools well. */
 const SLOTLOCK_MCP_INSTRUCTIONS = [
     'Slotlock is a tenant-isolated resource calendar (vehicles, rooms, equipment).',
+    'A resource is named in calls by its id (resource_id, resource_ids), never by its name or reference: find the id of one a person names with slotlock_list_resources and query (what they call it; typos and accents are forgiven). resource_not_found for something that is not an id names, in candidate_1 to candidate_3, the resources that best match it. A kind, label or location filter leaves out resources that do not state it, so search without one before saying a resource does not exist, and ask the person when several match equally.',
     'Check availability before booking: slotlock_get_free_busy returns busy intervals and slotlock_find_next_available the earliest free slot of a given length, and slotlock_find_available_slots up to 50 of them to offer a person a choice; an answer is certain only when coverage.certainty is "certain".',
     'slotlock_create_event needs an idempotency_key: retry with the same key and arguments, never a new key for the same booking. slotlock_update_event and slotlock_delete_event need the event revision you last read as expected_revision.',
     'Times are RFC 3339 with an offset; intervals are half-open [start, end).',

package/agent-store-backend.d.ts

@@ -39,7 +39,6 @@ export declare function slotlockAgentErrorStatus(code: string): 400 | 404 | 409
  * store's client, used for the feed's head.
  */
 export declare function createSlotlockStoreChangeSource(store: SlotlockStore, sql: Sql): SlotlockAgentChangeSource;
-/** Bind the protocol server to the production store without giving a request control of tenancy. */
 export declare function createSlotlockStoreAgentBackend(store: SlotlockStore, options: SlotlockStoreAgentBackendOptions): SlotlockAgentCalendarBackend;
 export interface SlotlockStoreApplicationBackendOptions {
     /**
@@ -66,6 +65,12 @@ export interface SlotlockStoreApplicationBackendOptions {
      * approvals_unavailable; declining still works.
      */
     agentBackend?: SlotlockAgentCalendarBackend;
+    /**
+     * How `slotlock_import_holidays` fetches a calendar's url (RFC 0004 B1): give it a fetch that
+     * refuses private addresses (`createSlotlockGuardedFetch`). Unset: a url answers 400
+     * holiday_url_not_served and only the calendar's text is read.
+     */
+    holidayFetch?: typeof fetch;
 }
 /**
  * Run a granted approval's write as the agent that asked for it, in one transaction with the grant: