slotlock 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotlock",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "license": "Apache-2.0",

package/rate-limit.d.ts

@@ -76,5 +76,13 @@ export declare function slotlockClientKey(value: string): string | null;
  * client shares; per /48, a site counts as one, as a site behind one IPv4 address does.
  */
 export declare function slotlockClientNetwork(key: string): string;
+/**
+ * One token bucket per key at `rate`, kept in this process like serve's own: `take` spends a token
+ * of the key's bucket and is false, spending nothing, when it has less than one. The dashboard
+ * assistant limits each member's messages with it.
+ */
+export declare function createSlotlockRateLimiter(rate: SlotlockRate, now?: () => number): {
+    take(key: string): boolean;
+};
 /** The limits `slotlock serve` puts in front of its agent server and dashboard. */
 export declare function createSlotlockRequestLimits(options: SlotlockRequestLimitsOptions): SlotlockRequestLimits;

package/rate-limit.js

@@ -202,6 +202,26 @@ function bucketsFor(rate, now) {
         },
     };
 }
+/**
+ * One token bucket per key at `rate`, kept in this process like serve's own: `take` spends a token
+ * of the key's bucket and is false, spending nothing, when it has less than one. The dashboard
+ * assistant limits each member's messages with it.
+ */
+export function createSlotlockRateLimiter(rate, now = () => performance.now()) {
+    if (!(rate.perSecond > 0) || !(rate.burst >= 1)) {
+        throw new Error('Slotlock rate limiter needs a positive rate and a burst of at least 1');
+    }
+    const buckets = bucketsFor(rate, now);
+    return {
+        take(key) {
+            const bucket = buckets.get(key, now());
+            if (bucket.tokens < 1)
+                return false;
+            bucket.tokens -= 1;
+            return true;
+        },
+    };
+}
 /**
  * Slots, at most `perKey` running for a key and `total` in all, shared between keys by how much
  * each asks for. A key's use is how long the event loop was busy while its writes held a slot,

package/self-host.d.ts

@@ -5,7 +5,7 @@ import { type SlotlockSql, type SlotlockStore } from './store.js';
 import type { WeeklyAvailabilityRule } from './types.js';
 export { SlotlockConfigError, type SlotlockEnv, type SlotlockServeDashboardConfig };
 /** Every variable the commands read. The README, `.env.example` and `server.json` document these. */
-export declare const SLOTLOCK_ENVIRONMENT_VARIABLES: readonly ["DATABASE_URL", "SLOTLOCK_MIGRATE_DATABASE_URL", "SLOTLOCK_AUTH_TOKEN", "SLOTLOCK_CONFIRMATION_SECRET", "SLOTLOCK_CONFIRM_WRITES", "SLOTLOCK_METRICS_TOKEN", "SLOTLOCK_PUBLIC_URL", "SLOTLOCK_TENANT", "SLOTLOCK_AVAILABILITY", "SLOTLOCK_REST_API", "SLOTLOCK_RETENTION_DAYS", "SLOTLOCK_WEBHOOKS", "SLOTLOCK_SHARED_LIMITS", "SLOTLOCK_LIMITS", "SLOTLOCK_TRUSTED_PROXY_HEADER", "SLOTLOCK_GITHUB_CLIENT_ID", "SLOTLOCK_GITHUB_CLIENT_SECRET", "SLOTLOCK_SESSION_SECRET", "SLOTLOCK_DASHBOARD_USERS", "SLOTLOCK_DASHBOARD_ORGS", "SLOTLOCK_DASHBOARD_NAME", "HOST", "PORT"];
+export declare const SLOTLOCK_ENVIRONMENT_VARIABLES: readonly ["DATABASE_URL", "SLOTLOCK_MIGRATE_DATABASE_URL", "SLOTLOCK_AUTH_TOKEN", "SLOTLOCK_CONFIRMATION_SECRET", "SLOTLOCK_CONFIRM_WRITES", "SLOTLOCK_METRICS_TOKEN", "SLOTLOCK_PUBLIC_URL", "SLOTLOCK_TENANT", "SLOTLOCK_AVAILABILITY", "SLOTLOCK_REST_API", "SLOTLOCK_RETENTION_DAYS", "SLOTLOCK_WEBHOOKS", "SLOTLOCK_SHARED_LIMITS", "SLOTLOCK_LIMITS", "SLOTLOCK_TRUSTED_PROXY_HEADER", "SLOTLOCK_GITHUB_CLIENT_ID", "SLOTLOCK_GITHUB_CLIENT_SECRET", "SLOTLOCK_SESSION_SECRET", "SLOTLOCK_ASSISTANT_SECRET", "SLOTLOCK_ASSISTANT_PRIVATE_URLS", "SLOTLOCK_DASHBOARD_USERS", "SLOTLOCK_DASHBOARD_ORGS", "SLOTLOCK_DASHBOARD_NAME", "HOST", "PORT"];
 export interface SlotlockDatabaseConfig {
     /** The role `serve` and `resource` connect as. */
     databaseUrl: string;
@@ -124,7 +124,7 @@ export declare function createSlotlockMaintenanceStore(sql: SlotlockSql, caps: S
 }): SlotlockStore;
 /** Serve MCP and A2A over HTTP from the Postgres store, as one token-authenticated tenant. */
 export declare function startSlotlockServer(config: SlotlockServeConfig, log: SlotlockLogger): Promise<SlotlockRunningServer>;
