slotlock 0.1.1 → 0.3.0

package/agent-server.js

@@ -2,8 +2,11 @@ import { createHash, randomBytes } from 'node:crypto';
 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 { matchSlotlockRestRoute, restInputFromBody, restQueryInput, slotlockOpenApiDocument, } from './rest-api.js';
+import { SLOTLOCK_APPLICATION_REST_ROUTES, SLOTLOCK_REST_ROUTES, matchSlotlockRestRoute, 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,14 +62,6 @@ const RESOURCE_ID = z.string().trim().min(1).max(200);
 const EVENT_ID = z.string().trim().min(1).max(500);
 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;
 /** The longest slot `slotlock_find_next_available` can look for: the whole search window. */
 const MAX_SLOT_MINUTES = SLOTLOCK_CALENDAR_HORIZON_DAYS * 24 * 60;
@@ -93,41 +88,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),
@@ -185,30 +145,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
@@ -425,7 +361,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,
@@ -445,6 +381,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 ||
@@ -558,6 +496,35 @@ export function slotlockMcpToolResult(outcome) {
     }
     return { content: [{ type: 'text', text: JSON.stringify({ error }) }], isError: true };
 }
+/** The agent tools as REST serves them: each with the scope it needs. */
+function restAgentTools() {
+    return slotlockAgentTools().map((tool) => ({ ...tool, scope: slotlockAgentOperationScope(tool.name) }));
+}
+/** The application operations with their input and output as JSON Schema, as REST serves them. */
+export function slotlockApplicationOperations() {
+    return SLOTLOCK_APPLICATION_OPERATIONS.map((operation) => ({
+        name: operation.name,
+        title: operation.title,
+        description: operation.description,
+        method: operation.method,
+        path: operation.path,
+        inputSchema: toJsonSchema(operation.input, 'input'),
+        outputSchema: toJsonSchema(operation.output, 'output'),
+    }));
+}
+/**
+ * The OpenAPI 3.1 document of the REST API: what a server with `rest` (and `application`) serves at
+ * /openapi.json. Without `publicBaseUrl` the server URL is a variable, `{baseUrl}`, as in the
+ * repository's openapi.json, which client generators read.
+ */
+export function slotlockOpenApi(options = {}) {
+    return slotlockOpenApiDocument({
+        ...(options.publicBaseUrl !== undefined ? { publicBaseUrl: options.publicBaseUrl } : {}),
+        version: SLOTLOCK_AGENT_SERVER_VERSION,
+        tools: restAgentTools(),
+        ...(options.application ? { application: slotlockApplicationOperations() } : {}),
+    });
+}
 export function slotlockAgentTools() {
     return OPERATION_DEFINITIONS.map((operation) => ({
         name: operation.name,
@@ -611,13 +578,44 @@ function rpcResult(id, result) {
 function rpcError(id, code, message) {
     return { jsonrpc: '2.0', id, error: { code, message } };
 }
+/**
+ * Whether a Content-Type names `application/json`, whatever its parameters. A media type's type
+ * and subtype are case-insensitive (RFC 9110 §8.3.1), so `Application/JSON` is the same type.
+ */
+function isJsonMediaType(contentType) {
+    return contentType?.split(';')[0]?.trim().toLowerCase() === 'application/json';
+}
+/**
+ * Parse a JSON body of at most `maxBytes`. The body is counted as it arrives, so one sent without
+ * Content-Length (chunked) is refused, and its stream cancelled, as soon as it passes the limit,
+ * rather than buffered whole first.
+ */
 async function readJson(request, maxBytes) {
     const declared = request.headers.get('content-length');
     if (declared && Number(declared) > maxBytes)
         throw new Error('request_too_large');
-    const bytes = new Uint8Array(await request.arrayBuffer());
-    if (bytes.byteLength > maxBytes)
-        throw new Error('request_too_large');
+    const chunks = [];
+    let size = 0;
+    if (request.body) {
+        const reader = request.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw new Error('request_too_large');
+            }
+            chunks.push(value);
+        }
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
     try {
         return JSON.parse(new TextDecoder().decode(bytes));
     }
@@ -783,10 +781,11 @@ export async function invokeSlotlockAgentOperation(args) {
         if (!principalScopesCover(principal, operation.name)) {
             return { ok: false, status: 403, code: 'forbidden' };
         }
-        const input = args.input && typeof args.input === 'object' && !Array.isArray(args.input)
-            ? args.input
-            : {};
-        const parsed = operation.input.safeParse(input);
+        // No input, or null, is no arguments; anything else that is not an object is refused.
+        if (args.input != null && !isRecord(args.input)) {
+            return { ok: false, status: 400, code: 'invalid_arguments' };
+        }
+        const parsed = operation.input.safeParse(args.input ?? {});
         if (!parsed.success)
             return { ok: false, status: 400, code: 'invalid_arguments' };
         if (!(await args.options.authorize({
@@ -838,12 +837,20 @@ export async function invokeSlotlockAgentOperation(args) {
 /** Hand an unexpected failure to `onError`; nothing it does can change the protocol answer. */
 function reportUnexpected(onError, error, operation) {
     try {
-        onError?.(error, { operation });
+        ignoreRejection(onError?.(error, { operation }));
     }
     catch {
         // Observability must never change what a protocol client receives.
     }
 }
+/** Milliseconds since `started` (a `performance.now()` reading), to a tenth. */
+function elapsedMs(started) {
+    return Math.round((performance.now() - started) * 10) / 10;
+}
+/** The trace id of a valid `traceparent` (`version-traceid-parentid-flags`): its second field. */
+function traceIdOf(trace) {
+    return trace.traceparent.split('-', 2)[1] ?? '';
+}
 /** Failures that are server faults, not operation outcomes an agent could act on. */
 const INTERNAL_FAILURES = new Set(['internal_error', 'invalid_backend_result']);
 /**
@@ -1081,12 +1088,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,
     };
 }
 /**
@@ -1380,10 +1389,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 }]
                 : [];
@@ -1540,10 +1553,14 @@ async function confirmationMessage(operation, input, lookup) {
             }, zone)
             : `for ${promptRange(promptInstantOf(input.starts_at), promptInstantOf(input.ends_at), zone)}`;
         const tentative = input.status === 'tentative' ? ', tentatively' : '';
+        // A transparent booking does not make the resource busy: the person must know it stays free.
+        const free = input.transparency === 'transparent' ? ', leaving the time free for other bookings' : '';
+        const details = promptDetails(input);
+        const also = details ? ` (${details})` : '';
         const title = typeof input.title === 'string' && input.title.length > 0
             ? `: ${promptQuoted(input.title)}`
             : '';
-        return `Book ${resource.label} ${when}${tentative}${title}.`;
+        return `Book ${resource.label} ${when}${tentative}${free}${also}${title}.`;
     }
     const event = await lookup.event(input.event_id);
     const current = event ? await lookup.resource(event.resourceId) : null;
@@ -1598,8 +1615,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') {
@@ -1609,15 +1636,23 @@ async function confirmationMessage(operation, input, lookup) {
             changes.push(`exceptions to ${promptRequestedExceptions(input.recurrence_exceptions, zone)}`);
         }
     }
-    const details = ['description', 'location', 'organizer', 'attendees', 'reminders'].filter((field) => input[field] !== undefined);
-    if (details.length > 0)
-        changes.push(`also ${details.join(', ')}`);
+    const details = promptDetails(input);
+    if (details)
+        changes.push(details);
     // The agent's own text goes last.
     if (input.title !== undefined) {
         changes.push(input.title === null ? 'title removed' : `title to ${promptQuoted(input.title)}`);
     }
     return `Change ${target}${changes.length > 0 ? `: ${changes.join('; ')}` : ''}.${titled}`;
 }
+/**
+ * The other fields a write sets, by name only (`also description, attendees`): their values are
+ * the agent's text, and only the title is quoted. `null` when it sets none of them.
+ */
+function promptDetails(input) {
+    const details = ['description', 'location', 'organizer', 'attendees', 'reminders'].filter((field) => input[field] !== undefined);
+    return details.length > 0 ? `also ${details.join(', ')}` : null;
+}
 /**
  * Read the client's retry of a guarded call. State this server did not seal, sealed for another
  * principal, another operation or other arguments is `invalid`; lapsed state, or an answer that is
@@ -1688,6 +1723,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 === '')
@@ -1730,14 +1781,33 @@ export function createSlotlockAgentServer(options) {
     if (options.rest !== undefined && typeof options.rest !== 'boolean') {
         throw new Error('Slotlock agent server rest must be a boolean');
     }
-    const restTools = options.rest ? slotlockAgentTools() : [];
-    const restInputSchemas = new Map(restTools.map((tool) => [tool.name, tool.inputSchema]));
+    const application = options.application;
+    if (application !== undefined) {
+        if (options.rest !== true) {
+            throw new Error('Slotlock agent server application needs rest: it is served only as REST');
+        }
+        const backend = application?.backend;
+        if (typeof application !== 'object' ||
+            application === null ||
+            typeof application.authorize !== 'function' ||
+            typeof backend !== 'object' ||
+            backend === null ||
+            SLOTLOCK_APPLICATION_OPERATIONS.some((operation) => typeof backend[operation.invoke] !== 'function')) {
+            throw new Error('Slotlock agent server application needs an authorize function and a backend with every application method');
+        }
+    }
+    const restTools = options.rest ? restAgentTools() : [];
+    const applicationTools = application ? slotlockApplicationOperations() : [];
+    const restInputSchemas = new Map([
+        ...restTools.map((tool) => [tool.name, tool.inputSchema]),
+        ...applicationTools.map((tool) => [tool.name, tool.inputSchema]),
+    ]);
+    const restRoutes = [
+        ...SLOTLOCK_REST_ROUTES,
+        ...(application ? SLOTLOCK_APPLICATION_REST_ROUTES : []),
+    ];
     const openApi = options.rest
-        ? Object.freeze(slotlockOpenApiDocument({
-            publicBaseUrl: config.publicBaseUrl,
-            version: SLOTLOCK_AGENT_SERVER_VERSION,
-            tools: restTools,
-        }))
+        ? Object.freeze(slotlockOpenApi({ publicBaseUrl: config.publicBaseUrl, application: application !== undefined }))
         : null;
     const manifest = Object.freeze({
         name: 'Slotlock Agent Calendar',
@@ -1761,12 +1831,33 @@ export function createSlotlockAgentServer(options) {
     const confirmation = validateConfirmation(options.confirmation);
     const emit = (event) => {
         try {
-            options.onEvent?.(event);
+            ignoreRejection(options.onEvent?.(event));
         }
         catch {
             // Observability must never change what a protocol client receives.
         }
     };
+    /**
+     * Report how an MCP or A2A call that named an operation ended, as a `call` event: run, or refused
+     * before it could run (a malformed message, a client that cannot confirm). Never its arguments.
+     */
+    const reportCall = (protocol, operation, outcome, started, trace) => {
+        emit({
+            type: 'call',
+            protocol,
+            operation,
+            outcome,
+            durationMs: elapsedMs(started),
+            ...(trace ? { traceId: traceIdOf(trace) } : {}),
+        });
+    };
+    /** Run an operation an MCP or A2A caller named, and report how it ended as a `call` event. */
+    const invokeReported = async (protocol, args) => {
+        const started = performance.now();
+        const outcome = await invokeSlotlockAgentOperation(args);
+        reportCall(protocol, args.operation, outcome.ok ? 'ok' : outcome.code, started, args.trace);
+        return outcome;
+    };
     const dispatchOptions = (principal) => ({
         backend: options.backend,
         // The transport authenticates once before protocol parsing/rate-limiting; the canonical
@@ -1832,10 +1923,17 @@ export function createSlotlockAgentServer(options) {
         const operation = resolveSlotlockAgentOperation(params.name);
         if (!operation)
             return modernError(200, id, -32602, 'Unknown tool');
+        const started = performance.now();
+        // `arguments` may be left out or null; anything else but an object is malformed params.
+        if (params.arguments != null && !isRecord(params.arguments)) {
+            reportCall('mcp', operation, 'invalid_arguments', started, call.trace);
+            return modernError(200, id, -32602, 'Invalid params');
+        }
         const dispatch = dispatchOptions(principal);
         const gate = {};
         if (confirmation?.operations.has(operation)) {
             if (!clientSupportsFormElicitation(call.capabilities)) {
+                reportCall('mcp', operation, 'missing_capability', started, call.trace);
                 return modernError(400, id, MCP_MISSING_REQUIRED_CLIENT_CAPABILITY, 'Missing required client capability', { requiredCapabilities: { elicitation: { form: {} } } });
             }
             dispatch.confirm = async ({ input }) => {
@@ -1848,19 +1946,18 @@ export function createSlotlockAgentServer(options) {
                     operation,
                     argsDigest: gate.argsDigest,
                 });
+                // 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];
             };
         }
-        const outcome = await invokeSlotlockAgentOperation({
+        const outcome = await invokeReported('mcp', {
             operation,
             input: isRecord(params.arguments) ? params.arguments : {},
             request: call.request,
             options: dispatch,
             ...(call.trace ? { trace: call.trace } : {}),
         });
-        if (gate.decision) {
-            emit({ type: 'confirmation', operation, outcome: CONFIRMATION_OUTCOME[gate.decision] });
-        }
         if (confirmation &&
             (gate.decision === 'prompt' || gate.decision === 'expired') &&
             gate.input &&
@@ -2056,15 +2153,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 {
@@ -2128,6 +2258,7 @@ export function createSlotlockAgentServer(options) {
             });
         }
         slot.end = end;
+        slot.streaming = true;
         stream.send({
             jsonrpc: '2.0',
             method: 'notifications/subscriptions/acknowledged',
@@ -2267,6 +2398,48 @@ export function createSlotlockAgentServer(options) {
                 return modernError(404, id, -32601, 'Method not found');
         }
     }
+    /**
+     * One application operation for an authenticated principal: the admin scope (when the principal
+     * carries scopes), the operation's strict input schema, `application.authorize`, the backend, and
+     * its output schema. A refusal the backend throws as a `SlotlockAgentOperationError` is the answer;
+     * anything else is reported to `onError` and answers only `internal_error`.
+     */
+    async function invokeApplicationOperation(definition, principal, given, request, trace) {
+        const served = application;
+        try {
+            const scopes = principal.scopes;
+            if (scopes !== undefined &&
+                !(Array.isArray(scopes) && scopes.includes(SLOTLOCK_APPLICATION_SCOPE))) {
+                return { ok: false, status: 403, code: 'forbidden' };
+            }
+            const parsed = definition.input.safeParse(given);
+            if (!parsed.success)
+                return { ok: false, status: 400, code: 'invalid_arguments' };
+            if (!(await served.authorize({ principal, operation: definition.name, input: parsed.data }))) {
+                return { ok: false, status: 403, code: 'forbidden' };
+            }
+            const context = {
+                principal,
+                operation: definition.name,
+                signal: request.signal,
+            };
+            if (trace)
+                context.trace = trace;
+            const data = await served.backend[definition.invoke].call(served.backend, context, parsed.data);
+            if (!definition.output.safeParse(data).success) {
+                reportUnexpected(options.onError, Object.assign(new Error(`The application backend's ${definition.name} result does not match the operation's output schema`), { code: 'invalid_backend_result' }), definition.name);
+                return { ok: false, status: 500, code: 'invalid_backend_result' };
+            }
+            return { ok: true, data };
+        }
+        catch (error) {
+            if (error instanceof SlotlockAgentOperationError) {
+                return { ok: false, status: error.status, code: error.code };
+            }
+            reportUnexpected(options.onError, error, definition.name);
+            return { ok: false, status: 500, code: 'internal_error' };
+        }
+    }
     /**
      * One REST call, checked as /mcp and /a2a are (origin, credential, rate limit), then run through
      * the same dispatcher: scopes, arguments, `authorize`, and confirmation, which REST cannot ask
@@ -2279,7 +2452,7 @@ export function createSlotlockAgentServer(options) {
                 ? json(200, openApi)
                 : refuse(405, 'method_not_allowed', { Allow: 'GET' });
         }
-        const match = matchSlotlockRestRoute(request.method, path);
+        const match = matchSlotlockRestRoute(request.method, path, restRoutes);
         if (match === null)
             return refuse(404, 'not_found');
         if ('allow' in match) {
@@ -2292,7 +2465,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)) {
@@ -2307,41 +2483,71 @@ export function createSlotlockAgentServer(options) {
         if ('invalid' in match)
             return refuse(400, 'invalid_arguments');
         const { route, params } = match;
+        const trace = traceContextFrom(undefined, request.headers);
+        const started = performance.now();
+        const report = (status) => emit({
+            type: 'rest',
+            operation: route.operation,
+            status,
+            durationMs: elapsedMs(started),
+            ...(trace ? { traceId: traceIdOf(trace) } : {}),
+        });
+        // A call refused before its operation runs is reported as one that ran, as on MCP and A2A.
+        const refuseCall = (status, code) => {
+            report(status);
+            return refuse(status, code);
+        };
         let given;
         if (restInputFromBody(route)) {
-            const contentType = request.headers.get('content-type')?.split(';')[0]?.trim();
-            if (contentType !== 'application/json')
-                return refuse(415, 'unsupported_media_type');
+            if (!isJsonMediaType(request.headers.get('content-type'))) {
+                return refuseCall(415, 'unsupported_media_type');
+            }
             let body;
             try {
                 body = await readJson(request, config.maxRequestBytes);
             }
             catch (error) {
                 const tooLarge = error instanceof Error && error.message === 'request_too_large';
-                return refuse(tooLarge ? 413 : 400, tooLarge ? 'request_too_large' : 'invalid_json');
+                return refuseCall(tooLarge ? 413 : 400, tooLarge ? 'request_too_large' : 'invalid_json');
             }
             if (!isRecord(body))
-                return refuse(400, 'invalid_arguments');
+                return refuseCall(400, 'invalid_arguments');
             given = body;
         }
         else {
-            given = restQueryInput(url.searchParams, restInputSchemas.get(route.operation) ?? {});
+            given = restQueryInput(url.searchParams, (restInputSchemas.get(route.operation) ?? {}));
         }
         // The path names the event; the body or query may not name another.
         if (Object.keys(params).some((name) => Object.hasOwn(given, name))) {
-            return refuse(400, 'invalid_arguments');
+            return refuseCall(400, 'invalid_arguments');
         }
-        const trace = traceContextFrom(undefined, request.headers);
-        const outcome = await invokeSlotlockAgentOperation({
-            operation: route.operation,
-            input: { ...given, ...params },
-            request,
-            options: withoutConfirmationRound(principal, route.operation),
-            ...(trace ? { trace } : {}),
-        });
+        // 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.
+        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')) {
+                return refuseCall(400, 'idempotency_key_not_supported');
+            }
+            if (Object.hasOwn(given, 'idempotency_key') && given.idempotency_key !== idempotencyHeader) {
+                return refuseCall(400, 'invalid_arguments');
+            }
+            given = { ...given, idempotency_key: idempotencyHeader };
+        }
+        const outcome = isSlotlockApplicationOperation(route.operation)
+            ? await invokeApplicationOperation(slotlockApplicationOperation(route.operation), principal, { ...given, ...params }, request, trace)
+            : await invokeSlotlockAgentOperation({
+                operation: route.operation,
+                input: { ...given, ...params },
+                request,
+                options: withoutConfirmationRound(principal, route.operation),
+                ...(trace ? { trace } : {}),
+            });
         const internal = !outcome.ok && INTERNAL_FAILURES.has(outcome.code);
         const status = outcome.ok ? 200 : internal ? 500 : outcome.status;
-        emit({ type: 'rest', operation: route.operation, status });
+        report(status);
         if (outcome.ok)
             return json(200, outcome.data);
         return refuse(status, internal ? 'internal_error' : outcome.code);
@@ -2411,8 +2617,7 @@ export function createSlotlockAgentServer(options) {
             if (request.method !== 'POST' || (path !== '/mcp' && path !== '/a2a')) {
                 return json(404, { error: { code: 'not_found' } });
             }
-            const contentType = request.headers.get('content-type')?.split(';')[0]?.trim();
-            if (contentType !== 'application/json') {
+            if (!isJsonMediaType(request.headers.get('content-type'))) {
                 return json(415, { error: { code: 'unsupported_media_type' } });
             }
             const origin = request.headers.get('origin');
@@ -2422,7 +2627,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)) {
@@ -2432,7 +2647,14 @@ export function createSlotlockAgentServer(options) {
             }
             if (options.consumeRateLimit &&
                 !(await options.consumeRateLimit({ principal, operation: 'protocol' }))) {
-                // Answered before the body is read, so the era comes from the version header alone.
+                // Answered before the body is read: the request's id is unknown, and the MCP era comes
+                // from the version header alone. A2A keeps the error in its 200 envelope with an ErrorInfo.
+                if (path === '/a2a') {
+                    return a2aError(null, -32029, 'Rate limit exceeded', {
+                        reason: 'RATE_LIMITED',
+                        domain: 'slotlock',
+                    });
+                }
                 const modernClient = path === '/mcp' &&
                     MODERN_MCP_VERSIONS.includes(request.headers.get('mcp-protocol-version') ?? '');
                 return json(429, rpcError(null, modernClient ? SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE : -32029, 'Rate limit exceeded'));
@@ -2541,14 +2763,16 @@ export function createSlotlockAgentServer(options) {
                 const operation = resolveSlotlockAgentOperation(rpc.params?.name);
                 if (!operation)
                     return json(200, rpcError(id, -32602, 'Unknown tool'));
-                const input = rpc.params?.arguments &&
-                    typeof rpc.params.arguments === 'object' &&
-                    !Array.isArray(rpc.params.arguments)
-                    ? rpc.params.arguments
-                    : {};
+                const started = performance.now();
+                const trace = traceContextFrom(isRecord(rpc.params?._meta) ? rpc.params._meta : undefined, request.headers);
+                // `arguments` may be left out or null; anything else but an object is malformed params.
+                const input = rpc.params?.arguments;
+                if (input != null && !isRecord(input)) {
+                    reportCall('mcp', operation, 'invalid_arguments', started, trace);
+                    return json(200, rpcError(id, -32602, 'Invalid params'));
+                }
                 try {
-                    const trace = traceContextFrom(isRecord(rpc.params?._meta) ? rpc.params._meta : undefined, request.headers);
-                    const outcome = await invokeSlotlockAgentOperation({
+                    const outcome = await invokeReported('mcp', {
                         operation,
                         input,
                         request,
@@ -2606,38 +2830,49 @@ export function createSlotlockAgentServer(options) {
             if (rpc.method !== 'SendMessage') {
                 return json(200, rpcError(id, -32601, 'Method not found'));
             }
-            const a2aParamKeys = Object.keys(rpc.params ?? {});
-            if (a2aParamKeys.some((key) => !['message', 'configuration', 'metadata', 'tenant'].includes(key)) ||
-                !isCallerTenant(rpc.params?.tenant, principal.tenantRef)) {
-                return a2aError(id, -32602, 'Invalid message parameters', {
-                    reason: 'INVALID_MESSAGE_PARAMETERS',
-                    domain: 'slotlock',
-                });
-            }
+            const started = performance.now();
+            const trace = traceContextFrom(undefined, request.headers);
             const message = rpc.params?.message;
             const parts = Array.isArray(message?.parts) ? message.parts : [];
             const part = parts.length === 1 ? parts[0] : null;
             const data = part?.data;
             const operation = resolveSlotlockAgentOperation(data?.skill);
-            const input = data?.arguments && typeof data.arguments === 'object' && !Array.isArray(data.arguments)
-                ? data.arguments
-                : {};
+            // A refused message that names an operation is still a call, reported by the error's reason.
+            const refuse = (outcome, response) => {
+                if (operation)
+                    reportCall('a2a', operation, outcome, started, trace);
+                return response;
+            };
+            const a2aParamKeys = Object.keys(rpc.params ?? {});
+            if (a2aParamKeys.some((key) => !['message', 'configuration', 'metadata', 'tenant'].includes(key)) ||
+                !isCallerTenant(rpc.params?.tenant, principal.tenantRef) ||
+                // a2a.proto: a SendMessageConfiguration and a Struct, each optional (null is unset in proto3
+                // JSON). What A2A 1.0 defines inside them (output modes, history length, ...) is the client's.
+                (rpc.params?.configuration != null && !isRecord(rpc.params.configuration)) ||
+                (rpc.params?.metadata != null && !isRecord(rpc.params.metadata))) {
+                return refuse('invalid_message_parameters', a2aError(id, -32602, 'Invalid message parameters', {
+                    reason: 'INVALID_MESSAGE_PARAMETERS',
+                    domain: 'slotlock',
+                }));
+            }
+            // `arguments` may be left out or null; anything else but an object is not arguments.
+            const input = data?.arguments;
             if (!operation ||
                 message?.role !== 'ROLE_USER' ||
                 !isCanonicalBoundedIdentifier(message.messageId, 200) ||
                 message.taskId !== undefined ||
-                (message.contextId !== undefined && !isCanonicalBoundedIdentifier(message.contextId, 200))) {
-                return a2aError(id, -32602, 'Invalid message', {
+                (message.contextId !== undefined && !isCanonicalBoundedIdentifier(message.contextId, 200)) ||
+                (input != null && !isRecord(input))) {
+                return refuse('invalid_message', a2aError(id, -32602, 'Invalid message', {
                     reason: 'INVALID_MESSAGE',
                     domain: 'slotlock',
                     metadata: {
                         expected: 'one application/json data part {"skill": "<skill id>", "arguments": {…}}',
                     },
-                });
+                }));
             }
             try {
-                const trace = traceContextFrom(undefined, request.headers);
-                const outcome = await invokeSlotlockAgentOperation({
+                const outcome = await invokeReported('a2a', {
                     operation,
                     input,
                     request,