slotlock 0.2.0 → 0.5.0

package/agent-server.js

@@ -3,9 +3,10 @@ import { z } from 'zod';
 import { SLOTLOCK_MCP_APPS_EXTENSION, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, clientSupportsSlotlockMcpApp, } from './mcp-app.js';
 import { MCP_META_PROTOCOL_VERSION, MCP_META_SERVER_INFO, MCP_META_SUBSCRIPTION_ID, MCP_MISSING_REQUIRED_CLIENT_CAPABILITY, canonicalJson, checkModernMcpRequest, isRecord, openMcpEventStream, openRequestState, principalTag, sealRequestState, sha256Hex, stateSecrets, traceContextFrom, } from './mcp-modern.js';
 import { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, slotlockApplicationOperation, } from './application-api.js';
+import { SLOTLOCK_EVENT_OUTPUT as EVENT } from './event-schema.js';
 import { ignoreRejection } from './hooks.js';
 import { slotlockPackageVersion } from './package-version.js';
-import { SLOTLOCK_APPLICATION_REST_ROUTES, SLOTLOCK_REST_ROUTES, matchSlotlockRestRoute, restInputFromBody, restQueryInput, slotlockOpenApiDocument, } from './rest-api.js';
+import { SLOTLOCK_APPLICATION_REST_ROUTES, SLOTLOCK_REST_ROUTES, matchSlotlockRestRoute, parseIdempotencyKeyHeader, SLOTLOCK_PROBLEM_DOCS, slotlockProblem, restInputFromBody, restQueryInput, slotlockOpenApiDocument, } from './rest-api.js';
 import { SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, calendarEventRollingHorizon, } from './store.js';
 import { canonicalRecurrenceRule, expandCalendarEventOccurrences, isBookableRecurrenceRule, } from './sync.js';
 import { zonedOffsetMinutes, zonedWallTime } from './timezone.js';
@@ -59,17 +60,163 @@ 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);
 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}$/);
 const IDEMPOTENCY_KEY = z.string().trim().min(1).max(200);
 const REVISION = z.number().int().positive();
-// Output bounds mirror the trusted store's byte ceilings. A value admitted by a UTF-8 byte
-// ceiling can never exceed that many UTF-16 code units, so every valid stored/provider event is
-// serializable without truncating recurrence semantics or calendar identities.
-const TRUSTED_SUMMARY_OUTPUT_MAX = 4_096;
-const TRUSTED_TEXT_OUTPUT_MAX = 16_384;
-const TRUSTED_PERSON_NAME_OUTPUT_MAX = 1_024;
-const TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX = 1_000;
-const TRUSTED_REMINDER_MINUTES_OUTPUT_MAX = 366 * 24 * 60;
 const MAX_AGENT_WINDOW_MS = SLOTLOCK_CALENDAR_HORIZON_DAYS * 24 * 60 * 60 * 1_000;
+/** How many slots `slotlock_find_available_slots` lists at most, and over how many resources. */
+const MAX_LISTED_SLOTS = 50;
+const MAX_SLOT_RESOURCES = 20;
+/** `slotlock_hold_slots`, from a backend that holds; one without it answers `holds_unavailable`. */
+function holdSlots(backend, context, input) {
+    if (!backend.holdSlots)
+        throw new SlotlockAgentOperationError('holds_unavailable', 409);
+    return backend.holdSlots(context, input);
+}
+/** `slotlock_book_pool`, from a backend that books pools, as `holdSlots`. */
+function bookPool(backend, context, input) {
+    if (!backend.bookPool)
+        throw new SlotlockAgentOperationError('pools_unavailable', 409);
+    return backend.bookPool(context, input);
+}
+/** `slotlock_get_pool_availability`, from a backend that knows pools, as `holdSlots`. */
+function getPoolAvailability(backend, context, input) {
+    if (!backend.getPoolAvailability)
+        throw new SlotlockAgentOperationError('pools_unavailable', 409);
+    return backend.getPoolAvailability(context, input);
+}
+/** `slotlock_book_together`, from a backend that books bundles, as `holdSlots`. */
+function bookTogether(backend, context, input) {
+    if (!backend.bookTogether)
+        throw new SlotlockAgentOperationError('bundles_unavailable', 409);
+    return backend.bookTogether(context, input);
+}
+/** `slotlock_release_slots`, as `holdSlots`. */
+function releaseSlots(backend, context, input) {
+    if (!backend.releaseSlots)
+        throw new SlotlockAgentOperationError('holds_unavailable', 409);
+    return backend.releaseSlots(context, input);
+}
+/** Next-available searches one collective search may make, across its resources. */
+const MAX_TOGETHER_SEARCHES = 500;
+/**
+ * Times when at least `needed` of the resources are free together for the duration, earliest
+ * first. Each resource's next certain start at or after a candidate time comes from the backend's
+ * own search (hours, booking rules, coverage, as a single answer judges them); the candidate is
+ * the `needed`-th earliest of those starts, and it is a slot when that many start there. Otherwise
+ * the search moves on to it, where the resources that start earlier are asked again. A resource's
+ * start stays valid until the candidate passes it, so most are asked once per slot at most.
+ */
+async function freeTogether(resourceIds, needed, next, options) {
+    if (needed > resourceIds.length)
+        throw new SlotlockAgentOperationError('invalid_arguments', 400);
+    const known = new Map();
+    const slots = [];
+    let from = options.window.start.getTime();
+    let searches = 0;
+    while (slots.length < options.limit && from + options.durationMs <= options.window.end.getTime()) {
+        for (const resourceId of resourceIds) {
+            const start = known.get(resourceId);
+            if (start === null || (start !== undefined && start >= from))
+                continue;
+            if (++searches > MAX_TOGETHER_SEARCHES)
+                return slots;
+            const found = await next(resourceId, new Date(from).toISOString());
+            if (found === 'uncertain')
+                return 'uncertain';
+            known.set(resourceId, found ? Date.parse(found.start) : null);
+        }
+        const starts = resourceIds
+            .map((resourceId) => known.get(resourceId))
+            .filter((start) => typeof start === 'number')
+            .sort((a, b) => a - b);
+        const candidate = starts[needed - 1];
+        if (candidate === undefined)
+            return slots;
+        const free = resourceIds.filter((resourceId) => known.get(resourceId) === candidate);
+        if (free.length >= needed) {
+            slots.push({
+                resource_id: free[0],
+                start: new Date(candidate).toISOString(),
+                end: new Date(candidate + options.durationMs).toISOString(),
+                resource_ids: free,
+            });
+            from = candidate + options.durationMs;
+        }
+        else {
+            from = candidate;
+        }
+    }
+    return slots;
+}
+/**
+ * Slots for `slotlock_find_available_slots`, from the backend's own next-available search, so each
+ * one is checked against busy time, the resource's hours and coverage exactly as a single answer
+ * is. Each resource's earliest slot first, then the next one after whichever slot was listed: at
+ * most one search per resource plus one per listed slot. Like a single answer, the list is certain
+ * only when every resource's coverage is, and empty otherwise.
+ */
+async function findAvailableSlots(backend, context, input) {
+    const end = input.end;
+    const durationMs = input.duration_minutes * 60_000;
+    const limit = input.limit;
+    const window = { start: new Date(input.start), end: new Date(end) };
+    const coverage = (certain) => ({
+        start: window.start.toISOString(),
+        end: window.end.toISOString(),
+        certainty: certain ? 'certain' : 'uncertain',
+        reason: certain ? null : 'coverage_incomplete',
+    });
+    const next = async (resourceId, from) => {
+        const found = await backend.findNextAvailable(context, {
+            resource_ids: [resourceId],
+            start: from,
+            end,
+            duration_minutes: input.duration_minutes,
+        });
+        if (found.coverage?.certainty !== 'certain') {
+            return 'uncertain';
+        }
+        return typeof found.start === 'string' && typeof found.end === 'string'
+            ? { resource_id: resourceId, start: found.start, end: found.end }
+            : null;
+    };
+    const resourceIds = [...new Set(input.resource_ids)];
+    if (typeof input.require_free === 'number') {
+        const together = await freeTogether(resourceIds, input.require_free, next, {
+            window,
+            durationMs,
+            limit,
+        });
+        return together === 'uncertain'
+            ? { slots: [], coverage: coverage(false) }
+            : { slots: together, coverage: coverage(true) };
+    }
+    const earliest = (a, b) => Date.parse(a.start) - Date.parse(b.start) || a.resource_id.localeCompare(b.resource_id);
+    const heads = [];
+    for (const resourceId of resourceIds) {
+        const head = await next(resourceId, window.start.toISOString());
+        if (head === 'uncertain')
+            return { slots: [], coverage: coverage(false) };
+        if (head)
+            heads.push(head);
+    }
+    const slots = [];
+    while (slots.length < limit && heads.length > 0) {
+        heads.sort(earliest);
+        const listed = heads.shift();
+        slots.push(listed);
+        if (slots.length === limit || window.end.getTime() - Date.parse(listed.end) < durationMs)
+            continue;
+        const after = await next(listed.resource_id, listed.end);
+        if (after === 'uncertain')
+            return { slots: [], coverage: coverage(false) };
+        if (after)
+            heads.push(after);
+    }
+    return { slots, coverage: coverage(true) };
+}
 /** The longest slot `slotlock_find_next_available` can look for: the whole search window. */
 const MAX_SLOT_MINUTES = SLOTLOCK_CALENDAR_HORIZON_DAYS * 24 * 60;
 const MAX_EVENT_DURATION_MS = SLOTLOCK_MAX_EVENT_DURATION_DAYS * 24 * 60 * 60 * 1_000;
@@ -95,41 +242,6 @@ const COVERAGE = z
     reason: z.string().max(100).nullable(),
 })
     .strict();
-const ORGANIZER = z
-    .object({
-    address: z.string().email().max(320),
-    name: z.string().trim().max(TRUSTED_PERSON_NAME_OUTPUT_MAX).nullable(),
-})
-    .strict();
-const ATTENDEE = z
-    .object({
-    address: z.string().email().max(320),
-    name: z.string().trim().max(TRUSTED_PERSON_NAME_OUTPUT_MAX).nullable(),
-    role: z.enum(['chair', 'required', 'optional', 'non_participant']),
-    participation_status: z.enum([
-        'needs_action',
-        'accepted',
-        'declined',
-        'tentative',
-        'delegated',
-    ]),
-    rsvp: z.boolean(),
-})
-    .strict();
-const REMINDER = z
-    .object({
-    minutes_before: z.number().int().min(0).max(TRUSTED_REMINDER_MINUTES_OUTPUT_MAX),
-    channel: z.enum(['display', 'email']),
-})
-    .strict();
-const RECURRENCE_EXCEPTION = z
-    .object({
-    recurrence_id: DATE_TIME,
-    cancelled: z.boolean(),
-    starts_at: DATE_TIME.nullable(),
-    ends_at: DATE_TIME.nullable(),
-})
-    .strict();
 const ORGANIZER_INPUT = z
     .object({
     address: z.string().email().max(320),
@@ -187,30 +299,6 @@ const MCP_INITIALIZE_PARAMS = z
     _meta: z.record(z.string(), z.unknown()).optional(),
 })
     .passthrough();
