slotlock 0.8.0 → 0.9.0

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: