slotlock 0.3.0 → 0.5.0

package/agent-server.js

@@ -6,7 +6,7 @@ import { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlock
 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';
@@ -60,9 +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();
 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;
@@ -177,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',
@@ -197,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';
@@ -224,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));
@@ -231,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
@@ -246,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),
@@ -310,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',
@@ -327,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',
@@ -440,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.
@@ -450,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;
@@ -539,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,
@@ -810,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,
@@ -818,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);
@@ -828,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' };
@@ -1141,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',
 ]);
@@ -1180,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) {
@@ -1537,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([
@@ -1946,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];
@@ -2003,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) => {
@@ -2434,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' };
@@ -2446,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)
@@ -2521,20 +2941,27 @@ export function createSlotlockAgentServer(options) {
         if (Object.keys(params).some((name) => Object.hasOwn(given, name))) {
             return refuseCall(400, 'invalid_arguments');
         }
-        // An application write's retry identity may come as the Idempotency-Key header, 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.
-        // The agent tools take theirs as an argument alone, as they always have.
+        // 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 && isSlotlockApplicationOperation(route.operation)) {
-            const fields = (restInputSchemas.get(route.operation)?.properties ?? {});
-            if (!Object.hasOwn(fields, 'idempotency_key')) {
+        if (idempotencyHeader !== null) {
+            if (!Object.hasOwn(inputSchema?.properties ?? {}, 'idempotency_key')) {
                 return refuseCall(400, 'idempotency_key_not_supported');
             }
-            if (Object.hasOwn(given, 'idempotency_key') && given.idempotency_key !== idempotencyHeader) {
+            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: idempotencyHeader };
+            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)
@@ -2550,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,
@@ -2596,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')),
@@ -2605,6 +3044,7 @@ export function createSlotlockAgentServer(options) {
                     return json(503, {
                         status: 'not_ready',
                         version: SLOTLOCK_AGENT_SERVER_VERSION,
+                        tzdata: process.versions.tz ?? null,
                         checks: [],
                     });
                 }
@@ -2782,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'));
@@ -2904,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',
                             },
                         ],