-export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);\n                           maintains each tenant it serves every hour\n  maintain                 Run maintenance for the tenant now: extend recurring events to the\n                           rolling horizon and prune past the retention window (for cron)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and\n                           no longer listed; what is on it stays\n  resource restore <ref>   Put an archived resource back in use\n  resource delete <ref>    Delete a resource and its history; refused while a booking, hold\n                           or event on it has not ended\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  rules set <json> --resource <ref>\n                           Set what a booking on the resource must satisfy, like\n                           {\"minNoticeMinutes\":120,\"slotStepMinutes\":30,\"turnaroundMinutes\":30,\"enforceHours\":true}\n  rules clear --resource <ref>\n                           Remove the resource's booking rules\n  key create <name> [--scope read,write,admin] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry; admin adds the application API) and print it once; only its\n                           SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  tenant status            Print whether the tenant is suspended\n  tenant suspend [--reason <text>]\n                           Suspend the tenant: it may read, and writes nothing; its keys get\n                           no new secret (as SLOTLOCK_MIGRATE_DATABASE_URL's role when set:\n                           only the schema owner suspends)\n  tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)\n  tenant erase --confirm <tenant>\n                           Delete everything the tenant has, its API keys included, for good;\n                           --confirm repeats SLOTLOCK_TENANT\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with read and write\n                                 access (never admin), 32+ random characters (serve); API keys\n                                 work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;\n                                 required when SLOTLOCK_CONFIRM_WRITES is not none)\n  SLOTLOCK_METRICS_TOKEN         Serves Prometheus metrics at /metrics to this bearer token, 32+\n                                 random characters (serve; off without it)\n  SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools\n                                 that wait for a person (MCP 2026-07-28 form elicitation; refused\n                                 with confirmation_required on REST, A2A and older MCP)\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and\n                                 the application API for admin keys, described at /openapi.json;\n                                 off: MCP and A2A only\n  SLOTLOCK_RETENTION_DAYS        Days of history kept: the change feed, ended waitlist entries,\n                                 and retired answers (never under 30) (1-3650, default 30;\n                                 serve and maintain)\n  SLOTLOCK_SHARED_LIMITS         on: tenant request budgets are shared by every server through the\n                                 database, so N servers allow a tenant its rate once; off (default):\n                                 each server keeps its own\n  SLOTLOCK_WEBHOOKS              on (default): deliver each tenant's changes to its webhooks,\n                                 never to a private network address; private: those too, for\n                                 testing; off: keep the change feed, send nothing\n  SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:\n                                 rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,\n                                 every request per client, before any key lookup), key_read,\n                                 tenant_read (20/s:40), key_write, tenant_write (5/s:20),\n                                 global_read (500/s:1000), global_write (50/s:100), app_read\n                                 (20/s:40) and app_write (5/s:20) per tenant for the\n                                 application API, sign_in (20/m:20); counts for\n                                 tenant_series_writes and series_writes\n                                 (1: writes that may expand a recurring series at once),\n                                 maintenance_runs (1: application API maintenance runs at once),\n                                 subscriptions (256), tenant_subscriptions (16),\n                                 key_subscriptions (4, and fewer than tenant_subscriptions),\n                                 key_lookups (2), key_lookup_queue (256),\n                                 tenant_transactions (2: one tenant's database transactions at\n                                 once, of the pool's 10); what one tenant may store:\n                                 tenant_holds (10000), tenant_reservations, tenant_events and\n                                 tenant_coverage (100000), holder_holds (20) and\n                                 holder_held_hours (2160), which maintain keeps too\n  SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,\n                                 such as CF-Connecting-IP (default: the connection's address);\n                                 set it only when every request comes through that proxy\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant\n  SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
+export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);\n                           maintains each tenant it serves every hour\n  maintain                 Run maintenance for the tenant now: extend recurring events to the\n                           rolling horizon and prune past the retention window (for cron)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and\n                           no longer listed; what is on it stays\n  resource restore <ref>   Put an archived resource back in use\n  resource delete <ref>    Delete a resource and its history; refused while a booking, hold\n                           or event on it has not ended\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  rules set <json> --resource <ref>\n                           Set what a booking on the resource must satisfy, like\n                           {\"minNoticeMinutes\":120,\"slotStepMinutes\":30,\"turnaroundMinutes\":30,\"enforceHours\":true}\n  rules clear --resource <ref>\n                           Remove the resource's booking rules\n  key create <name> [--scope read,write,admin] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry; admin adds the application API) and print it once; only its\n                           SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  tenant status            Print whether the tenant is suspended\n  tenant suspend [--reason <text>]\n                           Suspend the tenant: it may read, and writes nothing; its keys get\n                           no new secret (as SLOTLOCK_MIGRATE_DATABASE_URL's role when set:\n                           only the schema owner suspends)\n  tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)\n  tenant erase --confirm <tenant>\n                           Delete everything the tenant has, its API keys included, for good;\n                           --confirm repeats SLOTLOCK_TENANT\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with read and write\n                                 access (never admin), 32+ random characters (serve); API keys\n                                 work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;\n                                 required when SLOTLOCK_CONFIRM_WRITES is not none)\n  SLOTLOCK_METRICS_TOKEN         Serves Prometheus metrics at /metrics to this bearer token, 32+\n                                 random characters (serve; off without it)\n  SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools\n                                 that wait for a person (MCP 2026-07-28 form elicitation; refused\n                                 with confirmation_required on REST, A2A and older MCP)\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and\n                                 the application API for admin keys, described at /openapi.json;\n                                 off: MCP and A2A only\n  SLOTLOCK_RETENTION_DAYS        Days of history kept: the change feed, ended waitlist entries,\n                                 and retired answers (never under 30) (1-3650, default 30;\n                                 serve and maintain)\n  SLOTLOCK_SHARED_LIMITS         on: tenant request budgets are shared by every server through the\n                                 database, so N servers allow a tenant its rate once; off (default):\n                                 each server keeps its own\n  SLOTLOCK_WEBHOOKS              on (default): deliver each tenant's changes to its webhooks,\n                                 never to a private network address; private: those too, for\n                                 testing; off: keep the change feed, send nothing\n  SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:\n                                 rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,\n                                 every request per client, before any key lookup), key_read,\n                                 tenant_read (20/s:40), key_write, tenant_write (5/s:20),\n                                 global_read (500/s:1000), global_write (50/s:100), app_read\n                                 (20/s:40) and app_write (5/s:20) per tenant for the\n                                 application API, sign_in (20/m:20); counts for\n                                 tenant_series_writes and series_writes\n                                 (1: writes that may expand a recurring series at once),\n                                 maintenance_runs (1: application API maintenance runs at once),\n                                 subscriptions (256), tenant_subscriptions (16),\n                                 key_subscriptions (4, and fewer than tenant_subscriptions),\n                                 key_lookups (2), key_lookup_queue (256),\n                                 tenant_transactions (2: one tenant's database transactions at\n                                 once, of the pool's 10); what one tenant may store:\n                                 tenant_holds (10000), tenant_reservations, tenant_events and\n                                 tenant_coverage (100000), holder_holds (20) and\n                                 holder_held_hours (2160), which maintain keeps too\n  SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,\n                                 such as CF-Connecting-IP (default: the connection's address);\n                                 set it only when every request comes through that proxy\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_ASSISTANT_SECRET      Turns on the dashboard assistant and seals each organization's\n                                 model API key with it, 32+ random characters (dashboard; off\n                                 without it)\n  SLOTLOCK_ASSISTANT_PRIVATE_URLS off (default): refuse an assistant model URL whose host is, or\n                                 resolves to, a loopback, private, link-local, CGNAT, unique-local\n                                 or metadata address; on: allow them, for a self-hosted model\n                                 (Ollama, vLLM) on this machine or network\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant\n  SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
 /**
  * Run one `slotlock` command and resolve to its exit code: 0 success, 1 failure, 2 a usage or
  * configuration error (nothing was started). `serve` resolves once `io.signal` aborts and it has

package/self-host.js

@@ -8,7 +8,7 @@ import { createHash, timingSafeEqual } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import postgres from 'postgres';
 import { createSlotlockAgentServer, slotlockAgentOperationScope, } from './agent-server.js';
-import { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, } from './agent-store-backend.js';
+import { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, } from './agent-store-backend.js';
 import { SLOTLOCK_API_KEY_DEFAULT_SCOPES, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_SCOPES, createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, slotlockBearerCredential, } from './api-keys.js';
 import { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, } from './dashboard.js';
 import { SECRET_HINT, SlotlockConfigError, formatSlotlockRate, optional, readAvailability, readDashboardConfig, readDashboardOrganizations, readLimits, readSecret, readServerUrl, readTrustedProxyHeader, slotlockKeySubscriptions, } from './config.js';
@@ -43,6 +43,8 @@ export const SLOTLOCK_ENVIRONMENT_VARIABLES = Object.freeze([
     'SLOTLOCK_GITHUB_CLIENT_ID',
     'SLOTLOCK_GITHUB_CLIENT_SECRET',
     'SLOTLOCK_SESSION_SECRET',
+    'SLOTLOCK_ASSISTANT_SECRET',
+    'SLOTLOCK_ASSISTANT_PRIVATE_URLS',
     'SLOTLOCK_DASHBOARD_USERS',
     'SLOTLOCK_DASHBOARD_ORGS',
     'SLOTLOCK_DASHBOARD_NAME',
@@ -245,6 +247,7 @@ export function readSlotlockServeConfig(env) {
             confirmationSecret,
             env.SLOTLOCK_SESSION_SECRET?.trim(),
             env.SLOTLOCK_GITHUB_CLIENT_SECRET?.trim(),
+            env.SLOTLOCK_ASSISTANT_SECRET?.trim(),
         ];
         if (others.includes(metricsToken)) {
             throw new SlotlockConfigError('SLOTLOCK_METRICS_TOKEN must differ from every other secret');
@@ -308,6 +311,7 @@ function secretsIn(env) {
         'SLOTLOCK_CONFIRMATION_SECRET',
         'SLOTLOCK_GITHUB_CLIENT_SECRET',
         'SLOTLOCK_SESSION_SECRET',
+        'SLOTLOCK_ASSISTANT_SECRET',
         'SLOTLOCK_METRICS_TOKEN',
     ]) {
         const value = env[name]?.trim();
@@ -634,13 +638,14 @@ export async function startSlotlockServer(config, log) {
             onIgnoredClientField: (field) => log.warn('client_address_field_ignored', { field, setting: 'SLOTLOCK_TRUSTED_PROXY_HEADER' }),
         });
         let health;
+        const agentBackend = createSlotlockStoreAgentBackend(store, {
+            availabilityRules: async () => config.availability.map((rule) => ({ ...rule })),
+        });
         const agentServer = createSlotlockAgentServer({
             publicBaseUrl: config.publicUrl,
             // readPublicUrl admits plain HTTP only on a loopback host, which is all this permits anyway.
             allowInsecureLocalhost: publicUrl.protocol === 'http:',
-            backend: createSlotlockStoreAgentBackend(store, {
-                availabilityRules: async () => config.availability.map((rule) => ({ ...rule })),
-            }),
+            backend: agentBackend,
             authenticate: limits.authenticate,
             consumeRateLimit: limits.consumeRateLimit,
             // A write that may expand a recurring series also waits for one of a few slots, so one
@@ -652,6 +657,8 @@ export async function startSlotlockServer(config, log) {
                 return true;
             },
             subscriptions: {
+                // Live updates poll each tenant's change feed (one reader per tenant).
+                changes: createSlotlockStoreChangeSource(store, sql),
                 maxTotal: caps.subscriptions,
                 maxPerTenant: caps.tenant_subscriptions,
                 maxPerPrincipal: slotlockKeySubscriptions(caps),
@@ -718,6 +725,22 @@ export async function startSlotlockServer(config, log) {
                 resources: createSlotlockDashboardResources(store),
                 state: createSlotlockDashboardState(sql),
                 availability: config.availability,
+                ...(config.dashboard.assistantSecret !== undefined
+                    ? {
+                        // The assistant's reads and approved writes are agent calls: the same backend,
+                        // operations, rate limits and series-write slots as an API key's.
+                        assistant: {
+                            secret: config.dashboard.assistantSecret,
+                            ...(config.dashboard.assistantPrivateUrls ? { privateUrls: true } : {}),
+                            backend: agentBackend,
+                            consumeRateLimit: limits.consumeRateLimit,
+                            // Checks only: a proposal holds nothing. The series-write slot and the write
+                            // token are taken when an approved change runs (admit, consumeRateLimit).
+                            authorize: async ({ principal, operation }) => authorizeSlotlockServeOperation({ principal, operation }),
+                            admit: (args) => limits.admit(args),
+                        },
+                    }
+                    : {}),
                 clientAddress: (request) => limits.clientAddress(request),
                 onError: (error) => log.error('dashboard_error', describeError(error)),
             });
@@ -768,7 +791,9 @@ export async function startSlotlockServer(config, log) {
                     send,
                     feed: {
                         claimWebhookDeliveries: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.claimWebhookDeliveries(params)),
-                        settleWebhookDelivery: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.settleWebhookDelivery(params)),
+                        settleWebhookDelivery: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.settleWebhookDelivery(params), {
+                            origin: 'maintenance',
+                        }),
                     },
                 }),
                 // Counts only, never the tenant or a URL.
@@ -1099,6 +1124,9 @@ async function maintainTenant(config, caps) {
                 if (pass.capped && pass.extended + pass.pruned === 0 && !pass.rollPending)
                     break;
             }
+            // Every tenant's expired assistant conversations, a tenant only the dashboard serves
+            // included. Counted nowhere: the counts above are this tenant's.
+            await store.sweepAssistantConversations();
             return sum;
         });
         return total ?? null;
@@ -1249,6 +1277,13 @@ Environment:
                                  of a GitHub OAuth app with callback .../dashboard/callback
   SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)
   SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)
+  SLOTLOCK_ASSISTANT_SECRET      Turns on the dashboard assistant and seals each organization's
+                                 model API key with it, 32+ random characters (dashboard; off
+                                 without it)
+  SLOTLOCK_ASSISTANT_PRIVATE_URLS off (default): refuse an assistant model URL whose host is, or
+                                 resolves to, a loopback, private, link-local, CGNAT, unique-local
+                                 or metadata address; on: allow them, for a self-hosted model
+                                 (Ollama, vLLM) on this machine or network
   SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)
   SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant
   SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)
@@ -1520,7 +1555,7 @@ export async function runSlotlockCli(argv, io) {
             }
             case 'key rotate': {
                 const config = readSlotlockDatabaseConfig(io.env);
-                const rotated = await withApiKeys(config, (keys) => keys.rotate({ tenantRef: config.tenantRef, id: operands[1] }));
+                const rotated = await withApiKeys(config, (keys) => keys.rotate({ tenantRef: config.tenantRef, id: operands[1], actor: CLI_KEY_CREATOR }));
                 if (!rotated) {
                     io.stderr.write('slotlock: no active API key with that id in this tenant\n');
                     return 1;
@@ -1531,7 +1566,7 @@ export async function runSlotlockCli(argv, io) {
             }
             case 'key revoke': {
                 const config = readSlotlockDatabaseConfig(io.env);
-                const revoked = await withApiKeys(config, (keys) => keys.revoke({ tenantRef: config.tenantRef, id: operands[1] }));
+                const revoked = await withApiKeys(config, (keys) => keys.revoke({ tenantRef: config.tenantRef, id: operands[1], actor: CLI_KEY_CREATOR }));
                 if (!revoked) {
                     io.stderr.write('slotlock: no API key with that id in this tenant\n');
                     return 1;

package/slotlock.manifest.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0",
   "name": "Slotlock",
   "package": "slotlock",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "intervalSemantics": {
     "boundary": "[)",

package/store.d.ts

@@ -1,8 +1,8 @@
-import { type SlotlockEventFeed } from './event-feed.js';
+import { type SlotlockChangeOrigin, type SlotlockEventFeed } from './event-feed.js';
 import { type SlotlockBookingRules } from './booking-rules.js';
 import type { Sql, TransactionSql } from 'postgres';
 import { SLOTLOCK_CALENDAR_HORIZON_DAYS } from './rules.js';
-import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockAgendaEntry, SlotlockHold, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
+import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, SlotlockBookingRuleDefaults, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockAgendaEntry, SlotlockHold, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
 export { SLOTLOCK_CALENDAR_HORIZON_DAYS };
 /**
  * Longest one-off event the store accepts (ten years and some leap days): long enough for any lease
@@ -90,6 +90,8 @@ export declare function legacyPutCommandHash(params: Parameters<typeof putComman
 }): string;
 /** Members a pool booking or search considers at most, in id order. */
 export declare const SLOTLOCK_MAX_POOL_MEMBERS = 100;
+/** The most pools of one tenant that may have default booking rules (`setBookingRuleDefaults`). */
+export declare const SLOTLOCK_MAX_POOL_RULE_DEFAULTS = 1000;
 export declare function isPoolName(value: unknown): value is string;
 export interface SlotlockStore extends SlotlockEventFeed {
     /**
@@ -148,6 +150,13 @@ export interface SlotlockStore extends SlotlockEventFeed {
          * without control characters: the history (listHistory) records it with each change.
          */
         actor?: string;
+        /**
+         * Where the changes come from (SLOTLOCK_CHANGE_ORIGINS: `mcp`, `rest`, `dashboard`, ...),
+         * recorded with each beside the actor. Unset, the enclosing withTenant's, else `library`.
+         */
+        origin?: SlotlockChangeOrigin;
+        /** The id (a UUID) of the API key making these changes, recorded with each. */
+        keyId?: string;
     }): Promise<T>;
     /**
      * INVARIANT (erasure completeness): a tenant integration must use a stable, erasable business
@@ -228,6 +237,24 @@ export interface SlotlockStore extends SlotlockEventFeed {
         id: string;
         rules: SlotlockBookingRules | null;
     }): Promise<SlotlockResource | null>;
+    /**
+     * Set (or clear, with `null`) the tenant's default booking rules, or one pool's (`pool`): a
+     * resource's rules as they apply (`effectiveBookingRules`) are the tenant's, overlaid by its
+     * pool's, overlaid by its own, a field set at a narrower level winning. They apply to bookings made
+     * from then on. `checkInMinutes` is only a resource's own (`invalid_booking_rules`, as for rules
+     * outside their bounds); `pool` is a pool name (`invalid_pool`). At most
+     * SLOTLOCK_MAX_POOL_RULE_DEFAULTS pools a tenant have them (`pool_rules_limit_reached` for one
+     * more). Returns the rules stored.
+     */
+    setBookingRuleDefaults(params: {
+        tenantRef: string;
+        pool: string | null;
+        rules: SlotlockBookingRules | null;
+    }): Promise<SlotlockBookingRules | null>;
+    /** The tenant's default booking rules, and each pool's that has them, by pool name. */
+    getBookingRuleDefaults(params: {
+        tenantRef: string;
+    }): Promise<SlotlockBookingRuleDefaults>;
     /**
      * Put one resource in a pool, or take it out (`null`): `pool` is 1-100 characters of a-z, 0-9,
      * `.`, `_` and `-`, starting with a letter or digit (`invalid_pool` otherwise). A resource is in
@@ -635,6 +662,83 @@ export interface SlotlockStore extends SlotlockEventFeed {
         id: string;
         holderRef?: string;
     }): Promise<boolean>;
+    /** The tenant's dashboard assistant settings, or null when it has none. */
+    getAssistantSettings(params: {
+        tenantRef: string;
+    }): Promise<SlotlockAssistantSettingsRecord | null>;
+    /**
+     * Set the tenant's assistant settings. `key` is the sealed key and its hint, null for none, or
+     * `'keep'` to keep the one stored (none, for a tenant without settings). A stored key is kept only
+     * for the provider and base URL it was entered for: `'keep'` with another provider or URL changes
+     * nothing and answers `{ saved: false }`, decided in the one statement that writes, so racing
+     * saves cannot carry the key elsewhere.
+     */
+    putAssistantSettings(params: {
+        tenantRef: string;
+        provider: 'anthropic' | 'openai';
+        baseUrl: string;
+        model: string;
+        key: {
+            sealed: string;
+            hint: string;
+        } | null | 'keep';
+        updatedBy?: string;
+    }): Promise<{
+        saved: boolean;
+    }>;
+    /** Remove the tenant's assistant settings, its key with them. False when it had none. */
+    deleteAssistantSettings(params: {
+        tenantRef: string;
+    }): Promise<boolean>;
+    /** A member's live assistant conversation, or null when none is (or it expired). */
+    getAssistantConversation(params: {
+        tenantRef: string;
+        memberRef: string;
+    }): Promise<SlotlockAssistantConversationRecord | null>;
+    /**
+     * Store a member's conversation for `ttlMs` (1 second to a day) from now, replacing its messages.
+     * Its actions become those stored already that `keep` names, in their stored state
+     * (settleAssistantAction changes it), and the `added` ones not stored already: an action is never
+     * put back into a conversation that no longer has it. The tenant's expired conversations are
+     * deleted with it, and the tenant is listed for sweepAssistantConversations.
+     */
+    putAssistantConversation(params: {
+        tenantRef: string;
+        memberRef: string;
+        messages: unknown[];
+        added: Record<string, Record<string, unknown>>;
+        keep: readonly string[];
+        ttlMs: number;
+    }): Promise<void>;
+    /**
+     * Change one proposed action, only while its `status` is `from`: its fields are merged with
+     * `patch`. The action as changed, or null when it is not in that state (or not there): of two
+     * racing approvals, one wins.
+     */
+    settleAssistantAction(params: {
+        tenantRef: string;
+        memberRef: string;
+        actionId: string;
+        from: string;
+        patch: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | null>;
+    /** Forget a member's conversation. False when there was none. */
+    deleteAssistantConversation(params: {
+        tenantRef: string;
+        memberRef: string;
+    }): Promise<boolean>;
+    /** Delete up to `limit` (default 1,000) of the tenant's expired assistant conversations: how many. */
+    pruneAssistantConversations(params: {
+        tenantRef: string;
+        limit?: number;
+    }): Promise<number>;
+    /**
+     * Delete up to `limit` (1-100,000, default 10,000) expired assistant conversations of every
+     * tenant (slotlock.sweep_assistant_conversations): how many, and nothing else.
+     */
+    sweepAssistantConversations(params?: {
+        limit?: number;
+    }): Promise<number>;
     /**
      * Offer freed time to the waitlist, in the order entries joined: each waiting entry whose window
      * is free (on its resource, or on the first free member of its pool) gets a hold for its holder
@@ -735,6 +839,29 @@ export interface SlotlockStore extends SlotlockEventFeed {
         coverageMaxAgeMs?: number;
     }): Promise<Interval | null>;
 }
+/**
+ * The model a tenant's dashboard assistant uses (dashboard Settings, Assistant). The API key is held
+ * only sealed (assistant.ts sealSlotlockAssistantKey), never in the clear.
+ */
+export interface SlotlockAssistantSettingsRecord {
+    provider: 'anthropic' | 'openai';
+    baseUrl: string;
+    model: string;
+    /** The API key, sealed with the deployment's assistant secret; null when it has none. */
+    sealedKey: string | null;
+    /** The key's last four characters, to show; null when it has none. */
+    keyHint: string | null;
+    updatedBy: string | null;
+    updatedAt: Date;
+}
+/** One member's live conversation with the dashboard assistant, as assistant.ts keeps it. */
+export interface SlotlockAssistantConversationRecord {
+    messages: unknown[];
+    /** The writes it proposed, by id. */
+    actions: Record<string, Record<string, unknown>>;
+    updatedAt: Date;
+    expiresAt: Date;
+}
 /** One entry of a tenant's waitlist (joinWaitlist). */
 export interface SlotlockWaitlistEntry {
     id: string;
@@ -770,6 +897,8 @@ export type CheckInReservationResult = {
 /** One source's coverage of a resource, with its health (listCoverage). */
 export interface SlotlockCoverageHealth {
     source: string;
+    /** How the change feed names the source (slotlockCoverageSourceId), never the source itself. */
+    sourceId: string;
     start: Date;
     end: Date;
     revision: number;
@@ -874,4 +1003,4 @@ export declare function createSlotlockStore(sql: StoreSql, options?: SlotlockSto
  * Every store method that writes for a tenant: what a suspended tenant's withTenant store refuses.
  * Maintenance (rolling series, pruning, purging) and erasure are not among them.
  */
-export declare const SLOTLOCK_TENANT_WRITE_METHODS: readonly ["createResource", "archiveResource", "restoreResource", "deleteResource", "setResourceAvailability", "setResourceBookingRules", "setResourcePool", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage", "createWebhookEndpoint", "deleteWebhookEndpoint", "enableWebhookEndpoint", "recordCoverageFailure", "deleteCoverage", "checkInReservation", "joinWaitlist", "leaveWaitlist"];
+export declare const SLOTLOCK_TENANT_WRITE_METHODS: readonly ["createResource", "archiveResource", "restoreResource", "deleteResource", "setResourceAvailability", "setResourceBookingRules", "setBookingRuleDefaults", "setResourcePool", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage", "createWebhookEndpoint", "deleteWebhookEndpoint", "enableWebhookEndpoint", "recordCoverageFailure", "deleteCoverage", "checkInReservation", "joinWaitlist", "leaveWaitlist", "putAssistantSettings", "deleteAssistantSettings", "putAssistantConversation", "settleAssistantAction", "deleteAssistantConversation"];