slotlock 0.1.0 → 0.2.0

package/SPEC.md

@@ -129,19 +129,29 @@ event, an exhausted quota) is a result, not a protocol error:
 - A2A returns the agent's reply message with one `application/json` data part holding the result or
   `{"error":{"code":"…"}}`.
 
-Protocol errors stay in the protocol. MCP: an unknown tool is JSON-RPC `-32602`, a server fault
+A body must be `application/json`, compared without regard to case (RFC 9110 §8.3.1), or the request
+is HTTP 415; one longer than the server's limit is HTTP 413, refused as soon as it passes the limit,
+whether or not it declares a `Content-Length`.
+
+Protocol errors stay in the protocol. MCP: an unknown tool, or `arguments` that are not an object
+(left out or null is none), is JSON-RPC `-32602`, a server fault
 (including backend output that violates the declared schema) is `-32603` with HTTP 500, and a
 missing or unsupported `MCP-Protocol-Version` header is HTTP 400. A 2026-07-28 request is checked in
 that revision's order, each failure HTTP 400: a missing or malformed `_meta` field is `-32602`, an
 `MCP-Protocol-Version`, `Mcp-Method` or (Base64-sentinel-decoded) `Mcp-Name` that disagrees with the
 body is `-32020`, and an unimplemented revision is `-32022` naming the supported ones. An
 unimplemented method is HTTP 404 `-32601`; a rate-limited request is HTTP 429 `-31029`, outside the
-`-32020`..`-32099` range that revision reserves. A2A: every JSON-RPC error travels
-in an HTTP 200 envelope with a `google.rpc.ErrorInfo` detail; an `A2A-Version` other than `1.0`,
-including none (read as 0.3), is `VersionNotSupportedError` (`-32009`); push-notification methods are
+`-32020`..`-32099` range that revision reserves. A2A: every JSON-RPC error travels in an HTTP 200
+envelope (a body over the size limit is HTTP 413); A2A's own errors, below, carry a
+`google.rpc.ErrorInfo` detail and JSON-RPC's (`-32700`, `-32600`, `-32601`, `-32603`) none. An
+`A2A-Version` other than `1.0`, including none (read as 0.3), is `VersionNotSupportedError`
+(`-32009`); push-notification methods are
 `PushNotificationNotSupportedError` (`-32003`); streaming, task subscription and the extended card
 are `UnsupportedOperationError` (`-32004`); a message that is not exactly one data part
-`{"skill": "<id>", "arguments": {…}}` is `-32602`. The server replies with messages and keeps no
+`{"skill": "<id>", "arguments": {…}}` (`arguments` left out or null is none; any other value that is
+not an object is not arguments) is `-32602`, as is a `configuration` or `metadata` that is set but
+is not an object; a rate-limited request is `-32029` with the reason `RATE_LIMITED` and a null id,
+answered before its body is read. The server replies with messages and keeps no
 tasks, so the core task operations answer as for an unknown task: `GetTask` and `CancelTask` are
 `TaskNotFoundError` (`-32001`), `ListTasks` returns an empty page (`pageSize` 1-100, default 50).
 Their params are checked first, as `SendMessage`'s are: a field the method does not define, a
@@ -237,4 +247,7 @@ rejects absolute-form request targets, applies finite header/body/handler and co
 propagates disconnects through `AbortSignal`, and force-closes only after a bounded graceful-shutdown
 window. When it closes it first asks the target to end long-lived responses (the agent server's
 `shutdown()`), and closes keep-alive connections whose response finished during shutdown. It exposes
-sanitized transport failures and leaves public TLS termination to the deployment.
+sanitized transport failures and leaves public TLS termination to the deployment. A body the target
+stops reading (one past its size limit) does not abort the request: once the response is written,
+the rest is discarded as it arrives, within `requestTimeout`. Closing the adapter while it is still
+starting rejects the pending `listen()` with `listen_aborted`.

package/agent-server.d.ts

@@ -1,4 +1,5 @@
 import { type SlotlockTraceContext } from './mcp-modern.js';
+import { type SlotlockApplicationBackend, type SlotlockApplicationOperation } from './application-api.js';
 export type { SlotlockTraceContext } from './mcp-modern.js';
 export { clientSupportsSlotlockMcpApp, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, } from './mcp-app.js';
 /**
@@ -163,10 +164,31 @@ export type SlotlockAgentServerEvent = {
     operation: SlotlockAgentOperation;
     outcome: 'requested' | 'accepted' | 'declined' | 'cancelled' | 'expired' | 'refused' | 'unavailable';
 } | {
-    /** A REST call that reached an operation, and the HTTP status it answered. */
+    /**
+     * A REST call that named an operation, and the HTTP status it answered: run, or refused before
+     * it ran (a body that is not JSON, too large or not an object).
+     */
     type: 'rest';
-    operation: SlotlockAgentOperation;
+    operation: SlotlockAgentOperation | SlotlockApplicationOperation;
     status: number;