-const EVENT = z
-    .object({
-    id: EVENT_ID,
-    resource_id: RESOURCE_ID,
-    starts_at: DATE_TIME,
-    ends_at: DATE_TIME,
-    timezone: z.string().min(1).max(100),
-    title: z.string().max(TRUSTED_SUMMARY_OUTPUT_MAX).nullable(),
-    description: z.string().max(TRUSTED_TEXT_OUTPUT_MAX).nullable(),
-    location: z.string().max(TRUSTED_TEXT_OUTPUT_MAX).nullable(),
-    organizer: ORGANIZER.nullable(),
-    attendees: z.array(ATTENDEE).max(100),
-    reminders: z.array(REMINDER).max(20),
-    status: z.enum(['tentative', 'confirmed', 'cancelled']),
-    transparency: z.enum(['opaque', 'transparent']),
-    sequence: z.number().int().nonnegative(),
-    revision: REVISION,
-    recurrence_rule: z.string().max(TRUSTED_SUMMARY_OUTPUT_MAX).nullable(),
-    recurrence_exceptions: z
-        .array(RECURRENCE_EXCEPTION)
-        .max(TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX),
-    recurrence_id: DATE_TIME.nullable(),
-})
-    .strict();
 /**
  * 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
@@ -243,6 +331,12 @@ const OPERATION_SCOPES = Object.freeze({
     slotlock_list_resources: 'read',
     slotlock_get_free_busy: 'read',
     slotlock_find_next_available: 'read',
+    slotlock_find_available_slots: 'read',
+    slotlock_hold_slots: 'write',
+    slotlock_book_together: 'write',
+    slotlock_book_pool: 'write',
+    slotlock_get_pool_availability: 'read',
+    slotlock_release_slots: 'write',
     slotlock_create_event: 'write',
     slotlock_get_event: 'read',
     slotlock_list_events: 'read',
@@ -263,11 +357,25 @@ function principalScopesCover(principal, operation) {
 export class SlotlockAgentOperationError extends Error {
     code;
     status;
-    constructor(code, status) {
+    /**
+     * What the refusal is about, beside its code (the resource a bundle was refused on, say): at most
+     * five snake_case names with text values of up to 200 characters; anything else is dropped. Every
+     * protocol carries them next to `code`.
+     */
+    details;
+    constructor(code, status, details) {
         super(code);
         this.name = 'SlotlockAgentOperationError';
         this.code = /^[a-z][a-z0-9_]{0,63}$/.test(code) ? code : 'operation_failed';
-        this.status = [400, 403, 404, 409, 429, 503].includes(status) ? status : 500;
+        this.status = [400, 403, 404, 409, 410, 429, 503].includes(status) ? status : 500;
+        const kept = Object.entries(details ?? {})
+            .filter(([name, value]) => /^[a-z][a-z0-9_]{0,39}$/.test(name) &&
+            name !== 'code' &&
+            typeof value === 'string' &&
+            value.length <= 200)
+            .slice(0, 5);
+        if (kept.length > 0)
+            this.details = Object.freeze(Object.fromEntries(kept));
     }
 }
 const EXAMPLE_RESOURCE_ID = '0f8b6c1e-2d4a-4c7e-9b1a-3e5f7a9c2d4b';
@@ -290,6 +398,8 @@ const EVENT_CREATE_INPUT = z
     reminders: z.array(REMINDER_INPUT).max(20).optional(),
     idempotency_key: IDEMPOTENCY_KEY,
     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(),
 })
     .strict()
     .refine((value) => boundedEventSpan(value.starts_at, value.ends_at));
@@ -297,11 +407,12 @@ const OPERATION_DEFINITIONS = [
     {
         name: 'slotlock_list_resources',
         title: 'List calendar resources',
-        description: 'List resources visible to the authenticated tenant principal.',
+        description: 'List resources visible to the authenticated tenant principal, with the pool each belongs to (a vehicle class, a room type). With pool, only that pool\'s members, in the order slotlock_book_pool tries them.',
         input: z
             .object({
             cursor: z.string().max(500).optional(),
             limit: z.number().int().min(1).max(100).default(50),
+            pool: POOL.optional(),
         })
             .strict(),
         output: z
@@ -312,6 +423,7 @@ const OPERATION_DEFINITIONS = [
                 id: RESOURCE_ID,
                 external_ref: z.string().max(500).nullable(),
                 timezone: z.string().min(1).max(100),
+                pool: POOL.optional(),
             })
                 .strict())
                 .max(100),
@@ -376,6 +488,40 @@ const OPERATION_DEFINITIONS = [
         invoke: 'findNextAvailable',
         example: { resource_ids: [EXAMPLE_RESOURCE_ID], ...EXAMPLE_WINDOW, duration_minutes: 120 },
     },
+    {
+        name: 'slotlock_find_available_slots',
+        title: 'Find available slots',
+        description: '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.',
+        input: z
+            .object({
+            resource_ids: z.array(RESOURCE_ID).min(1).max(MAX_SLOT_RESOURCES),
+            start: DATE_TIME,
+            end: DATE_TIME,
+            duration_minutes: z.number().int().min(1).max(MAX_SLOT_MINUTES),
+            limit: z.number().int().min(1).max(MAX_LISTED_SLOTS).default(10),
+            require_free: z.number().int().min(1).max(MAX_SLOT_RESOURCES).optional(),
+        })
+            .strict()
+            .refine(boundedAgentWindow),
+        output: z
+            .object({
+            slots: z
+                .array(z
+                .object({
+                resource_id: RESOURCE_ID,
+                start: DATE_TIME,
+                end: DATE_TIME,
+                resource_ids: z.array(RESOURCE_ID).min(1).max(MAX_SLOT_RESOURCES).optional(),
+            })
+                .strict())
+                .max(MAX_LISTED_SLOTS),
+            coverage: COVERAGE,
+        })
+            .strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: findAvailableSlots,
+        example: { resource_ids: [EXAMPLE_RESOURCE_ID], ...EXAMPLE_WINDOW, duration_minutes: 60, limit: 10 },
+    },
     {
         name: 'slotlock_create_event',
         title: 'Create resource event',
@@ -393,6 +539,86 @@ const OPERATION_DEFINITIONS = [
             idempotency_key: 'create-handover-2027-03-02',
         },
     },
