slotlock 0.5.1 → 0.5.3

package/event-feed.d.ts

@@ -1,8 +1,30 @@
 import type { Sql, TransactionSql } from 'postgres';
 type SlotlockSql = Sql | TransactionSql;
 /** What a change can be, as the feed and a webhook's `event_types` name it. */
-export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "webhook.disabled"];
+export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "webhook.disabled", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
 export type SlotlockChangeType = (typeof SLOTLOCK_CHANGE_TYPES)[number];
+/**
+ * Where a change came from, as the history and the feed record it (withTenant's `origin`): an agent
+ * protocol (`mcp`, `a2a`), the REST API's agent routes (`rest`) or its application operations
+ * (`application`), the dashboard, a member's dashboard assistant, maintenance, or code calling the
+ * store itself (`library`). Never an address or anything else about a person.
+ */
+export declare const SLOTLOCK_CHANGE_ORIGINS: readonly ["mcp", "a2a", "rest", "application", "dashboard", "dashboard-assistant", "maintenance", "library"];
+export type SlotlockChangeOrigin = (typeof SLOTLOCK_CHANGE_ORIGINS)[number];
+/** Whether `value` is one of SLOTLOCK_CHANGE_ORIGINS. */
+export declare function isSlotlockChangeOrigin(value: unknown): value is SlotlockChangeOrigin;
+/**
+ * The SQL that names a coverage source on the feed (`coverage.recorded`, `.deleted`, `.stale`): a
+ * digest of the tenant and the source, stable for both, so the source itself (an iCalendar URL with
+ * a token, an address) never reaches a webhook or the history. `tenant` and `source` are SQL
+ * expressions; slotlockCoverageSourceId works out the same value.
+ */
+export declare function slotlockCoverageSourceIdSql(tenant: string, source: string): string;
+/**
+ * How the feed names a tenant's coverage source (`subject` and `data.source_id` of `coverage.*`
+ * changes; `source_id` of slotlock_get_coverage): `src_` and 24 hex digits.
+ */
+export declare function slotlockCoverageSourceId(tenantRef: string, source: string): string;
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export declare const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
@@ -20,6 +42,10 @@ export interface SlotlockChange {
     occurredAt: Date;
     /** Who made it (withTenant's `actor`: an API key, an agent), or null when unrecorded. */
     actor: string | null;
+    /** Where it came from (withTenant's `origin`), or null when unrecorded (before 0.6, say). */
+    origin: SlotlockChangeOrigin | null;
+    /** The API key that made it (withTenant's `keyId`), or null when no key did. */
+    keyId: string | null;
     /** Pass as `after` to read what follows this change. */
     position: string;
 }