+    /** How long the call took from naming its operation, in milliseconds to a tenth. */
+    durationMs: number;
+    /** The W3C trace id of the call's valid `traceparent`, when it carried one. */
+    traceId?: string;
+} | {
+    /** An MCP `tools/call` or A2A `SendMessage` that named an operation, and how it ended. */
+    type: 'call';
+    protocol: 'mcp' | 'a2a';
+    operation: SlotlockAgentOperation;
+    /**
+     * `ok`, or the refusal's code (`overlap`, `forbidden`, `rate_limited`, …), or why the request
+     * was refused before the operation ran: `invalid_arguments` (MCP arguments that are not an
+     * object), `missing_capability` (a guarded write from a 2026-07-28 client without form
+     * elicitation), `invalid_message` or `invalid_message_parameters` (A2A).
+     */
+    outcome: string;
+    durationMs: number;
+    traceId?: string;
 } | {
     type: 'subscription';
     outcome: 'opened' | 'closed';
@@ -204,6 +226,21 @@ export interface SlotlockAgentServerOptions {
      * to ask a person. Off unless set.
      */
     rest?: boolean;
+    /**
+     * Also serve the application API under `/v1` (application-api.ts): resources, bookable hours,
+     * holds, reservations, calendar coverage and maintenance, for the application around the agents,
+     * in any language. Needs `rest`. A principal whose `scopes` are set needs `admin`
+     * (SLOTLOCK_APPLICATION_SCOPE); then `authorize` decides. They are never MCP tools or A2A skills,
+     * and never wait for a confirmation. Off unless set.
+     */
+    application?: {
+        backend: SlotlockApplicationBackend;
+        authorize(args: {
+            principal: SlotlockAgentPrincipal;
+            operation: SlotlockApplicationOperation;
+            input: Record<string, unknown>;
+        }): Promise<boolean>;
+    };
     /** Require a person's confirmation before the listed writes run. Off unless set. */
     confirmation?: SlotlockAgentConfirmationOptions;
     /**
@@ -218,23 +255,24 @@ export interface SlotlockAgentServerOptions {
      */
     subscriptions?: SlotlockAgentSubscriptionOptions | false;
     /**
-     * Observe confirmations and subscriptions (counts and outcomes, no arguments or identities) for
-     * metrics or audit. It runs synchronously and whatever it throws is ignored.
+     * Observe calls, confirmations and subscriptions (counts and outcomes, no arguments or
+     * identities) for metrics or audit. It is not awaited, and whatever it throws, or its promise
+     * rejects with, is ignored.
      */
     onEvent?: (event: SlotlockAgentServerEvent) => void;
     /**
      * Called with a failure no client is told about: an operation's backend threw something other
      * than a `SlotlockAgentOperationError`, or returned a result outside the operation's schema. The
      * client gets `internal_error` and nothing more, so log it here to find out why. It receives the
-     * error and the operation, never the arguments or the request; it runs synchronously and whatever
-     * it throws is ignored.
+     * error and the operation, never the arguments or the request. It is not awaited, and whatever it
+     * throws, or its promise rejects with, is ignored.
      */
     onError?: (error: unknown, context: SlotlockAgentErrorContext) => void;
 }
 /** What `onError` is told about an unexpected failure besides the error itself. */
 export interface SlotlockAgentErrorContext {
     /** The operation that failed; `null` when the failure came before one was resolved. */
-    operation: SlotlockAgentOperation | null;
+    operation: SlotlockAgentOperation | SlotlockApplicationOperation | null;
 }
 export interface SlotlockAgentOperationDispatchOptions {
     backend: SlotlockAgentCalendarBackend;
@@ -309,6 +347,25 @@ export declare function slotlockMcpToolResult(outcome: {
     code: string;
     details?: Readonly<Record<string, string | number | boolean | null>>;
 }): SlotlockMcpToolResult;
+/** The application operations with their input and output as JSON Schema, as REST serves them. */
+export declare function slotlockApplicationOperations(): {
+    name: SlotlockApplicationOperation;
+    title: string;
+    description: string;
+    method: "DELETE" | "GET" | "POST" | "PUT";
+    path: string;
+    inputSchema: Readonly<Record<string, unknown>>;
+    outputSchema: Readonly<Record<string, unknown>>;
+}[];
+/**
+ * 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 declare function slotlockOpenApi(options?: {
+    publicBaseUrl?: string;
+    application?: boolean;
+}): Record<string, unknown>;
 export declare function slotlockAgentTools(): {
     name: "slotlock_create_event" | "slotlock_delete_event" | "slotlock_find_next_available" | "slotlock_get_event" | "slotlock_get_free_busy" | "slotlock_list_events" | "slotlock_list_resources" | "slotlock_update_event";
     title: "Create resource event" | "Delete resource event" | "Find next available interval" | "Get free-busy" | "Get resource event" | "List calendar resources" | "List resource events" | "Update resource event";