+    {
+        name: 'slotlock_book_pool',
+        title: 'Book from a pool',
+        description: 'Book any one member of a pool (a vehicle class, a room type) for a time: members are tried in a fixed order 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.',
+        input: z
+            .object({
+            pool: POOL,
+            starts_at: DATE_TIME,
+            ends_at: DATE_TIME,
+            timezone: z.string().min(1).max(100),
+            title: z.string().trim().min(1).max(500).optional(),
+            idempotency_key: IDEMPOTENCY_KEY,
+        })
+            .strict()
+            .refine((value) => boundedEventSpan(value.starts_at, value.ends_at)),
+        output: z.object({ event: EVENT, replayed: z.boolean() }).strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: bookPool,
+        example: {
+            pool: 'van',
+            starts_at: '2027-03-02T09:00:00Z',
+            ends_at: '2027-03-03T09:00:00Z',
+            timezone: 'Europe/London',
+            title: 'Van hire',
+            idempotency_key: 'van-hire-2027-03-02',
+        },
+    },
+    {
+        name: 'slotlock_get_pool_availability',
+        title: 'Get pool availability',
+        description: '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.',
+        input: z
+            .object({ pool: POOL, start: DATE_TIME, end: DATE_TIME })
+            .strict()
+            .refine(boundedAgentWindow),
+        output: z
+            .object({
+            pool: POOL,
+            members: z.number().int().min(1).max(100),
+            intervals: z
+                .array(z
+                .object({ start: DATE_TIME, end: DATE_TIME, free: z.number().int().min(0).max(100) })
+                .strict())
+                .max(20_001),
+            coverage: COVERAGE,
+        })
+            .strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: getPoolAvailability,
+        example: { pool: 'van', ...EXAMPLE_WINDOW },
+    },
+    {
+        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.',
+        input: z
+            .object({
+            resource_ids: z.array(RESOURCE_ID).min(2).max(MAX_SLOT_RESOURCES),
+            starts_at: DATE_TIME,
+            ends_at: DATE_TIME,
+            timezone: z.string().min(1).max(100),
+            title: z.string().trim().min(1).max(500).optional(),
+            idempotency_key: IDEMPOTENCY_KEY,
+        })
+            .strict()
+            .refine((value) => boundedEventSpan(value.starts_at, value.ends_at)),
+        output: z
+            .object({ events: z.array(EVENT).min(2).max(MAX_SLOT_RESOURCES), replayed: z.boolean() })
+            .strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: bookTogether,
+        example: {
+            resource_ids: [EXAMPLE_RESOURCE_ID, '1f8b6c1e-2d4a-4c7e-9b1a-3e5f7a9c2d4b'],
+            starts_at: '2027-03-02T09:00:00Z',
+            ends_at: '2027-03-02T10:00:00Z',
+            timezone: 'Europe/London',
+            title: 'Handover with driver',
+            idempotency_key: 'bundle-handover-2027-03-02',
+        },
+    },
     {
         name: 'slotlock_get_event',
         title: 'Get resource event',
@@ -427,7 +653,7 @@ const OPERATION_DEFINITIONS = [
     {
         name: 'slotlock_update_event',
         title: 'Update resource event',
-        description: 'Apply an expected-revision event patch and rematerialize occupancy atomically.',
+        description: 'Apply an expected-revision event patch and rematerialize occupancy atomically. With expected_resource_id, the resource you read the event on, an event since moved elsewhere is not found.',
         input: z
             .object({
             event_id: EVENT_ID,
@@ -447,6 +673,8 @@ const OPERATION_DEFINITIONS = [
             recurrence_rule: RECURRENCE_RULE.nullable().optional(),
             recurrence_exceptions: z.array(RECURRENCE_EXCEPTION_INPUT).max(500).optional(),
             idempotency_key: IDEMPOTENCY_KEY,
+            // Last, so the generated clients that take optional arguments by position keep their order.
+            expected_resource_id: RESOURCE_ID.optional(),
         })
             .strict()
             .refine((value) => value.starts_at !== undefined ||
@@ -504,8 +732,65 @@ const OPERATION_DEFINITIONS = [
             idempotency_key: 'cancel-handover-2027-03-02',
         },
     },
+    {
+        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.',
+        input: z
+            .object({
+            slots: z
+                .array(z
+                .object({ resource_id: RESOURCE_ID, start: DATE_TIME, end: DATE_TIME })
+                .strict()
+                .refine((value) => boundedEventSpan(value.start, value.end)))
+                .min(1)
+                .max(5),
+            ttl_seconds: z.number().int().min(30).max(900).default(300),
+            idempotency_key: IDEMPOTENCY_KEY,
+        })
+            .strict(),
+        output: z
+            .object({
+            group_id: HOLD_ID,
+            holds: z
+                .array(z
+                .object({
+                hold_id: HOLD_ID,
+                resource_id: RESOURCE_ID,
+                start: DATE_TIME,
+                end: DATE_TIME,
+                expires_at: DATE_TIME,
+            })
+                .strict())
+                .max(5),
+            refused: z
+                .array(z.object({ index: z.number().int().min(0).max(4), code: z.string().max(64) }).strict())
+                .max(5),
+        })
+            .strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: holdSlots,
+        example: {
+            slots: [
+                { resource_id: EXAMPLE_RESOURCE_ID, start: '2027-03-02T09:00:00Z', end: '2027-03-02T10:00:00Z' },
+                { resource_id: EXAMPLE_RESOURCE_ID, start: '2027-03-02T14:00:00Z', end: '2027-03-02T15:00:00Z' },
+            ],
+            ttl_seconds: 300,
+            idempotency_key: 'hold-handover-2027-03-02',
+        },
+    },
+    {
+        name: 'slotlock_release_slots',
+        title: 'Release held slots',
+        description: '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.',
+        input: z.object({ hold_id: HOLD_ID }).strict(),
+        output: z.object({ released: z.boolean() }).strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: releaseSlots,
+        example: { hold_id: '7d3f8c2a-4b1e-4f6a-9c2d-1e5b7a9f3c4d' },
+    },
 ];
-const FORMATS_WITHOUT_PATTERN = new Set(['date-time', 'email']);
+const FORMATS_WITHOUT_PATTERN = new Set(['date-time', 'email', 'uuid']);
 function toJsonSchema(schema, io) {
     // Zod's own converter: zod-to-json-schema reads only Zod 3 schemas (for a Zod 4 one it returns {})
     // and its repository is archived. A type JSON Schema cannot express throws rather than vanishing.
@@ -514,7 +799,7 @@ function toJsonSchema(schema, io) {
         io,
         unrepresentable: 'throw',
         override: ({ jsonSchema }) => {
-            // Zod 4.6 writes its validation regex beside `format` for dates and emails (288 and 102
+            // Zod 4.6 writes its validation regex beside `format` for dates, emails and UUIDs (288 and 102
             // characters, on 60 fields): the format already says it, and every agent reads the list.
             if (FORMATS_WITHOUT_PATTERN.has(String(jsonSchema.format)))
                 delete jsonSchema.pattern;
@@ -603,18 +888,32 @@ export function slotlockAgentTools() {
             idempotentHint: operation.risk.idempotent,
             openWorldHint: false,
         },
-        ...(operation.risk.readOnly
-            ? {
-                _meta: {
-                    ui: {
-                        resourceUri: SLOTLOCK_MCP_APP_RESOURCE_URI,
-                        visibility: ['model', 'app'],
-                    },
-                },
-            }
-            : {}),
+        // Reads render in the calendar view, which may call them again. A write is the model's to make
+        // through the normal path, where a person can be asked to confirm it: never a view's, which
+        // MCP Apps would otherwise allow (visibility defaults to model and app).
+        // Held slots render there too, to pick from, but only the model holds.
+        _meta: {
+            ui: operation.risk.readOnly
+                ? { resourceUri: SLOTLOCK_MCP_APP_RESOURCE_URI, visibility: ['model', 'app'] }
+                : operation.name === 'slotlock_hold_slots'
+                    ? { resourceUri: SLOTLOCK_MCP_APP_RESOURCE_URI, visibility: ['model'] }
+                    : { visibility: ['model'] },
+        },
     }));
 }
+/** The resource and interval a refused write asked for, as an overlap's problem details name them. */
+function refusedInterval(input) {
+    const named = {};
+    const fields = [
+        ['resource_id', input.resource_id],
+        ['start', input.starts_at ?? input.start],
+        ['end', input.ends_at ?? input.end],
+    ];
+    for (const [name, value] of fields)
+        if (typeof value === 'string')
+            named[name] = value;
+    return named;
+}
 function json(status, body, extraHeaders = {}) {
     return new Response(JSON.stringify(body), {
         status,
@@ -874,7 +1173,11 @@ export async function invokeSlotlockAgentOperation(args) {
             if (halt)
                 return { ok: false, status: halt.status, code: halt.code };
         }
-        const method = args.options.backend[operation.invoke];
+        const invoke = operation.invoke;
+        const backend = args.options.backend;
+        const method = typeof invoke === 'function'
+            ? (context, input) => invoke(backend, context, input)
+            : backend[invoke];
         const context = {
             principal,
             operation: operation.name,
@@ -882,7 +1185,7 @@ export async function invokeSlotlockAgentOperation(args) {
         };
         if (args.trace)
             context.trace = args.trace;
-        const data = await method.call(args.options.backend, context, parsed.data);
+        const data = await method.call(backend, context, parsed.data);
         if (!operation.output.safeParse(data).success) {
             // Neither the result nor the schema's complaint about it: either may hold tenant data.
             reportUnexpected(args.options.onError, Object.assign(new Error(`The backend's ${operation.name} result does not match the operation's output schema`), { code: 'invalid_backend_result' }), resolvedOperation);
@@ -892,7 +1195,12 @@ export async function invokeSlotlockAgentOperation(args) {
     }
     catch (error) {
         if (error instanceof SlotlockAgentOperationError) {
-            return { ok: false, status: error.status, code: error.code };
+            return {
+                ok: false,
+                status: error.status,
+                code: error.code,
+                ...(error.details ? { details: error.details } : {}),
+            };
         }
         reportUnexpected(args.options.onError, error, resolvedOperation);
         return { ok: false, status: 500, code: 'internal_error' };
@@ -1152,12 +1460,14 @@ function validateSubscriptions(value) {
         }
         return setting;
     };
+    const maxTotal = bounded('maxTotal', 1, 10_000, 256);
     return {
         pollIntervalMs: bounded('pollIntervalMs', 1_000, 300_000, 10_000),
         maxDurationMs: bounded('maxDurationMs', 60_000, 86_400_000, 900_000),
         keepAliveMs: bounded('keepAliveMs', 1_000, 60_000, 15_000),
         maxPerPrincipal: bounded('maxPerPrincipal', 1, 64, 4),
-        maxTotal: bounded('maxTotal', 1, 10_000, 256),
+        maxPerTenant: bounded('maxPerTenant', 1, 10_000, maxTotal),
+        maxTotal,
     };
 }
 /**
@@ -1203,13 +1513,15 @@ function unref(timer) {
 /** 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).',
-    'Check availability before booking: slotlock_get_free_busy returns busy intervals and slotlock_find_next_available the earliest free slot of a given length; an answer is certain only when coverage.certainty is "certain".',
+    '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).',
     'A failed call returns {"error":{"code":"…"}}; read the code before retrying (overlap means the slot is taken).',
 ].join(' ');
 const WRITE_OPERATIONS = new Set([
     'slotlock_create_event',
+    'slotlock_book_together',
+    'slotlock_book_pool',
     'slotlock_update_event',
     'slotlock_delete_event',
 ]);
@@ -1242,7 +1554,15 @@ function validateConfirmation(value) {
     if (!Number.isInteger(ttlSeconds) || ttlSeconds < 30 || ttlSeconds > 3_600) {
         throw invalid('ttlSeconds');
     }
-    return { operations: new Set(value.operations), keys, ttlMs: ttlSeconds * 1_000 };
+    if (value.consumeAcceptance !== undefined && typeof value.consumeAcceptance !== 'function') {
+        throw invalid('consumeAcceptance');
+    }
+    return {
+        operations: new Set(value.operations),
+        keys,
+        ttlMs: ttlSeconds * 1_000,
+        ...(value.consumeAcceptance ? { consumeAcceptance: value.consumeAcceptance } : {}),
+    };
 }
 /** An empty `elicitation` object declares form mode (2026-07-28 client/elicitation §Capabilities). */
 function clientSupportsFormElicitation(capabilities) {
@@ -1451,10 +1771,14 @@ function promptSeries(series, zone) {
         const booked = expandCalendarEventOccurrences(content, horizon);
         beyond = promptSeriesEnd(series.rule, booked.length, horizon.end);
         const length = end.getTime() - start.getTime();
+        // Moved: by an exception, to another time or length. One the clocks change inside, or that
+        // the store ends where the next starts, is where its rule puts it.
+        const excepted = new Set(exceptions.flatMap((exception) => exception.cancelled !== true && exception.start ? [exception.recurrenceId.getTime()] : []));
         moved = promptMoved(booked.flatMap((occurrence) => {
             const from = new Date(occurrence.recurrenceId);
-            const shifted = occurrence.start.getTime() !== from.getTime() ||
-                occurrence.end.getTime() - occurrence.start.getTime() !== length;
+            const shifted = excepted.has(from.getTime()) &&
+                (occurrence.start.getTime() !== from.getTime() ||
+                    occurrence.end.getTime() - occurrence.start.getTime() !== length);
             return shifted && Number.isFinite(from.getTime())
                 ? [{ from, start: occurrence.start, end: occurrence.end }]
                 : [];
@@ -1595,6 +1919,23 @@ function confirmationLookup(options, context) {
  * part has its own bound, so nothing is cut from the end.
  */
 async function confirmationMessage(operation, input, lookup) {
+    if (operation === 'slotlock_book_pool') {
+        const zone = promptZone([[input.timezone, false]]);
+        const title = typeof input.title === 'string' && input.title.length > 0 ? `: ${promptQuoted(input.title)}` : '';
+        return `Book any one of pool ${promptText(input.pool, 100)} for ${promptRange(promptInstantOf(input.starts_at), promptInstantOf(input.ends_at), zone)}${title}.`;
+    }
+    if (operation === 'slotlock_book_together') {
+        const ids = Array.isArray(input.resource_ids) ? input.resource_ids : [];
+        const resources = await Promise.all(ids.map((id) => lookup.resource(id)));
+        const zone = promptZone([
+            ...resources.map((resource) => [resource.timezone, true]),
+            [input.timezone, false],
+        ]);
+        const labels = resources.map((resource) => resource.label);
+        const all = labels.length > 1 ? `${labels.slice(0, -1).join(', ')} and ${labels.at(-1)}` : (labels[0] ?? '');
+        const title = typeof input.title === 'string' && input.title.length > 0 ? `: ${promptQuoted(input.title)}` : '';
+        return `Book ${all} together, all or none, for ${promptRange(promptInstantOf(input.starts_at), promptInstantOf(input.ends_at), zone)}${title}.`;
+    }
     if (operation === 'slotlock_create_event') {
         const resource = await lookup.resource(input.resource_id);
         const zone = promptZone([
@@ -1673,8 +2014,18 @@ async function confirmationMessage(operation, input, lookup) {
         changes.push('no longer repeats');
     }
     else if (typeof rule === 'string' && reshaped && seriesStart && seriesEnd) {
-        const seriesZone = input.timezone ?? event?.timezone ?? 'UTC';
-        changes.push(`so it books ${promptSeries({ start: seriesStart, end: seriesEnd, timezone: seriesZone, rule, exceptions }, zone)}`);
+        const seriesZone = input.timezone ?? event?.timezone;
+        if (seriesZone === undefined) {
+            // An unread event and no new zone: the store expands in the event's own, which the question
+            // cannot know, so it states no dates.
+            changes.push(`repeats ${promptRule(rule)}, on dates that follow the event's existing time zone`);
+            if (input.recurrence_exceptions !== undefined) {
+                changes.push(`exceptions to ${promptRequestedExceptions(input.recurrence_exceptions, zone)}`);
+            }
+        }
+        else {
+            changes.push(`so it books ${promptSeries({ start: seriesStart, end: seriesEnd, timezone: seriesZone, rule, exceptions }, zone)}`);
+        }
     }
     else {
         if (typeof input.recurrence_rule === 'string') {
@@ -1771,6 +2122,22 @@ function a2aError(id, code, message, info) {
         },
     });
 }
+/**
+ * The request's principal, or the error when `authenticate` throws a 503
+ * `SlotlockAgentOperationError`, as createSlotlockApiKeyAuthenticator does when its lookup queue is
+ * full: no answer about the credential, so the client is told to retry rather than that it is
+ * anonymous.
+ */
+async function principalOrBusy(authenticate, request) {
+    try {
+        return await authenticate(request);
+    }
+    catch (error) {
+        if (error instanceof SlotlockAgentOperationError && error.status === 503)
+            return error;
+        throw error;
+    }
+}
 /** Map a request path onto the server's base path; `null` when it lies outside it. */
 function routePath(pathname, basePath) {
     if (basePath === '')
@@ -1978,6 +2345,17 @@ export function createSlotlockAgentServer(options) {
                     operation,
                     argsDigest: gate.argsDigest,
                 });
+                if (gate.decision === 'accepted' && confirmation.consumeAcceptance) {
+                    // Once only: the same accepted state sent again is refused, on any server.
+                    const state = openRequestState(confirmation.keys, params.requestState)?.payload;
+                    const nonce = state?.nonce;
+                    if (typeof nonce !== 'string' || typeof state?.exp !== 'number') {
+                        gate.decision = 'invalid';
+                    }
+                    else if (!(await confirmation.consumeAcceptance({ nonce, expiresAt: new Date(state.exp) }))) {
+                        gate.decision = 'invalid';
+                    }
+                }
                 // Before the call it decides, as on every other protocol.
                 emit({ type: 'confirmation', operation, outcome: CONFIRMATION_OUTCOME[gate.decision] });
                 return gate.decision === 'accepted' ? null : CONFIRMATION_HALT[gate.decision];
@@ -2035,7 +2413,7 @@ export function createSlotlockAgentServer(options) {
         if (!outcome.ok && INTERNAL_FAILURES.has(outcome.code)) {
             return modernError(500, id, -32603, 'Internal error');
         }
-        return modernResult(id, slotlockMcpToolResult(outcome.ok ? outcome : { ok: false, code: outcome.code }));
+        return modernResult(id, slotlockMcpToolResult(outcome));
     }
     /** A backend failure behind a resources/* or subscriptions/* request, as its JSON-RPC error. */
     const modernFailure = (id, outcome) => {
@@ -2185,15 +2563,48 @@ export function createSlotlockAgentServer(options) {
             return modernError(503, id, -32603, 'Server is shutting down');
         const principalKey = `${principal.tenantRef}\0${principal.subject}`;
         let held = 0;
-        for (const open of openSubscriptions)
+        let heldByTenant = 0;
+        for (const open of openSubscriptions) {
             if (open.principalKey === principalKey)
                 held += 1;
+            if (open.tenantRef === principal.tenantRef)
+                heldByTenant += 1;
+        }
+        if (openSubscriptions.size >= subscriptionPolicy.maxTotal &&
+            held < subscriptionPolicy.maxPerPrincipal &&
+            heldByTenant < subscriptionPolicy.maxPerTenant) {
+            // A full server is shared out: a tenant holding fewer than the one holding most, less one,
+            // ends that tenant's oldest stream, so many tenants within their share cannot keep another
+            // from holding any. A slot still opening has nothing to end yet.
+            const streamsOf = new Map();
+            for (const open of openSubscriptions) {
+                if (!open.streaming)
+                    continue;
+                const streams = streamsOf.get(open.tenantRef);
+                if (streams)
+                    streams.push(open);
+                else
+                    streamsOf.set(open.tenantRef, [open]);
+            }
+            let most = [];
+            for (const streams of streamsOf.values())
+                if (streams.length > most.length)
+                    most = streams;
+            if (most.length > heldByTenant + 1)
+                most[0]?.end('preempted');
+        }
         if (openSubscriptions.size >= subscriptionPolicy.maxTotal ||
-            held >= subscriptionPolicy.maxPerPrincipal) {
+            held >= subscriptionPolicy.maxPerPrincipal ||
+            heldByTenant >= subscriptionPolicy.maxPerTenant) {
             return modernError(429, id, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, 'Too many subscriptions');
         }
         // The slot is held while access is checked, so concurrent opens cannot overshoot the caps.
-        const slot = { principalKey, end: (_reason) => { } };
+        const slot = {
+            principalKey,
+            tenantRef: principal.tenantRef,
+            streaming: false,
+            end: () => { },
+        };
         openSubscriptions.add(slot);
         let streaming = false;
         try {
@@ -2257,6 +2668,7 @@ export function createSlotlockAgentServer(options) {
             });
         }
         slot.end = end;
+        slot.streaming = true;
         stream.send({
             jsonrpc: '2.0',
             method: 'notifications/subscriptions/acknowledged',
@@ -2432,7 +2844,12 @@ export function createSlotlockAgentServer(options) {
         }
         catch (error) {
             if (error instanceof SlotlockAgentOperationError) {
-                return { ok: false, status: error.status, code: error.code };
+                return {
+                    ok: false,
+                    status: error.status,
+                    code: error.code,
+                    ...(error.details ? { details: error.details } : {}),
+                };
             }
             reportUnexpected(options.onError, error, definition.name);
             return { ok: false, status: 500, code: 'internal_error' };
@@ -2444,7 +2861,12 @@ export function createSlotlockAgentServer(options) {
      * for, so a guarded write answers 428 `confirmation_required`.
      */
     async function restCall(request, path, url) {
-        const refuse = (status, code, headers = {}) => json(status, { error: { code } }, headers);
+        // Every refusal is RFC 9457 problem details, still carrying `error.code`.
+        const refuse = (status, code, headers = {}, extensions = {}) => json(status, slotlockProblem(status, code, extensions), {
+            'Content-Type': 'application/problem+json',
+            Link: `<${SLOTLOCK_PROBLEM_DOCS}>; rel="describedby"; type="text/html"`,
+            ...headers,
+        });
         if (path === '/openapi.json') {
             return request.method === 'GET'
                 ? json(200, openApi)
@@ -2463,7 +2885,10 @@ export function createSlotlockAgentServer(options) {
                 return refuse(403, 'origin_not_allowed');
             }
         }
-        const principal = await options.authenticate(request);
+        const principal = await principalOrBusy(options.authenticate, request);
+        if (principal instanceof SlotlockAgentOperationError) {
+            return refuse(503, principal.code, { 'Retry-After': '1' });
+        }
         if (!principal ||
             !isCanonicalPrincipalIdentity(principal.subject) ||
             !isCanonicalPrincipalIdentity(principal.tenantRef)) {
@@ -2516,6 +2941,28 @@ export function createSlotlockAgentServer(options) {
         if (Object.keys(params).some((name) => Object.hasOwn(given, name))) {
             return refuseCall(400, 'invalid_arguments');
         }
+        // A write's retry identity may come as the Idempotency-Key header (a Structured Field String,
+        // draft-ietf-httpapi-idempotency-key-header-08), where HTTP clients put it, as well as its
+        // `idempotency_key` argument. On an operation that keeps none it is refused rather than
+        // ignored: a key that was dropped would promise a replay it never gives.
+        const inputSchema = restInputSchemas.get(route.operation);
+        const idempotencyHeader = request.headers.get('idempotency-key');
+        if (idempotencyHeader !== null) {
+            if (!Object.hasOwn(inputSchema?.properties ?? {}, 'idempotency_key')) {
+                return refuseCall(400, 'idempotency_key_not_supported');
+            }
+            const key = parseIdempotencyKeyHeader(idempotencyHeader);
+            if (key === null)
+                return refuseCall(400, 'invalid_idempotency_key');
+            if (Object.hasOwn(given, 'idempotency_key') && given.idempotency_key !== key) {
+                return refuseCall(400, 'invalid_arguments');
+            }
+            given = { ...given, idempotency_key: key };
+        }
+        else if (inputSchema?.required?.includes('idempotency_key') &&
+            !Object.hasOwn(given, 'idempotency_key')) {
+            return refuseCall(400, 'idempotency_key_required');
+        }
         const outcome = isSlotlockApplicationOperation(route.operation)
             ? await invokeApplicationOperation(slotlockApplicationOperation(route.operation), principal, { ...given, ...params }, request, trace)
             : await invokeSlotlockAgentOperation({
@@ -2530,7 +2977,16 @@ export function createSlotlockAgentServer(options) {
         report(status);
         if (outcome.ok)
             return json(200, outcome.data);
-        return refuse(status, internal ? 'internal_error' : outcome.code);
+        if (internal)
+            return refuse(status, 'internal_error');
+        // The same key with another request is 422 (the Idempotency-Key draft); on MCP and A2A, where
+        // no status is seen, it is the same code.
+        if (outcome.code === 'idempotency_conflict')
+            return refuse(422, outcome.code);
+        return refuse(status, outcome.code, {}, {
+            ...(outcome.code === 'overlap' ? refusedInterval(given) : {}),
+            ...outcome.details,
+        });
     }
     return {
         manifest,
@@ -2576,6 +3032,9 @@ export function createSlotlockAgentServer(options) {
                     return json(health.ready ? 200 : 503, {
                         status: health.ready ? 'ready' : 'not_ready',
                         version: SLOTLOCK_AGENT_SERVER_VERSION,
+                        // The time zone rules this process resolves zones with: when they change, maintenance
+                        // finds the bookings whose wall time moved (store.followZoneRules).
+                        tzdata: process.versions.tz ?? null,
                         checks: [...health.checks]
                             .slice(0, 100)
                             .map((check) => (/^[a-z][a-z0-9_-]{0,63}$/.test(check) ? check : 'invalid')),
@@ -2585,6 +3044,7 @@ export function createSlotlockAgentServer(options) {
                     return json(503, {
                         status: 'not_ready',
                         version: SLOTLOCK_AGENT_SERVER_VERSION,
+                        tzdata: process.versions.tz ?? null,
                         checks: [],
                     });
                 }
@@ -2607,7 +3067,17 @@ export function createSlotlockAgentServer(options) {
                     return json(403, rpcError(null, -32600, 'Origin not allowed'));
                 }
             }
-            const principal = await options.authenticate(request);
+            const principal = await principalOrBusy(options.authenticate, request);
+            if (principal instanceof SlotlockAgentOperationError) {
+                // As `slotlock serve` answers it: A2A names the reason in an ErrorInfo, as for a rate limit.
+                const error = { code: -32603, message: 'Server is busy' };
+                const info = {
+                    '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+                    reason: 'SERVER_BUSY',
+                    domain: 'slotlock',
+                };
+                return json(503, { jsonrpc: '2.0', id: null, error: path === '/a2a' ? { ...error, data: [info] } : error }, { 'Retry-After': '1' });
+            }
             if (!principal ||
                 !isCanonicalPrincipalIdentity(principal.subject) ||
                 !isCanonicalPrincipalIdentity(principal.tenantRef)) {
@@ -2752,7 +3222,7 @@ export function createSlotlockAgentServer(options) {
                     if (!outcome.ok && INTERNAL_FAILURES.has(outcome.code)) {
                         return json(500, rpcError(id, -32603, 'Internal error'));
                     }
-                    return json(200, rpcResult(id, slotlockMcpToolResult(outcome.ok ? outcome : { ok: false, code: outcome.code })));
+                    return json(200, rpcResult(id, slotlockMcpToolResult(outcome)));
                 }
                 catch {
                     return json(500, rpcError(id, -32603, 'Internal error'));
@@ -2874,7 +3344,9 @@ export function createSlotlockAgentServer(options) {
                         role: 'ROLE_AGENT',
                         parts: [
                             {
-                                data: outcome.ok ? outcome.data : { error: { code: outcome.code } },
+                                data: outcome.ok
+                                    ? outcome.data
+                                    : { error: { ...outcome.details, code: outcome.code } },
                                 mediaType: 'application/json',
                             },
                         ],