@@ -150,9 +176,10 @@ export interface SlotlockEventFeed {
         };
     }): Promise<void>;
     /**
-     * History: the changes to one resource (`resourceId`) or one record (`subject`: a booking's
-     * reference, an event's or hold's id), newest first, `limit` (1-100) at a time, each with who
-     * made it and, for a change of an existing record, what it was before. Pass the last one's
+     * History: the changes to one resource (`resourceId`: its bookings and events, and its own
+     * configuration) or one record (`subject`: a booking's reference, an event's, hold's, webhook's or
+     * API key's id), newest first, `limit` (1-100) at a time, each with who made it (`actor`, `keyId`),
+     * where from (`origin`) and, for a change of an existing record, what it was before. Pass the last one's
      * `id` as `before` for the page after. Kept as long as the feed keeps changes.
      */
     listHistory(params: {
@@ -175,4 +202,10 @@ export declare function isWebhookUrl(value: unknown): value is string;
  * `retentionDays` (default SLOTLOCK_CHANGE_RETENTION_DAYS), and a cursor reaches back as far.
  */
 export declare function slotlockEventFeedMethods(sql: SlotlockSql, retentionDays?: number): SlotlockEventFeed;
+/**
+ * A position at or before every change that has not ended yet, so a reader that starts from it and
+ * follows `next` misses none still to come (it may read again some that ended just before). Live
+ * updates start here (agent-store-backend.ts, createSlotlockStoreChangeSource).
+ */
+export declare function slotlockChangeFeedHead(sql: SlotlockSql): Promise<string>;
 export {};

package/event-feed.js

@@ -2,7 +2,7 @@
 // endpoints it is delivered to. Rows are appended by triggers in the same transaction as the change
 // (ddl.ts, SLOTLOCK_OUTBOX_DDL). These are the store's methods for reading them and for keeping each
 // endpoint's delivery state; webhooks.ts signs and sends.
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 /** A transaction on a client, or a savepoint inside the caller's (a tenant's, say). */
 async function inTransaction(sql, callback) {
     return ('begin' in sql ? sql.begin(callback) : sql.savepoint(callback));
@@ -28,7 +28,58 @@ export const SLOTLOCK_CHANGE_TYPES = Object.freeze([
     'waitlist.offered',
     'waitlist.expired',
     'webhook.disabled',
+    // Configuration: what a resource is and how it books, the sources it is read from, where the
+    // feed is delivered and the keys that reach the tenant. Ids and states, never a secret or a URL.
+    'resource.created',
+    'resource.updated',
+    'resource.archived',
+    'resource.restored',
+    'resource.deleted',
+    'coverage.recorded',
+    'coverage.deleted',
+    'webhook.created',
+    'webhook.enabled',
+    'webhook.deleted',
+    'key.created',
+    'key.rotated',
+    'key.revoked',
 ]);
+/**
+ * Where a change came from, as the history and the feed record it (withTenant's `origin`): an agent
+ * protocol (`mcp`, `a2a`), the REST API's agent routes (`rest`) or its application operations
+ * (`application`), the dashboard, a member's dashboard assistant, maintenance, or code calling the
+ * store itself (`library`). Never an address or anything else about a person.
+ */
+export const SLOTLOCK_CHANGE_ORIGINS = Object.freeze([
+    'mcp',
+    'a2a',
+    'rest',
+    'application',
+    'dashboard',
+    'dashboard-assistant',
+    'maintenance',
+    'library',
+]);
+/** Whether `value` is one of SLOTLOCK_CHANGE_ORIGINS. */
+export function isSlotlockChangeOrigin(value) {
+    return typeof value === 'string' && SLOTLOCK_CHANGE_ORIGINS.includes(value);
+}
+/**
+ * The SQL that names a coverage source on the feed (`coverage.recorded`, `.deleted`, `.stale`): a
+ * digest of the tenant and the source, stable for both, so the source itself (an iCalendar URL with
+ * a token, an address) never reaches a webhook or the history. `tenant` and `source` are SQL
+ * expressions; slotlockCoverageSourceId works out the same value.
+ */
+export function slotlockCoverageSourceIdSql(tenant, source) {
+    return `'src_' || left(encode(sha256(convert_to(${tenant} || E'\\n' || ${source}, 'UTF8')), 'hex'), 24)`;
+}
+/**
+ * How the feed names a tenant's coverage source (`subject` and `data.source_id` of `coverage.*`
+ * changes; `source_id` of slotlock_get_coverage): `src_` and 24 hex digits.
+ */
+export function slotlockCoverageSourceId(tenantRef, source) {
+    return `src_${createHash('sha256').update(`${tenantRef}\n${source}`, 'utf8').digest('hex').slice(0, 24)}`;
+}
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
@@ -58,6 +109,9 @@ function toChange(row) {
         data: row.data,
         occurredAt: row.occurred_at,
         actor: row.actor,
+        // One a later release added, read by this one: unknown here, so unrecorded, not a failed page.
+        origin: isSlotlockChangeOrigin(row.origin) ? row.origin : null,
+        keyId: row.key_id,
         position: encodePosition({ txid: row.txid, id: row.id, at: row.occurred_at.getTime() }),
     };
 }
@@ -127,7 +181,7 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
         SELECT mark.txid::text AS pruned_txid, mark.id::text AS pruned_id,
                pg_snapshot_xmin(pg_current_snapshot())::text AS horizon,
                page.id::text, page.txid::text, page.type, page.resource_id, page.subject,
-               page.data, page.occurred_at, page.actor
+               page.data, page.occurred_at, page.actor, page.origin, page.key_id::text
           FROM (SELECT 1) here
           LEFT JOIN slotlock.outbox_pruned mark ON mark.tenant_ref = ${params.tenantRef}
           LEFT JOIN LATERAL (
@@ -179,7 +233,8 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
                 });
             }
             const rows = await sql `
-        SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor
+        SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor, origin,
+               key_id::text
           FROM slotlock.outbox
          WHERE tenant_ref = ${params.tenantRef}
          ORDER BY txid DESC, id DESC
@@ -194,7 +249,6 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             const types = params.eventTypes === undefined ? null : [...new Set(params.eventTypes)];
             if (types !== null &&
                 (types.length === 0 ||
-                    types.length > 20 ||
                     !types.every((type) => SLOTLOCK_CHANGE_TYPES.includes(type)))) {
                 return { ok: false, code: 'invalid_event_types' };
             }
@@ -300,7 +354,8 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             const claims = [];
             for (const endpoint of endpoints) {
                 const rows = await sql `
-          SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor
+          SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor, origin,
+               key_id::text
             FROM slotlock.outbox
            WHERE tenant_ref = ${params.tenantRef}
              AND txid < pg_snapshot_xmin(pg_current_snapshot())
@@ -393,7 +448,8 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             if (before === undefined)
                 return [];
             const rows = await sql `
-        SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor
+        SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor, origin,
+               key_id::text
           FROM slotlock.outbox
          WHERE tenant_ref = ${params.tenantRef}
            AND (${params.resourceId ?? null}::uuid IS NULL OR resource_id = ${params.resourceId ?? null}::uuid)
@@ -445,3 +501,15 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
         },
     };
 }
+/**
+ * A position at or before every change that has not ended yet, so a reader that starts from it and
+ * follows `next` misses none still to come (it may read again some that ended just before). Live
+ * updates start here (agent-store-backend.ts, createSlotlockStoreChangeSource).
+ */
+export async function slotlockChangeFeedHead(sql) {
+    const [row] = await sql `
+    SELECT pg_snapshot_xmin(pg_current_snapshot())::text AS horizon`;
+    if (!row)
+        throw new Error('slotlock: change feed head returned no row');
+    return encodePosition({ txid: row.horizon, id: '0', at: Date.now() });
+}

package/index.d.ts

@@ -1,8 +1,8 @@
 /// <reference types="node" preserve="true" />
 export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
-export { type SlotlockBookingRule, type SlotlockBookingRules, bookingRuleBroken, bookingSearch, nextStepStart, parseBookingRules, } from './booking-rules.js';
-export { type CreateWebhookEndpointResult, type ListChangesResult, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, type SlotlockChange, type SlotlockChangeType, type SlotlockEventFeed, type SlotlockWebhookClaim, type SlotlockWebhookEndpoint, } from './event-feed.js';
-export { type SlotlockCloudEvent, type SlotlockWebhookPassResult, type SlotlockWebhookResponse, type SlotlockWebhookScheduler, type SlotlockWebhookSender, createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
+export { type SlotlockBookingRule, type SlotlockBookingRules, type SlotlockBookingSearch, bookingRuleBroken, bookingSearch, bookingSearchBlocked, bookingSearchReach, nextStepStart, parseBookingRuleDefaults, parseBookingRules, } from './booking-rules.js';
+export { type CreateWebhookEndpointResult, type ListChangesResult, SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, slotlockChangeFeedHead, type SlotlockChange, type SlotlockChangeOrigin, type SlotlockChangeType, type SlotlockEventFeed, type SlotlockWebhookClaim, type SlotlockWebhookEndpoint, slotlockCoverageSourceId, } from './event-feed.js';
+export { type SlotlockCloudEvent, type SlotlockWebhookPassResult, type SlotlockWebhookResponse, type SlotlockWebhookScheduler, type SlotlockWebhookSender, createSlotlockGuardedFetch, createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
 export { type SlotlockMetrics, createSlotlockMetrics } from './metrics.js';
 export { expandRules } from './rules.js';
 export { availabilityRuleProblem, parseAvailabilityRules, rulesToWeeklyHours, SLOTLOCK_MAX_AVAILABILITY_RULES, weeklyHoursToRules, } from './weekly-hours.js';
@@ -11,11 +11,12 @@ export { emitVAvailability, parseVAvailability, recurrenceRuleFromRRule, SLOTLOC
 export type { EmitVAvailabilityOptions, JSCalendarAlert, JSCalendarEvent, JSCalendarParticipant, JSCalendarRecurrenceRule, ParsedVAvailability, } from './interop.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
 export type { LocalDateTime, TimeZoneConverter, ZonedCalendarDate, ZonedWallTime, } from './timezone.js';
-export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
+export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
 export type { SlotlockAgentCalendarBackend, SlotlockAgentConfirmationOptions, SlotlockAgentErrorContext, SlotlockAgentInvocationContext, SlotlockAgentOperation, SlotlockAgentOperationDispatchOptions, SlotlockAgentOperationDispatchResult, SlotlockAgentPrincipal, SlotlockAgentScope, SlotlockAgentServerEvent, SlotlockAgentServerOAuthOptions, SlotlockAgentServerOptions, SlotlockAgentSubscriptionOptions, SlotlockAgentWriteOperation, SlotlockMcpToolResult, SlotlockTraceContext, } from './agent-server.js';
 export { createSlotlockNodeServer } from './node-server.js';
 export type { SlotlockNodeListenOptions, SlotlockNodeServer, SlotlockNodeServerAddress, SlotlockNodeServerCloseResult, SlotlockNodeServerErrorPhase, SlotlockNodeServerFetchTarget, SlotlockNodeServerOptions, } from './node-server.js';
-export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { SLOTLOCK_FEED_BUSY_MS, SLOTLOCK_FEED_IDLE_MS, type SlotlockAgentChange, type SlotlockAgentChangeSource, } from './change-watch.js';
 export type { SlotlockStoreAgentBackendOptions, SlotlockStoreApplicationBackendOptions, } from './agent-store-backend.js';
 export { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, } from './application-api.js';
 export type { SlotlockApplicationBackend, SlotlockApplicationInvocationContext, SlotlockApplicationOperation, SlotlockApplicationOperationDefinition, } from './application-api.js';
@@ -23,12 +24,14 @@ export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenan
 export type { SlotlockMaintenanceResult, SlotlockMaintenanceScheduler, SlotlockMaintenanceSchedulerOptions, } from './maintenance.js';
 export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
 export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
-export type { SlotlockDashboard, SlotlockDashboardOptions, SlotlockDashboardResources, SlotlockDashboardState, } from './dashboard.js';
-export type { CreateSlotlockApiKeyInput, SlotlockApiKey, SlotlockApiKeyAuthenticatorOptions, SlotlockApiKeyIdentity, SlotlockApiKeyScope, SlotlockApiKeyStore, } from './api-keys.js';
+export type { SlotlockDashboard, SlotlockDashboardAssistantOptions, SlotlockDashboardOptions, SlotlockDashboardResources, SlotlockDashboardState, } from './dashboard.js';
+export { createSlotlockAssistantStore, createSlotlockMemoryAssistantStore, SLOTLOCK_ASSISTANT_TOOL_USE, } from './assistant.js';
+export type { SlotlockAssistantStore } from './assistant.js';
+export type { CreateSlotlockApiKeyInput, SlotlockApiKey, SlotlockApiKeyAuthenticatorOptions, SlotlockApiKeyChange, SlotlockApiKeyIdentity, SlotlockApiKeyScope, SlotlockApiKeyStore, } from './api-keys.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
 export type { ICalendarWorkerPool, ICalendarWorkerPoolOptions } from './ical-worker.js';
 export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } from './sync.js';
 export type { ExternalCalendarChange, ExternalCalendarChangeInput, ExternalCalendarStatus, ICalendarEvent, ICalendarExpansionWindow, ICalendarFeedRead, ICalendarSeriesRefusal, ITipMethod, } from './sync.js';
 export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
 export { assertSlotlockSchemaCurrent, calendarEventRollingHorizon, createSlotlockStore, readSlotlockSchemaVersion, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MATERIALIZATION_WINDOW_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, SLOTLOCK_TENANT_WRITE_METHODS, type SlotlockHoldTenantOptions, type SlotlockMigrationOptions, type SlotlockSql, type SlotlockStore, type SlotlockStoreOptions, type SlotlockTenantLimits, type SlotlockTenantStore, } from './store.js';
-export type { AcquireHoldResult, BookingRetentionResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockAgendaEntry, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';
+export type { AcquireHoldResult, BookingRetentionResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockAgendaEntry, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, SlotlockBookingRuleDefaults, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';

package/index.js

@@ -4,21 +4,23 @@
 // TypeScript 6 default) still loads @types/node.
 /// <reference types="node" preserve="true" />
 export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
-export { bookingRuleBroken, bookingSearch, nextStepStart, parseBookingRules, } from './booking-rules.js';
-export { SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, } from './event-feed.js';
-export { createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
+export { bookingRuleBroken, bookingSearch, bookingSearchBlocked, bookingSearchReach, nextStepStart, parseBookingRuleDefaults, parseBookingRules, } from './booking-rules.js';
+export { SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, slotlockChangeFeedHead, slotlockCoverageSourceId, } from './event-feed.js';
+export { createSlotlockGuardedFetch, createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
 export { createSlotlockMetrics } from './metrics.js';
 export { expandRules } from './rules.js';
 export { availabilityRuleProblem, parseAvailabilityRules, rulesToWeeklyHours, SLOTLOCK_MAX_AVAILABILITY_RULES, weeklyHoursToRules, } from './weekly-hours.js';
 export { emitVAvailability, parseVAvailability, recurrenceRuleFromRRule, SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS, toJSCalendarEvent, } from './interop.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
-export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
+export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
 export { createSlotlockNodeServer } from './node-server.js';
-export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { SLOTLOCK_FEED_BUSY_MS, SLOTLOCK_FEED_IDLE_MS, } from './change-watch.js';
 export { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, } from './application-api.js';
 export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
 export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
+export { createSlotlockAssistantStore, createSlotlockMemoryAssistantStore, SLOTLOCK_ASSISTANT_TOOL_USE, } from './assistant.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
 export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } from './sync.js';
 export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';

package/maintenance.d.ts

@@ -10,7 +10,8 @@ export interface SlotlockMaintenanceResult {
     /**
      * Expired holds and the answers kept for keyed ones, and past the retention window event
      * idempotency answers, agents' event cancellations, booking references retired with no
-     * booking and feed changes, deleted. A cancelled booking's tombstone stays.
+     * booking and feed changes, deleted, and dashboard assistant conversations past their expiry.
+     * A cancelled booking's tombstone stays.
      */
     pruned: number;
     /**

package/maintenance.js

@@ -1,5 +1,5 @@
 import { ignoreRejection } from './hooks.js';
-import { SLOTLOCK_MAX_WAITLIST_PER_TENANT, calendarEventRollingHorizon } from './store.js';
+import { SLOTLOCK_MAX_WAITLIST_PER_TENANT, calendarEventRollingHorizon, } from './store.js';
 /**
  * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then purge
  * its expired holds with their answers and prune its events' and bookings' bookkeeping past the
@@ -11,6 +11,8 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     if (!(Number.isSafeInteger(batches) && batches >= 1 && batches <= 100)) {
         throw new RangeError('batches must be a whole number from 1 to 100');
     }
+    // What a pass changes (a no-show released, a waitlist offer) is recorded as maintenance's.
+    const withTenant = (callback) => store.withTenant(tenantRef, callback, { origin: 'maintenance' });
     const window = calendarEventRollingHorizon();
     let extended = 0;
     let conflicts = 0;
@@ -24,7 +26,7 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
         for (let batch = 0; batch < batches; batch++) {
             options.signal?.throwIfAborted();
             const from = after;
-            const roll = await store.withTenant(tenantRef, (tenant) => tenant.rollCalendarEventHorizon({ tenantRef, window, ...(from ? { after: from } : {}) }));
+            const roll = await withTenant((tenant) => tenant.rollCalendarEventHorizon({ tenantRef, window, ...(from ? { after: from } : {}) }));
             extended += roll.extended;
             conflicts += roll.conflicts;
             refused += roll.refused;
@@ -47,26 +49,29 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     for (let batch = 0; batch < batches && (eventsLeft || bookingsLeft || changesLeft); batch++) {
         options.signal?.throwIfAborted();
         if (eventsLeft) {
-            const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
+            const prune = await withTenant((tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
             pruned += prune.commandsDeleted + prune.tombstonesDeleted;
             eventsLeft = prune.hasMore;
         }
         if (bookingsLeft) {
-            const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneBookingRetention({ tenantRef }));
+            const prune = await withTenant((tenant) => tenant.pruneBookingRetention({ tenantRef }));
             pruned += prune.expiredHoldsDeleted + prune.holdCommandsDeleted + prune.tombstonesDeleted;
             bookingsLeft = prune.hasMore;
         }
         if (changesLeft) {
-            const deleted = await store.withTenant(tenantRef, (tenant) => tenant.pruneChanges({ tenantRef, limit: CHANGE_PRUNE_BATCH }));
+            const deleted = await withTenant((tenant) => tenant.pruneChanges({ tenantRef, limit: CHANGE_PRUNE_BATCH }));
             pruned += deleted;
             changesLeft = deleted === CHANGE_PRUNE_BATCH;
         }
     }
     options.signal?.throwIfAborted();
-    const zones = await store.withTenant(tenantRef, (tenant) => tenant.followZoneRules({ tenantRef, move: options.followZoneRules === true }));
-    const staleSources = await store.withTenant(tenantRef, (tenant) => tenant.reportStaleCoverage({ tenantRef }));
+    // Conversations last 2 hours after their last message (dashboard.ts): an expired one is
+    // unreadable already, and deleted here.
+    pruned += await withTenant((tenant) => tenant.pruneAssistantConversations({ tenantRef }));
+    const zones = await withTenant((tenant) => tenant.followZoneRules({ tenantRef, move: options.followZoneRules === true }));
+    const staleSources = await withTenant((tenant) => tenant.reportStaleCoverage({ tenantRef }));
     // No-shows first: the time they free is offered to the waitlist in the same pass.
-    const noShows = await store.withTenant(tenantRef, (tenant) => tenant.releaseNoShows({ tenantRef }));
+    const noShows = await withTenant((tenant) => tenant.releaseNoShows({ tenantRef }));
     // The whole waitlist, in join order, a page at a time and each page its own transaction, so a
     // later entry whose window is free is offered however many wait before it.
     let waitlistOffers = 0;
@@ -74,7 +79,7 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     for (let pages = 0; pages < WAITLIST_PAGES; pages++) {
         options.signal?.throwIfAborted();
         const from = page;
-        const offers = await store.withTenant(tenantRef, (tenant) => tenant.offerWaitlist({ tenantRef, ...(from ? { after: from } : {}) }));
+        const offers = await withTenant((tenant) => tenant.offerWaitlist({ tenantRef, ...(from ? { after: from } : {}) }));
         waitlistOffers += offers.offered;
         page = offers.next;
         if (!page)
@@ -97,6 +102,8 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
 }
 /** Pages of 50 that cover a tenant's whole waitlist (SLOTLOCK_MAX_WAITLIST_PER_TENANT). */
 const WAITLIST_PAGES = Math.ceil(SLOTLOCK_MAX_WAITLIST_PER_TENANT / 50);
+/** How often the scheduler sweeps every tenant's expired assistant conversations, at most. */
+const SWEEP_INTERVAL_MS = 15 * 60_000;
 /** Feed changes past the retention deleted per batch. */
 const CHANGE_PRUNE_BATCH = 1_000;
 /** The advisory lock key for one tenant's maintenance (64-bit, from the tenant reference). */
@@ -208,11 +215,28 @@ export function startSlotlockMaintenance(options) {
             working = null;
         }
     };
+    // Expired assistant conversations of every tenant, the ones whose keys never call included (a
+    // tenant only the dashboard serves): one bounded sweep at most every quarter hour.
+    let lastSweep = 0;
+    const sweep = () => {
+        if (controller.signal.aborted || Date.now() - lastSweep < Math.min(intervalMs, SWEEP_INTERVAL_MS))
+            return;
+        lastSweep = Date.now();
+        options.store.sweepAssistantConversations().catch((error) => {
+            try {
+                ignoreRejection(options.onError?.(error));
+            }
+            catch {
+                // Reporting must never stop maintenance.
+            }
+        });
+    };
     const tick = () => {
         for (const tenantRef of [...pinned.keys(), ...served.keys()]) {
             if (due(tenantRef))
                 enqueue(tenantRef);
         }
+        sweep();
     };
     const timer = setInterval(tick, Math.min(intervalMs, 60_000));
     timer.unref();