slotlock 0.5.2 → 0.6.0

package/agent-server.js

@@ -1,8 +1,10 @@
+import { AsyncResource } from 'node:async_hooks';
 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 { createSlotlockChangeReaders, } from './change-watch.js';
 import { SLOTLOCK_EVENT_OUTPUT as EVENT } from './event-schema.js';
 import { ignoreRejection } from './hooks.js';
 import { slotlockPackageVersion } from './package-version.js';
@@ -378,6 +380,21 @@ export class SlotlockAgentOperationError extends Error {
             this.details = Object.freeze(Object.fromEntries(kept));
     }
 }
+/** At most this many issues are returned, each message cut to {@link MAX_ISSUE_MESSAGE} characters. */
+const MAX_ISSUES = 20;
+const MAX_ISSUE_MESSAGE = 200;
+/** Argument validation's refusal: 400 `invalid_arguments` with the fields zod refused. */
+function invalidArguments(error) {
+    return {
+        ok: false,
+        status: 400,
+        code: 'invalid_arguments',
+        issues: error.issues.slice(0, MAX_ISSUES).map((issue) => ({
+            path: issue.path.map((key) => (typeof key === 'number' ? key : String(key))),
+            message: issue.message.slice(0, MAX_ISSUE_MESSAGE),
+        })),
+    };
+}
 const EXAMPLE_RESOURCE_ID = '0f8b6c1e-2d4a-4c7e-9b1a-3e5f7a9c2d4b';
 const EXAMPLE_EVENT_ID = 'agent:5e8ff9bf55ba3508199d22e984129be6b5b6a8a7e3e5f1f0d2b9ba0c4a6f7e21';
 const EXAMPLE_WINDOW = { start: '2027-03-01T00:00:00Z', end: '2027-03-08T00:00:00Z' };
@@ -843,6 +860,8 @@ export function slotlockMcpToolResult(outcome) {
         if (key !== 'code')
             error[key] = value;
     }
+    if (outcome.issues)
+        error.issues = outcome.issues;
     return { content: [{ type: 'text', text: JSON.stringify({ error }) }], isError: true };
 }
 /** The agent tools as REST serves them: each with the scope it needs. */
@@ -1150,7 +1169,7 @@ export async function invokeSlotlockAgentOperation(args) {
         }
         const parsed = operation.input.safeParse(args.input ?? {});
         if (!parsed.success)
-            return { ok: false, status: 400, code: 'invalid_arguments' };
+            return invalidArguments(parsed.error);
         if (!(await args.options.authorize({
             principal,
             operation: operation.name,
@@ -1185,6 +1204,8 @@ export async function invokeSlotlockAgentOperation(args) {
         };
         if (args.trace)
             context.trace = args.trace;
+        if (args.origin)
+            context.origin = args.origin;
         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.
@@ -1226,12 +1247,14 @@ function traceIdOf(trace) {
 /** Failures that are server faults, not operation outcomes an agent could act on. */
 const INTERNAL_FAILURES = new Set(['internal_error', 'invalid_backend_result']);
 /**
- * A2A 1.0 methods (a2a.proto `A2AService`) this synchronous, stateless binding does not implement.
- * A2A §3.3.4 fixes the error for the capability-gated ones: push-notification configuration answers
- * `PushNotificationNotSupportedError`; streaming, task subscription and the extended card answer
- * `UnsupportedOperationError`. GetTask, CancelTask and ListTasks are core operations every agent
- * answers; since every reply here is a message, no task id exists: `TaskNotFoundError` for the
- * first two (§3.1) and an empty page for the list.
+ * A2A 1.0 methods (a2a.proto `A2AService`) this binding does not implement. A2A §3.3.4 fixes the
+ * error for the capability-gated ones: push-notification configuration answers
+ * `PushNotificationNotSupportedError` (a tenant's changes reach a URL as signed webhooks instead);
+ * task subscription and the extended card answer `UnsupportedOperationError`. `SendStreamingMessage`
+ * is served: a skill's reply as a one-message stream, and the watch skill as a task whose stream is
+ * the only place it lives, so it cannot be subscribed to again. GetTask, CancelTask and ListTasks are
+ * core operations every agent answers; no task is kept to find: `TaskNotFoundError` for the first
+ * two (§3.1) and an empty page for the list.
  */
 const A2A_PUSH_NOTIFICATION_METHODS = new Set([
     'CreateTaskPushNotificationConfig',
@@ -1240,7 +1263,6 @@ const A2A_PUSH_NOTIFICATION_METHODS = new Set([
     'DeleteTaskPushNotificationConfig',
 ]);
 const A2A_UNSUPPORTED_METHODS = new Set([
-    'SendStreamingMessage',
     'SubscribeToTask',
     'GetExtendedAgentCard',
 ]);
@@ -1450,9 +1472,19 @@ const INVISIBLE_STATUSES = new Set([400, 403, 404]);
 const MAX_RESOURCE_SUBSCRIPTIONS = 20;
 /** Consecutive failed re-reads after which a subscription is abandoned. */
 const MAX_POLL_FAILURES = 3;
+/** The least time between the starts of two re-reads of one subscription a change asked for, in ms. */
+const CHANGE_REREAD_MIN_MS = 1_000;
 function validateSubscriptions(value) {
     if (value === false)
         return null;
+    const changes = value?.changes ?? null;
+    if (changes !== null &&
+        (typeof changes !== 'object' ||
+            typeof changes.head !== 'function' ||
+            typeof changes.listChanges !== 'function' ||
+            (changes.watch !== undefined && typeof changes.watch !== 'function'))) {
+        throw new Error('Slotlock agent server subscriptions.changes is invalid');
+    }
     const bounded = (name, min, max, fallback) => {
         const setting = value?.[name] ?? fallback;
         if (!Number.isInteger(setting) || setting < min || setting > max) {
@@ -1462,7 +1494,8 @@ function validateSubscriptions(value) {
     };
     const maxTotal = bounded('maxTotal', 1, 10_000, 256);
     return {
-        pollIntervalMs: bounded('pollIntervalMs', 1_000, 300_000, 10_000),
+        pollIntervalMs: bounded('pollIntervalMs', 1_000, 300_000, changes ? 15_000 : 10_000),
+        changes,
         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),
@@ -2161,8 +2194,15 @@ function routePath(pathname, basePath) {
         return '/';
     return pathname.startsWith(`${basePath}/`) ? pathname.slice(basePath.length) : null;
 }
+/**
+ * The A2A skill that watches calendars: `SendStreamingMessage` only. Its stream opens with a task
+ * in TASK_STATE_WORKING and carries a status update for each change to a watched resource's
+ * free/busy, from the same feed as MCP resource subscriptions, until the watch's duration is up.
+ */
+export const SLOTLOCK_A2A_WATCH_SKILL = 'slotlock_watch_resources';
+const A2A_WATCH_EXAMPLE = { resource_ids: ['018f2f8e-7f8a-7c3e-9b1a-2a4c6e8f0a1b'] };
 /** The A2A 1.0 agent card, in the JSON form of a2a.proto's `AgentCard`. */
-function agentCard(publicBaseUrl) {
+function agentCard(publicBaseUrl, watch) {
     return Object.freeze({
         name: 'Slotlock Agent Calendar',
         description: `Tenant-isolated resource events, recurrence, free-busy, and scheduling. Invoke a skill with one application/json data part {"skill": "<skill id>", "arguments": {…}}; argument and result JSON Schemas are published at ${publicBaseUrl}/manifest.json.`,
@@ -2174,20 +2214,37 @@ function agentCard(publicBaseUrl) {
             },
         ],
         version: SLOTLOCK_AGENT_SERVER_VERSION,
-        capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
+        capabilities: { streaming: true, pushNotifications: false, extendedAgentCard: false },
         securitySchemes: { bearer: { httpAuthSecurityScheme: { scheme: 'Bearer' } } },
         securityRequirements: [{ schemes: { bearer: { list: [] } } }],
         defaultInputModes: ['application/json'],
         defaultOutputModes: ['application/json'],
-        skills: OPERATION_DEFINITIONS.map((operation) => ({
-            id: operation.name,
-            name: operation.title,
-            description: operation.description,
-            tags: ['calendar', 'scheduling', 'resources'],
-            examples: [JSON.stringify({ skill: operation.name, arguments: operation.example })],
-            inputModes: ['application/json'],
-            outputModes: ['application/json'],
-        })),
+        skills: [
+            ...OPERATION_DEFINITIONS.map((operation) => ({
+                id: operation.name,
+                name: operation.title,
+                description: operation.description,
+                tags: ['calendar', 'scheduling', 'resources'],
+                examples: [JSON.stringify({ skill: operation.name, arguments: operation.example })],
+                inputModes: ['application/json'],
+                outputModes: ['application/json'],
+            })),
+            ...(watch
+                ? [
+                    {
+                        id: SLOTLOCK_A2A_WATCH_SKILL,
+                        name: 'Watch calendar resources',
+                        description: 'SendStreamingMessage only. Watch up to 20 resources (resource_ids) for changes to their free/busy: the stream opens with a task in TASK_STATE_WORKING and carries a status update {"resource_id", "uri"} for each change, until the watch ends (TASK_STATE_COMPLETED) or access is withdrawn (TASK_STATE_FAILED). Read the resource again on each update.',
+                        tags: ['calendar', 'resources', 'watch'],
+                        examples: [
+                            JSON.stringify({ skill: SLOTLOCK_A2A_WATCH_SKILL, arguments: A2A_WATCH_EXAMPLE }),
+                        ],
+                        inputModes: ['application/json'],
+                        outputModes: ['application/json'],
+                    },
+                ]
+                : []),
+        ],
     });
 }
 export function createSlotlockAgentServer(options) {
@@ -2241,7 +2298,7 @@ export function createSlotlockAgentServer(options) {
         },
         capabilities: slotlockAgentTools(),
     });
-    const card = agentCard(config.publicBaseUrl);
+    const card = agentCard(config.publicBaseUrl, options.subscriptions !== false);
     const confirmation = validateConfirmation(options.confirmation);
     const emit = (event) => {
         try {
@@ -2268,7 +2325,7 @@ export function createSlotlockAgentServer(options) {
     /** 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);
+        const outcome = await invokeSlotlockAgentOperation({ ...args, origin: protocol });
         reportCall(protocol, args.operation, outcome.ok ? 'ok' : outcome.code, started, args.trace);
         return outcome;
     };
@@ -2306,6 +2363,10 @@ export function createSlotlockAgentServer(options) {
     /** Open subscriptions (and slots reserved by ones still opening), for the caps and shutdown. */
     const openSubscriptions = new Set();
     let shuttingDown = false;
+    /** One feed reader per tenant with an open subscription, when there is a feed to follow. */
+    const changeReaders = subscriptionPolicy?.changes
+        ? createSlotlockChangeReaders(subscriptionPolicy.changes, (error) => reportUnexpected(options.onError, error, null))
+        : null;
     const discoverResult = Object.freeze({
         supportedVersions: [...SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS],
         capabilities: {
@@ -2444,6 +2505,7 @@ export function createSlotlockAgentServer(options) {
         input: { resource_ids: resourceIds, start: window.start, end: window.end },
         request: call.request,
         options: dispatch,
+        origin: 'mcp',
         ...(call.trace ? { trace: call.trace } : {}),
     });
     /**
@@ -2462,6 +2524,7 @@ export function createSlotlockAgentServer(options) {
             input: cursor === undefined ? {} : { cursor },
             request: call.request,
             options: dispatchOptions(call.principal),
+            origin: 'mcp',
             ...(call.trace ? { trace: call.trace } : {}),
         });
         if (!outcome.ok) {
@@ -2560,22 +2623,10 @@ export function createSlotlockAgentServer(options) {
         return { ok: true, digests };
     }
     /**
-     * `subscriptions/listen` (2026-07-28 basic/patterns/subscriptions). The response is an SSE stream
-     * that opens with `notifications/subscriptions/acknowledged` naming the calendar resources this
-     * principal may watch, then carries `notifications/resources/updated` for each change until the
-     * client closes it or the server ends it gracefully (its duration, shutdown, lost access) with the
-     * request's result. Nothing is honored but resource subscriptions; a subscription honoring nothing
-     * ends right after its acknowledgment.
+     * A subscription slot for the principal, held while it opens so concurrent opens cannot
+     * overshoot the caps; null when a cap is reached. MCP subscriptions and A2A watches share them.
      */
-    async function modernListen(call) {
-        const { id, principal } = call;
-        if (!subscriptionPolicy)
-            return modernError(404, id, -32601, 'Method not found');
-        const filter = parseSubscriptionFilter(call.params.notifications);
-        if (!filter.ok)
-            return modernError(200, id, -32602, filter.message, filter.data);
-        if (shuttingDown)
-            return modernError(503, id, -32603, 'Server is shutting down');
+    function reserveSubscriptionSlot(policy, principal) {
         const principalKey = `${principal.tenantRef}\0${principal.subject}`;
         let held = 0;
         let heldByTenant = 0;
@@ -2585,9 +2636,9 @@ export function createSlotlockAgentServer(options) {
             if (open.tenantRef === principal.tenantRef)
                 heldByTenant += 1;
         }
-        if (openSubscriptions.size >= subscriptionPolicy.maxTotal &&
-            held < subscriptionPolicy.maxPerPrincipal &&
-            heldByTenant < subscriptionPolicy.maxPerTenant) {
+        if (openSubscriptions.size >= policy.maxTotal &&
+            held < policy.maxPerPrincipal &&
+            heldByTenant < policy.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.
@@ -2608,12 +2659,11 @@ export function createSlotlockAgentServer(options) {
             if (most.length > heldByTenant + 1)
                 most[0]?.end('preempted');
         }
-        if (openSubscriptions.size >= subscriptionPolicy.maxTotal ||
-            held >= subscriptionPolicy.maxPerPrincipal ||
-            heldByTenant >= subscriptionPolicy.maxPerTenant) {
-            return modernError(429, id, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, 'Too many subscriptions');
+        if (openSubscriptions.size >= policy.maxTotal ||
+            held >= policy.maxPerPrincipal ||
+            heldByTenant >= policy.maxPerTenant) {
+            return null;
         }
-        // The slot is held while access is checked, so concurrent opens cannot overshoot the caps.
         const slot = {
             principalKey,
             tenantRef: principal.tenantRef,
@@ -2621,13 +2671,43 @@ export function createSlotlockAgentServer(options) {
             end: () => { },
         };
         openSubscriptions.add(slot);
+        return slot;
+    }
+    /**
+     * The window a watch covers. A read's window rolls forward with the clock; a watch covers one
+     * fixed window that holds every window a read can return while it is open (from now to its last
+     * possible read's end), so a booking entering the rolling end is announced, and the clock alone
+     * changes nothing.
+     */
+    function watchWindow(policy) {
+        const window = calendarResourceWindow(Date.now(), resourceWindowDays);
+        window.end = new Date(Date.parse(window.end) + policy.maxDurationMs).toISOString();
+        return window;
+    }
+    /**
+     * `subscriptions/listen` (2026-07-28 basic/patterns/subscriptions). The response is an SSE stream
+     * that opens with `notifications/subscriptions/acknowledged` naming the calendar resources this
+     * principal may watch, then carries `notifications/resources/updated` for each change until the
+     * client closes it or the server ends it gracefully (its duration, shutdown, lost access) with the
+     * request's result. Nothing is honored but resource subscriptions; a subscription honoring nothing
+     * ends right after its acknowledgment.
+     */
+    async function modernListen(call) {
+        const { id, principal } = call;
+        if (!subscriptionPolicy)
+            return modernError(404, id, -32601, 'Method not found');
+        const filter = parseSubscriptionFilter(call.params.notifications);
+        if (!filter.ok)
+            return modernError(200, id, -32602, filter.message, filter.data);
+        if (shuttingDown)
+            return modernError(503, id, -32603, 'Server is shutting down');
+        const slot = reserveSubscriptionSlot(subscriptionPolicy, principal);
+        if (!slot) {
+            return modernError(429, id, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, 'Too many subscriptions');
+        }
         let streaming = false;
         try {
-            // A read's window rolls forward with the clock; a subscription watches one fixed window that
-            // holds every window a read can return while it is open (from now to its last possible read's
-            // end), so a booking entering the rolling end is announced, and the clock alone changes nothing.
-            const window = calendarResourceWindow(Date.now(), resourceWindowDays);
-            window.end = new Date(Date.parse(window.end) + subscriptionPolicy.maxDurationMs).toISOString();
+            const window = watchWindow(subscriptionPolicy);
             const watchable = await watchableCalendars(call, filter.resourceIds, window);
             if (!watchable.ok)
                 return modernFailure(id, watchable);
@@ -2644,12 +2724,153 @@ export function createSlotlockAgentServer(options) {
                 openSubscriptions.delete(slot);
         }
     }
+    /**
+     * Watch `watched.resourceIds` for the principal until the returned function is called: re-read
+     * their free/busy when the tenant's feed says a change touched one (and every `pollIntervalMs`
+     * regardless), and call `updated` for each whose free/busy changed. Every re-read authenticates
+     * the request's credentials again and must find the same principal, and is authorized like any
+     * read; neither the rate limiter nor a confirmation applies to reads the server makes on its own.
+     */
+    function watchResources(call, policy, window, watched, sink) {
+        const { principal, request } = call;
+        const stop = new AbortController();
+        let stopped = false;
+        let refreshing = false;
+        let again = false;
+        // The feed's cursor expired: the next read that succeeds announces every resource.
+        let owedAll = false;
+        let failures = 0;
+        let nextPoll;
+        // Changes coalesce: a re-read starts at most once every CHANGE_REREAD_MIN_MS.
+        let lastRefresh = 0;
+        let touchTimer;
+        const pollRequest = new Request(request.url, {
+            method: 'POST',
+            headers: request.headers,
+            signal: AbortSignal.any([request.signal, stop.signal]),
+        });
+        const pollDispatch = {
+            backend: options.backend,
+            authenticate: async (current) => {
+                const again = await options.authenticate(current);
+                return again?.subject === principal.subject && again.tenantRef === principal.tenantRef
+                    ? again
+                    : null;
+            },
+            authorize: options.authorize,
+            ...(options.onError ? { onError: options.onError } : {}),
+        };
+        const schedule = () => {
+            clearTimeout(nextPoll);
+            nextPoll = unref(setTimeout(() => void refresh(false), policy.pollIntervalMs));
+        };
+        const refresh = async (all) => {
+            if (stopped)
+                return;
+            if (all)
+                owedAll = true;
+            if (refreshing) {
+                again = true;
+                return;
+            }
+            refreshing = true;
+            lastRefresh = Date.now();
+            clearTimeout(nextPoll);
+            clearTimeout(touchTimer);
+            touchTimer = undefined;
+            try {
+                const outcome = await readFreeBusy({ request: pollRequest, trace: call.trace }, pollDispatch, watched.resourceIds, window);
+                if (stopped)
+                    return;
+                if (!outcome.ok) {
+                    if (outcome.status === 401 || INVISIBLE_STATUSES.has(outcome.status)) {
+                        sink.end('revoked');
+                        return;
+                    }
+                    failures += 1;
+                    if (failures >= MAX_POLL_FAILURES) {
+                        sink.end('failed');
+                        return;
+                    }
+                }
+                else {
+                    failures = 0;
+                    const announceAll = owedAll;
+                    owedAll = false;
+                    const digests = freeBusyDigests(outcome.data);
+                    for (const resourceId of watched.resourceIds) {
+                        const digest = digests.get(resourceId) ?? '';
+                        if (!announceAll && digest === watched.digests.get(resourceId))
+                            continue;
+                        watched.digests.set(resourceId, digest);
+                        sink.updated(resourceId);
+                    }
+                    if (!sink.healthy()) {
+                        sink.end('failed');
+                        return;
+                    }
+                }
+            }
+            catch {
+                sink.end('failed');
+                return;
+            }
+            finally {
+                refreshing = false;
+            }
+            if (stopped)
+                return;
+            schedule();
+            if (again) {
+                again = false;
+                touch(false);
+            }
+        };
+        const touch = (all) => {
+            if (stopped)
+                return;
+            if (all)
+                owedAll = true;
+            if (refreshing) {
+                again = true;
+                return;
+            }
+            const wait = lastRefresh + CHANGE_REREAD_MIN_MS - Date.now();
+            if (wait <= 0) {
+                void refresh(false);
+            }
+            else if (touchTimer === undefined) {
+                touchTimer = unref(setTimeout(() => {
+                    touchTimer = undefined;
+                    void refresh(false);
+                }, wait));
+            }
+        };
+        // The tenant's reader is shared and runs outside any request; this subscription's re-reads run
+        // in its own request's async context.
+        const watcher = {
+            resourceIds: new Set(watched.resourceIds),
+            touched: AsyncResource.bind(() => touch(false)),
+            resync: AsyncResource.bind(() => touch(true)),
+        };
+        const leave = changeReaders?.join(principal.tenantRef, watcher);
+        schedule();
+        return () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearTimeout(nextPoll);
+            clearTimeout(touchTimer);
+            stop.abort();
+            leave?.();
+        };
+    }
     function streamSubscription(call, policy, slot, window, watched) {
-        const { id, principal, request } = call;
+        const { id, request } = call;
         const subscriptionMeta = { [MCP_META_SUBSCRIPTION_ID]: id };
-        const stop = new AbortController();
         let ended = false;
         const timers = {};
+        let unwatch;
         const stream = openMcpEventStream(() => end('client'));
         const onAbort = () => end('client');
         function end(reason) {
@@ -2658,8 +2879,7 @@ export function createSlotlockAgentServer(options) {
             ended = true;
             clearInterval(timers.keepAlive);
             clearTimeout(timers.lifetime);
-            clearTimeout(timers.nextPoll);
-            stop.abort();
+            unwatch?.();
             request.signal.removeEventListener('abort', onAbort);
             openSubscriptions.delete(slot);
             // A server-side end the client should not retry is graceful: the listen request's result.
@@ -2704,73 +2924,176 @@ export function createSlotlockAgentServer(options) {
             return stream.response;
         }
         request.signal.addEventListener('abort', onAbort, { once: true });
-        // Every re-read authenticates the listen request's credentials again and must find the same
-        // principal, and is authorized like any read; neither the rate limiter nor a confirmation applies
-        // to reads the server makes on its own schedule.
-        const pollRequest = new Request(request.url, {
-            method: 'POST',
-            headers: request.headers,
-            signal: AbortSignal.any([request.signal, stop.signal]),
+        unwatch = watchResources(call, policy, window, watched, {
+            updated: (resourceId) => stream.send({
+                jsonrpc: '2.0',
+                method: 'notifications/resources/updated',
+                params: { _meta: subscriptionMeta, uri: slotlockCalendarResourceUri(resourceId) },
+            }),
+            healthy: () => !stream.lagging(),
+            end,
         });
-        const pollDispatch = {
-            backend: options.backend,
-            authenticate: async (current) => {
-                const again = await options.authenticate(current);
-                return again?.subject === principal.subject && again.tenantRef === principal.tenantRef
-                    ? again
-                    : null;
-            },
-            authorize: options.authorize,
-            ...(options.onError ? { onError: options.onError } : {}),
-        };
-        let failures = 0;
-        const poll = async () => {
-            try {
-                const outcome = await readFreeBusy({ request: pollRequest, trace: call.trace }, pollDispatch, watched.resourceIds, window);
-                if (ended)
-                    return;
-                if (!outcome.ok) {
-                    if (outcome.status === 401 || INVISIBLE_STATUSES.has(outcome.status)) {
-                        end('revoked');
-                        return;
-                    }
-                    failures += 1;
-                    if (failures >= MAX_POLL_FAILURES) {
-                        end('failed');
-                        return;
-                    }
-                }
-                else {
-                    failures = 0;
-                    const digests = freeBusyDigests(outcome.data);
-                    for (const resourceId of watched.resourceIds) {
-                        const digest = digests.get(resourceId) ?? '';
-                        if (digest === watched.digests.get(resourceId))
-                            continue;
-                        watched.digests.set(resourceId, digest);
-                        stream.send({
-                            jsonrpc: '2.0',
-                            method: 'notifications/resources/updated',
-                            params: { _meta: subscriptionMeta, uri: slotlockCalendarResourceUri(resourceId) },
-                        });
-                    }
-                    if (stream.lagging()) {
-                        end('failed');
-                        return;
-                    }
+        timers.keepAlive = unref(setInterval(() => {
+            if (!stream.keepAlive() || stream.lagging())
+                end('failed');
+        }, policy.keepAliveMs));
+        timers.lifetime = unref(setTimeout(() => end('duration'), policy.maxDurationMs));
+        return stream.response;
+    }
+    /**
+     * The A2A watch skill over `SendStreamingMessage`: the same caps, visibility check, feed and
+     * re-reads as an MCP subscription, framed as A2A 1.0 stream responses. The stream opens with the
+     * task (TASK_STATE_WORKING, naming the resources watched), carries a status update naming each
+     * resource whose free/busy changed, and ends with TASK_STATE_COMPLETED when its duration is up or
+     * the server shuts down, or TASK_STATE_FAILED when the credential or permission is withdrawn. A
+     * refusal before it opens is the skill's reply, as for any skill.
+     */
+    async function a2aWatch(args) {
+        const { id, request, principal, trace, contextId, reply } = args;
+        const policy = subscriptionPolicy;
+        if (!policy)
+            return reply({ error: { code: 'not_supported' } });
+        const given = args.input;
+        const requested = isRecord(given) ? given.resource_ids : undefined;
+        if (!isRecord(given) ||
+            Object.keys(given).some((key) => key !== 'resource_ids') ||
+            !Array.isArray(requested) ||
+            requested.length === 0 ||
+            requested.length > MAX_RESOURCE_SUBSCRIPTIONS ||
+            !requested.every((resourceId) => isCanonicalBoundedIdentifier(resourceId, 500))) {
+            return reply({ error: { code: 'invalid_arguments' } });
+        }
+        if (shuttingDown)
+            return json(200, rpcError(id, -32603, 'Server is shutting down'));
+        const slot = reserveSubscriptionSlot(policy, principal);
+        if (!slot) {
+            return a2aError(id, -32029, 'Too many subscriptions', {
+                reason: 'RATE_LIMITED',
+                domain: 'slotlock',
+            });
+        }
+        let streaming = false;
+        try {
+            const resourceIds = [...new Set(requested)];
+            const window = watchWindow(policy);
+            const call = { request, principal, trace };
+            const watchable = await watchableCalendars(call, resourceIds, window);
+            if (!watchable.ok) {
+                if (INTERNAL_FAILURES.has(watchable.code)) {
+                    return json(200, rpcError(id, -32603, 'Internal error'));
                 }
-                timers.nextPoll = unref(setTimeout(poll, policy.pollIntervalMs));
+                return reply({ error: { code: watchable.code } });
             }
-            catch {
-                end('failed');
+            const watched = {
+                resourceIds: resourceIds.filter((resourceId) => watchable.digests.has(resourceId)),
+                digests: watchable.digests,
+            };
+            if (watched.resourceIds.length === 0)
+                return reply({ error: { code: 'not_found' } });
+            if (shuttingDown)
+                return json(200, rpcError(id, -32603, 'Server is shutting down'));
+            streaming = true;
+            return streamA2AWatch({ id, request, principal, trace, contextId }, policy, slot, window, watched);
+        }
+        finally {
+            if (!streaming)
+                openSubscriptions.delete(slot);
+        }
+    }
+    function streamA2AWatch(call, policy, slot, window, watched) {
+        const { id, request, contextId } = call;
+        const taskId = `watch_${randomBytes(16).toString('base64url')}`;
+        let ended = false;
+        let unwatch;
+        const timers = {};
+        const stream = openMcpEventStream(() => end('client'));
+        const onAbort = () => end('client');
+        const status = (state, data) => ({
+            state,
+            timestamp: new Date().toISOString(),
+            ...(data === undefined
+                ? {}
+                : {
+                    message: {
+                        messageId: `msg_${randomBytes(16).toString('base64url')}`,
+                        contextId,
+                        taskId,
+                        role: 'ROLE_AGENT',
+                        parts: [{ data, mediaType: 'application/json' }],
+                    },
+                }),
+        });
+        const send = (result) => stream.send({ jsonrpc: '2.0', id, result });
+        function end(reason) {
+            if (ended)
+                return;
+            ended = true;
+            clearInterval(timers.keepAlive);
+            clearTimeout(timers.lifetime);
+            unwatch?.();
+            request.signal.removeEventListener('abort', onAbort);
+            openSubscriptions.delete(slot);
+            // A server-side end is the task's terminal state; a failure closes the stream without one,
+            // which a client may treat as a reason to watch again.
+            if (reason === 'revoked') {
+                send({
+                    statusUpdate: {
+                        taskId,
+                        contextId,
+                        status: status('TASK_STATE_FAILED', { error: { code: 'forbidden' } }),
+                    },
+                });
             }
-        };
+            else if (reason !== 'client' && reason !== 'failed') {
+                send({ statusUpdate: { taskId, contextId, status: status('TASK_STATE_COMPLETED') } });
+            }
+            stream.close();
+            emit({
+                type: 'subscription',
+                outcome: 'closed',
+                reason,
+                resources: watched.resourceIds.length,
+            });
+        }
+        slot.end = end;
+        slot.streaming = true;
+        send({
+            task: {
+                id: taskId,
+                contextId,
+                status: status('TASK_STATE_WORKING', {
+                    resources: watched.resourceIds.map((resourceId) => ({
+                        resource_id: resourceId,
+                        uri: slotlockCalendarResourceUri(resourceId),
+                    })),
+                }),
+            },
+        });
+        emit({ type: 'subscription', outcome: 'opened', resources: watched.resourceIds.length });
+        if (request.signal.aborted) {
+            end('client');
+            return stream.response;
+        }
+        request.signal.addEventListener('abort', onAbort, { once: true });
+        unwatch = watchResources(call, policy, window, watched, {
+            updated: (resourceId) => send({
+                statusUpdate: {
+                    taskId,
+                    contextId,
+                    status: status('TASK_STATE_WORKING', {
+                        resource_id: resourceId,
+                        uri: slotlockCalendarResourceUri(resourceId),
+                    }),
+                },
+            }),
+            healthy: () => !stream.lagging(),
+            end,
+        });
         timers.keepAlive = unref(setInterval(() => {
             if (!stream.keepAlive() || stream.lagging())
                 end('failed');
         }, policy.keepAliveMs));
         timers.lifetime = unref(setTimeout(() => end('duration'), policy.maxDurationMs));
-        timers.nextPoll = unref(setTimeout(poll, policy.pollIntervalMs));
         return stream.response;
     }
     /** One MCP 2026-07-28 request: stateless, validated against its own `_meta` and headers. */
@@ -2839,7 +3162,7 @@ export function createSlotlockAgentServer(options) {
             }
             const parsed = definition.input.safeParse(given);
             if (!parsed.success)
-                return { ok: false, status: 400, code: 'invalid_arguments' };
+                return invalidArguments(parsed.error);
             if (!(await served.authorize({ principal, operation: definition.name, input: parsed.data }))) {
                 return { ok: false, status: 403, code: 'forbidden' };
             }
@@ -2847,6 +3170,7 @@ export function createSlotlockAgentServer(options) {
                 principal,
                 operation: definition.name,
                 signal: request.signal,
+                origin: 'application',
             };
             if (trace)
                 context.trace = trace;
@@ -2985,6 +3309,7 @@ export function createSlotlockAgentServer(options) {
                 input: { ...given, ...params },
                 request,
                 options: withoutConfirmationRound(principal, route.operation),
+                origin: 'rest',
                 ...(trace ? { trace } : {}),
             });
         const internal = !outcome.ok && INTERNAL_FAILURES.has(outcome.code);
@@ -3001,6 +3326,7 @@ export function createSlotlockAgentServer(options) {
         return refuse(status, outcome.code, {}, {
             ...(outcome.code === 'overlap' ? refusedInterval(given) : {}),
             ...outcome.details,
+            ...(outcome.issues ? { issues: outcome.issues } : {}),
         });
     }
     return {
@@ -3263,7 +3589,7 @@ export function createSlotlockAgentServer(options) {
                 return a2aError(id, -32004, 'Unsupported operation', {
                     reason: 'UNSUPPORTED_OPERATION',
                     domain: 'a2a-protocol.org',
-                    metadata: { supportedMethods: 'SendMessage' },
+                    metadata: { supportedMethods: 'SendMessage, SendStreamingMessage' },
                 });
             }
             if (A2A_TASK_METHOD_FIELDS.has(rpc.method)) {
@@ -3282,7 +3608,8 @@ export function createSlotlockAgentServer(options) {
                 const pageSize = rpc.params?.pageSize ?? SLOTLOCK_A2A_TASK_PAGE_SIZE.default;
                 return json(200, rpcResult(id, { tasks: [], nextPageToken: '', pageSize, totalSize: 0 }));
             }
-            if (rpc.method !== 'SendMessage') {
+            const streamingRequest = rpc.method === 'SendStreamingMessage';
+            if (rpc.method !== 'SendMessage' && !streamingRequest) {
                 return json(200, rpcError(id, -32601, 'Method not found'));
             }
             const started = performance.now();
@@ -3291,7 +3618,8 @@ export function createSlotlockAgentServer(options) {
             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 watchSkill = data?.skill === SLOTLOCK_A2A_WATCH_SKILL;
+            const operation = watchSkill ? null : resolveSlotlockAgentOperation(data?.skill);
             // A refused message that names an operation is still a call, reported by the error's reason.
             const refuse = (outcome, response) => {
                 if (operation)
@@ -3312,7 +3640,7 @@ export function createSlotlockAgentServer(options) {
             }
             // `arguments` may be left out or null; anything else but an object is not arguments.
             const input = data?.arguments;
-            if (!operation ||
+            if ((!operation && !watchSkill) ||
                 message?.role !== 'ROLE_USER' ||
                 !isCanonicalBoundedIdentifier(message.messageId, 200) ||
                 message.taskId !== undefined ||
@@ -3326,6 +3654,44 @@ export function createSlotlockAgentServer(options) {
                     },
                 }));
             }
+            const requestedContextId = message.contextId;
+            const contextId = typeof requestedContextId === 'string' &&
+                requestedContextId.length > 0 &&
+                requestedContextId.length <= 200
+                ? requestedContextId
+                : `ctx_${createHash('sha256')
+                    .update(`${principal.tenantRef}\0${message.messageId}`)
+                    .digest('base64url')
+                    .slice(0, 32)}`;
+            const skillName = operation ?? SLOTLOCK_A2A_WATCH_SKILL;
+            // A skill's outcome is the agent's reply, success or not — the same contract as an MCP
+            // `isError` result, so the calling agent reads `{"error":{"code":…}}` and can act on it.
+            // Streamed, the reply is the stream's one event (A2A: a Message, then the stream closes).
+            const reply = (replyData) => {
+                const replyId = createHash('sha256')
+                    .update(`${principal.subject}\0${message.messageId}\0${skillName}`)
+                    .digest('base64url')
+                    .slice(0, 32);
+                const result = {
+                    message: {
+                        messageId: `reply_${replyId}`,
+                        contextId,
+                        role: 'ROLE_AGENT',
+                        parts: [{ data: replyData, mediaType: 'application/json' }],
+                    },
+                };
+                if (!streamingRequest)
+                    return json(200, rpcResult(id, result));
+                const stream = openMcpEventStream(() => { });
+                stream.send({ jsonrpc: '2.0', id, result });
+                stream.close();
+                return stream.response;
+            };
+            if (!operation) {
+                if (!streamingRequest)
+                    return reply({ error: { code: 'streaming_required' } });
+                return a2aWatch({ id, request, principal, trace, input, contextId, reply });
+            }
             try {
                 const outcome = await invokeReported('a2a', {
                     operation,
@@ -3337,36 +3703,15 @@ export function createSlotlockAgentServer(options) {
                 if (!outcome.ok && INTERNAL_FAILURES.has(outcome.code)) {
                     return json(200, rpcError(id, -32603, 'Internal error'));
                 }
-                const replyId = createHash('sha256')
-                    .update(`${principal.subject}\0${message.messageId}\0${operation}`)
-                    .digest('base64url')
-                    .slice(0, 32);
-                const requestedContextId = message.contextId;
-                const contextId = typeof requestedContextId === 'string' &&
-                    requestedContextId.length > 0 &&
-                    requestedContextId.length <= 200
-                    ? requestedContextId
-                    : `ctx_${createHash('sha256')
-                        .update(`${principal.tenantRef}\0${message.messageId}`)
-                        .digest('base64url')
-                        .slice(0, 32)}`;
-                // A skill's outcome is the agent's reply, success or not — the same contract as an MCP
-                // `isError` result, so the calling agent reads `{"error":{"code":…}}` and can act on it.
-                return json(200, rpcResult(id, {
-                    message: {
-                        messageId: `reply_${replyId}`,
-                        contextId,
-                        role: 'ROLE_AGENT',
-                        parts: [
-                            {
-                                data: outcome.ok
-                                    ? outcome.data
-                                    : { error: { ...outcome.details, code: outcome.code } },
-                                mediaType: 'application/json',
-                            },
-                        ],
-                    },
-                }));
+                return reply(outcome.ok
+                    ? outcome.data
+                    : {
+                        error: {
+                            ...outcome.details,
+                            code: outcome.code,
+                            ...(outcome.issues ? { issues: outcome.issues } : {}),
+                        },
+                    });
             }
             catch {
                 return json(200, rpcError(id, -32603, 'Internal error'));