slotlock 0.5.1 → 0.5.2

package/ddl.d.ts

@@ -41,21 +41,21 @@ export declare const SLOTLOCK_SCHEMA_TABLES: readonly ["schema_version"];
 /** The SECURITY DEFINER function through which a server reads the version it is serving. */
 export declare const SLOTLOCK_SCHEMA_FUNCTIONS: readonly ["slotlock.installed_schema_version()"];
 /** The table of suspended tenants: they may read, and write nothing (store.ts withTenant). */
-export declare const SLOTLOCK_TENANT_ADMIN_TABLES: readonly ["tenant_suspensions", "webhook_tenants", "rate_buckets"];
+export declare const SLOTLOCK_TENANT_ADMIN_TABLES: readonly ["tenant_suspensions", "webhook_tenants", "rate_buckets", "assistant_tenants"];
 /**
  * The SECURITY DEFINER functions through which a server checks a tenant's suspension and erases a
  * tenant, by signature.
  */
-export declare const SLOTLOCK_TENANT_ADMIN_FUNCTIONS: readonly ["slotlock.tenant_suspended(text)", "slotlock.erase_tenant(text)", "slotlock.register_webhook_tenant(text)", "slotlock.webhook_tenants(text)", "slotlock.unregister_webhook_tenant(text)", "slotlock.take_rate_token(text, double precision, double precision)"];
+export declare const SLOTLOCK_TENANT_ADMIN_FUNCTIONS: readonly ["slotlock.tenant_suspended(text)", "slotlock.erase_tenant(text)", "slotlock.register_webhook_tenant(text)", "slotlock.webhook_tenants(text)", "slotlock.unregister_webhook_tenant(text)", "slotlock.take_rate_token(text, double precision, double precision)", "slotlock.register_assistant_tenant(text, timestamptz)", "slotlock.sweep_assistant_conversations(integer)"];
 /**
  * Functions only the deployment role runs: suspending and lifting a suspension. No other role is
  * granted them, so a serving role cannot lift a suspension.
  */
 export declare const SLOTLOCK_OPERATOR_FUNCTIONS: readonly ["slotlock.suspend_tenant(text, text)", "slotlock.unsuspend_tenant(text)"];
 /** Every SECURITY DEFINER function the serving role may execute, by signature. */
-export declare const SLOTLOCK_DEFINER_FUNCTIONS: readonly ("slotlock.authenticate_api_key(bytea)" | "slotlock.create_api_key(text, text, text, bytea, text[], timestamptz, text)" | "slotlock.dashboard_session_ended(bytea, timestamptz)" | "slotlock.erase_api_keys(text)" | "slotlock.erase_tenant(text)" | "slotlock.installed_schema_version()" | "slotlock.list_api_keys(text)" | "slotlock.register_webhook_tenant(text)" | "slotlock.revoke_api_key(text, uuid)" | "slotlock.rotate_api_key(text, uuid, text, bytea)" | "slotlock.take_rate_token(text, double precision, double precision)" | "slotlock.tenant_suspended(text)" | "slotlock.unregister_webhook_tenant(text)" | "slotlock.use_dashboard_token(text, bytea, timestamptz, bytea)" | "slotlock.webhook_tenants(text)")[];
+export declare const SLOTLOCK_DEFINER_FUNCTIONS: readonly ("slotlock.authenticate_api_key(bytea)" | "slotlock.create_api_key(text, text, text, bytea, text[], timestamptz, text)" | "slotlock.dashboard_session_ended(bytea, timestamptz)" | "slotlock.erase_api_keys(text)" | "slotlock.erase_tenant(text)" | "slotlock.installed_schema_version()" | "slotlock.list_api_keys(text)" | "slotlock.register_assistant_tenant(text, timestamptz)" | "slotlock.register_webhook_tenant(text)" | "slotlock.revoke_api_key(text, uuid)" | "slotlock.rotate_api_key(text, uuid, text, bytea)" | "slotlock.sweep_assistant_conversations(integer)" | "slotlock.take_rate_token(text, double precision, double precision)" | "slotlock.tenant_suspended(text)" | "slotlock.unregister_webhook_tenant(text)" | "slotlock.use_dashboard_token(text, bytea, timestamptz, bytea)" | "slotlock.webhook_tenants(text)")[];
 /** Tables no role but their owner reads or writes, reached only through SLOTLOCK_DEFINER_FUNCTIONS. */
-export declare const SLOTLOCK_DEFINER_TABLES: readonly ("api_key_retired_digests" | "api_keys" | "dashboard_tokens" | "rate_buckets" | "schema_version" | "tenant_suspensions" | "webhook_tenants")[];
+export declare const SLOTLOCK_DEFINER_TABLES: readonly ("api_key_retired_digests" | "api_keys" | "assistant_tenants" | "dashboard_tokens" | "rate_buckets" | "schema_version" | "tenant_suspensions" | "webhook_tenants")[];
 /**
  * The advisory lock every server transaction for a tenant holds shared (store.ts withTenant), and
  * suspension and erasure take exclusively, keyed by this text's hashtextextended(…, 0).
@@ -76,7 +76,7 @@ export declare const SLOTLOCK_TENANT_CONTEXT_SETTING = "slotlock.tenant_ref";
  * `slotlock.rls_policy_contracts` and `slotlock.deployment_lifted_row_security` are
  * deployment-only and deliberately absent.
  */
-export declare const SLOTLOCK_TENANT_TABLES: readonly ["resources", "reservations", "reservation_tombstones", "reservation_conflict_archive", "calendar_events", "calendar_event_attendees", "calendar_event_reminders", "calendar_event_exceptions", "calendar_event_occurrences", "calendar_event_tombstones", "calendar_event_commands", "calendar_coverage", "hold_commands", "outbox", "outbox_pruned", "webhook_endpoints", "waitlist_entries"];
+export declare const SLOTLOCK_TENANT_TABLES: readonly ["resources", "reservations", "reservation_tombstones", "reservation_conflict_archive", "calendar_events", "calendar_event_attendees", "calendar_event_reminders", "calendar_event_exceptions", "calendar_event_occurrences", "calendar_event_tombstones", "calendar_event_commands", "calendar_coverage", "hold_commands", "outbox", "outbox_pruned", "webhook_endpoints", "waitlist_entries", "assistant_settings", "assistant_conversations"];
 /**
  * Build the grants for the application role: USAGE on the `slotlock` schema, DML on the store's
  * tables and EXECUTE on the API key and dashboard functions. Nothing else: no ownership, DDL,

package/ddl.js

@@ -239,6 +239,7 @@ export const SLOTLOCK_TENANT_ADMIN_TABLES = Object.freeze([
     'tenant_suspensions',
     'webhook_tenants',
     'rate_buckets',
+    'assistant_tenants',
 ]);
 /**
  * The SECURITY DEFINER functions through which a server checks a tenant's suspension and erases a
@@ -251,6 +252,8 @@ export const SLOTLOCK_TENANT_ADMIN_FUNCTIONS = Object.freeze([
     'slotlock.webhook_tenants(text)',
     'slotlock.unregister_webhook_tenant(text)',
     'slotlock.take_rate_token(text, double precision, double precision)',
+    'slotlock.register_assistant_tenant(text, timestamptz)',
+    'slotlock.sweep_assistant_conversations(integer)',
 ]);
 /**
  * Functions only the deployment role runs: suspending and lifting a suspension. No other role is
@@ -872,6 +875,14 @@ BEGIN
   DELETE FROM slotlock.waitlist_entries WHERE tenant_ref = requested_tenant_ref;
   GET DIAGNOSTICS erased_rows = ROW_COUNT;
   RETURN NEXT;
+  erased_table := 'assistant_conversations';
+  DELETE FROM slotlock.assistant_conversations WHERE tenant_ref = requested_tenant_ref;
+  GET DIAGNOSTICS erased_rows = ROW_COUNT;
+  RETURN NEXT;
+  erased_table := 'assistant_settings';
+  DELETE FROM slotlock.assistant_settings WHERE tenant_ref = requested_tenant_ref;
+  GET DIAGNOSTICS erased_rows = ROW_COUNT;
+  RETURN NEXT;
   erased_table := 'resources';
   DELETE FROM slotlock.resources WHERE tenant_ref = requested_tenant_ref;
   GET DIAGNOSTICS erased_rows = ROW_COUNT;
@@ -889,6 +900,10 @@ BEGIN
   DELETE FROM slotlock.webhook_endpoints WHERE tenant_ref = requested_tenant_ref;
   GET DIAGNOSTICS erased_rows = ROW_COUNT;
   RETURN NEXT;
+  erased_table := 'assistant_tenants';
+  DELETE FROM slotlock.assistant_tenants WHERE tenant_ref = requested_tenant_ref;
+  GET DIAGNOSTICS erased_rows = ROW_COUNT;
+  RETURN NEXT;
   erased_table := 'webhook_tenants';
   DELETE FROM slotlock.webhook_tenants WHERE tenant_ref = requested_tenant_ref;
   GET DIAGNOSTICS erased_rows = ROW_COUNT;
@@ -1015,6 +1030,106 @@ BEGIN
 END
 $slotlock_take_rate_token$;
 REVOKE ALL ON FUNCTION ${SLOTLOCK_TENANT_ADMIN_FUNCTIONS[5]} FROM PUBLIC;
+
+-- The tenants with a dashboard assistant conversation, and when the first of them expires. Forced
+-- row-level security hides every other tenant's conversations, from the owner too, so this list
+-- (names and a time only) is how maintenance finds the tenants whose conversations have expired,
+-- whichever server stored them: one only the dashboard (or its Worker) ever used included. No role
+-- but its owner reads it.
+CREATE TABLE IF NOT EXISTS slotlock.assistant_tenants (
+  tenant_ref text PRIMARY KEY,
+  next_expiry timestamptz NOT NULL,
+  CONSTRAINT slotlock_assistant_tenants_tenant_ref_valid
+    CHECK (octet_length(tenant_ref) BETWEEN 1 AND 500)
+);
+CREATE INDEX IF NOT EXISTS slotlock_assistant_tenants_expiry_idx
+  ON slotlock.assistant_tenants (next_expiry);
+ALTER TABLE slotlock.assistant_tenants ENABLE ROW LEVEL SECURITY;
+REVOKE ALL ON slotlock.assistant_tenants FROM PUBLIC;
+
+-- Record that the tenant has a conversation expiring at expires (the earliest is kept).
+CREATE OR REPLACE FUNCTION slotlock.register_assistant_tenant(requested_tenant_ref text, expires timestamptz)
+RETURNS void
+LANGUAGE plpgsql
+VOLATILE
+SECURITY DEFINER
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $slotlock_register_assistant_tenant$
+BEGIN
+  IF requested_tenant_ref IS NULL OR octet_length(requested_tenant_ref) NOT BETWEEN 1 AND 500
+     OR expires IS NULL THEN
+    RAISE EXCEPTION 'Slotlock assistant tenant arguments are invalid' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  INSERT INTO slotlock.assistant_tenants AS kept (tenant_ref, next_expiry)
+  VALUES (requested_tenant_ref, expires)
+  ON CONFLICT (tenant_ref) DO UPDATE SET next_expiry = LEAST(kept.next_expiry, EXCLUDED.next_expiry);
+END
+$slotlock_register_assistant_tenant$;
+REVOKE ALL ON FUNCTION ${SLOTLOCK_TENANT_ADMIN_FUNCTIONS[6]} FROM PUBLIC;
+
+-- Delete expired assistant conversations across every tenant: up to max_rows of them, from the
+-- tenants whose earliest expiry has passed, longest overdue first, each under its own tenant
+-- context (forced row-level security binds the owner too), putting the caller's settings back
+-- after. A tenant left with none leaves the list; one with more is listed at its next expiry.
+-- Only a count comes back.
+CREATE OR REPLACE FUNCTION slotlock.sweep_assistant_conversations(max_rows integer)
+RETURNS bigint
+LANGUAGE plpgsql
+VOLATILE
+SECURITY DEFINER
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $slotlock_sweep_assistant_conversations$
+DECLARE
+  setting text;
+  previous jsonb := '{}'::jsonb;
+  due record;
+  deleted bigint := 0;
+  step bigint;
+  upcoming timestamptz;
+BEGIN
+  IF max_rows IS NULL OR max_rows NOT BETWEEN 1 AND 100000 THEN
+    RAISE EXCEPTION 'Slotlock assistant sweep size must be 1-100,000' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  FOR setting IN
+    SELECT DISTINCT contract.tenant_context_setting FROM slotlock.rls_policy_contracts contract
+  LOOP
+    previous := previous || jsonb_build_object(setting, current_setting(setting, true));
+  END LOOP;
+  FOR due IN
+    SELECT listed.tenant_ref FROM slotlock.assistant_tenants listed
+     WHERE listed.next_expiry <= now()
+     ORDER BY listed.next_expiry
+     LIMIT 1000
+       FOR UPDATE SKIP LOCKED
+  LOOP
+    EXIT WHEN deleted >= max_rows;
+    FOR setting IN SELECT jsonb_object_keys(previous) LOOP
+      PERFORM set_config(setting, due.tenant_ref, true);
+    END LOOP;
+    DELETE FROM slotlock.assistant_conversations gone
+     WHERE gone.tenant_ref = due.tenant_ref
+       AND gone.member_ref IN (
+         SELECT expired.member_ref FROM slotlock.assistant_conversations expired
+          WHERE expired.tenant_ref = due.tenant_ref AND expired.expires_at <= now()
+          LIMIT max_rows - deleted)
+       AND gone.expires_at <= now();
+    GET DIAGNOSTICS step = ROW_COUNT;
+    deleted := deleted + step;
+    SELECT min(live.expires_at) INTO upcoming FROM slotlock.assistant_conversations live
+     WHERE live.tenant_ref = due.tenant_ref;
+    IF upcoming IS NULL THEN
+      DELETE FROM slotlock.assistant_tenants WHERE tenant_ref = due.tenant_ref;
+    ELSE
+      UPDATE slotlock.assistant_tenants SET next_expiry = upcoming WHERE tenant_ref = due.tenant_ref;
+    END IF;
+  END LOOP;
+  FOR setting IN SELECT jsonb_object_keys(previous) LOOP
+    PERFORM set_config(setting, coalesce(previous ->> setting, ''), true);
+  END LOOP;
+  RETURN deleted;
+END
+$slotlock_sweep_assistant_conversations$;
+REVOKE ALL ON FUNCTION ${SLOTLOCK_TENANT_ADMIN_FUNCTIONS[7]} FROM PUBLIC;
 `;
 // A constraint an upgrade added NOT VALID (no table scan under its ACCESS EXCLUSIVE lock) is checked
 // here. applySchema runs this in a transaction of its own once the DDL has committed: inside the
@@ -1206,6 +1321,54 @@ CREATE INDEX IF NOT EXISTS slotlock_waitlist_entries_queue_idx
 CREATE INDEX IF NOT EXISTS slotlock_waitlist_entries_tenant_idx
   ON slotlock.waitlist_entries (tenant_ref, starts_at);
 
+-- The model a tenant's dashboard assistant uses (dashboard.ts, assistant.ts), one row a tenant.
+-- The API key is stored only sealed (AES-256-GCM under the deployment's SLOTLOCK_ASSISTANT_SECRET,
+-- bound to the tenant), with its last four characters to show.
+CREATE TABLE IF NOT EXISTS slotlock.assistant_settings (
+  tenant_ref text PRIMARY KEY,
+  provider text NOT NULL,
+  base_url text NOT NULL,
+  model text NOT NULL,
+  sealed_key text,
+  key_hint text,
+  updated_by text,
+  updated_at timestamptz NOT NULL DEFAULT statement_timestamp(),
+  CONSTRAINT slotlock_assistant_settings_tenant_ref_valid CHECK (octet_length(tenant_ref) BETWEEN 1 AND 500),
+  CONSTRAINT slotlock_assistant_settings_provider_valid CHECK (provider IN ('anthropic', 'openai')),
+  CONSTRAINT slotlock_assistant_settings_base_url_valid CHECK (octet_length(base_url) BETWEEN 1 AND 2048),
+  CONSTRAINT slotlock_assistant_settings_model_valid CHECK (octet_length(model) BETWEEN 1 AND 200),
+  CONSTRAINT slotlock_assistant_settings_key_valid CHECK (
+    (sealed_key IS NULL) = (key_hint IS NULL)
+    AND (sealed_key IS NULL OR octet_length(sealed_key) BETWEEN 1 AND 8192)
+    AND (key_hint IS NULL OR char_length(key_hint) BETWEEN 1 AND 4)
+  ),
+  CONSTRAINT slotlock_assistant_settings_updated_by_valid
+    CHECK (updated_by IS NULL OR octet_length(updated_by) BETWEEN 1 AND 200)
+);
+
+-- One member's short-lived conversation with the dashboard assistant, and the writes it proposed
+-- (actions, by id, each pending until the member approves or dismisses it).
+CREATE TABLE IF NOT EXISTS slotlock.assistant_conversations (
+  tenant_ref text NOT NULL,
+  member_ref text NOT NULL,
+  messages jsonb NOT NULL DEFAULT '[]'::jsonb,
+  actions jsonb NOT NULL DEFAULT '{}'::jsonb,
+  updated_at timestamptz NOT NULL DEFAULT statement_timestamp(),
+  expires_at timestamptz NOT NULL,
+  CONSTRAINT slotlock_assistant_conversations_pkey PRIMARY KEY (tenant_ref, member_ref),
+  CONSTRAINT slotlock_assistant_conversations_identity_valid CHECK (
+    octet_length(tenant_ref) BETWEEN 1 AND 500 AND octet_length(member_ref) BETWEEN 1 AND 500
+  ),
+  CONSTRAINT slotlock_assistant_conversations_messages_valid CHECK (
+    jsonb_typeof(messages) = 'array' AND octet_length(messages::text) <= 262144
+  ),
+  CONSTRAINT slotlock_assistant_conversations_actions_valid CHECK (
+    jsonb_typeof(actions) = 'object' AND octet_length(actions::text) <= 131072
+  )
+);
+CREATE INDEX IF NOT EXISTS slotlock_assistant_conversations_expiry_idx
+  ON slotlock.assistant_conversations (tenant_ref, expires_at);
+
 -- The tenant a reservation row belongs to: its own, or (a hold) its resource's.
 CREATE OR REPLACE FUNCTION slotlock.outbox_reservation_change()
 RETURNS trigger
@@ -2633,6 +2796,8 @@ export const SLOTLOCK_TENANT_TABLES = Object.freeze([
     'outbox_pruned',
     'webhook_endpoints',
     'waitlist_entries',
+    'assistant_settings',
+    'assistant_conversations',
 ]);
 const POSTGRES_SETTING_NAME = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/;
 const POSTGRES_ROLE_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
@@ -2702,6 +2867,10 @@ ALTER TABLE slotlock.webhook_endpoints ENABLE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.webhook_endpoints FORCE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.waitlist_entries ENABLE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.waitlist_entries FORCE ROW LEVEL SECURITY;
+ALTER TABLE slotlock.assistant_settings ENABLE ROW LEVEL SECURITY;
+ALTER TABLE slotlock.assistant_settings FORCE ROW LEVEL SECURITY;
+ALTER TABLE slotlock.assistant_conversations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE slotlock.assistant_conversations FORCE ROW LEVEL SECURITY;
 
 -- One database must have one tenant-context contract. Re-applying with an adapter-specific
 -- setting deliberately rebinds the stable policies instead of silently keeping a prior setting.
@@ -2730,7 +2899,9 @@ BEGIN
          'outbox',
          'outbox_pruned',
          'webhook_endpoints',
-         'waitlist_entries'
+         'waitlist_entries',
+         'assistant_settings',
+         'assistant_conversations'
        )
   LOOP
     EXECUTE format(
@@ -2941,6 +3112,26 @@ BEGIN
       USING (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''))
       WITH CHECK (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''));
   END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_policies
+     WHERE schemaname = 'slotlock' AND tablename = 'assistant_settings'
+       AND policyname = 'tenant_isolation_v1'
+  ) THEN
+    CREATE POLICY tenant_isolation_v1 ON slotlock.assistant_settings
+      USING (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''))
+      WITH CHECK (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''));
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_policies
+     WHERE schemaname = 'slotlock' AND tablename = 'assistant_conversations'
+       AND policyname = 'tenant_isolation_v1'
+  ) THEN
+    CREATE POLICY tenant_isolation_v1 ON slotlock.assistant_conversations
+      USING (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''))
+      WITH CHECK (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''));
+  END IF;
 END
 $slotlock_rls$;
 
@@ -2978,6 +3169,10 @@ COMMENT ON POLICY tenant_isolation_v1 ON slotlock.webhook_endpoints
   IS 'slotlock:tenant-context:${tenantContextSetting}';
 COMMENT ON POLICY tenant_isolation_v1 ON slotlock.waitlist_entries
   IS 'slotlock:tenant-context:${tenantContextSetting}';
+COMMENT ON POLICY tenant_isolation_v1 ON slotlock.assistant_settings
+  IS 'slotlock:tenant-context:${tenantContextSetting}';
+COMMENT ON POLICY tenant_isolation_v1 ON slotlock.assistant_conversations
+  IS 'slotlock:tenant-context:${tenantContextSetting}';
 
 INSERT INTO slotlock.rls_policy_contracts (
   table_name, tenant_context_setting, policy_fingerprint, installed_at
@@ -3017,7 +3212,9 @@ WHERE schemaname = 'slotlock'
     'outbox',
     'outbox_pruned',
     'webhook_endpoints',
-    'waitlist_entries'
+    'waitlist_entries',
+    'assistant_settings',
+    'assistant_conversations'
   )
   AND policyname = 'tenant_isolation_v1'
 ON CONFLICT (table_name) DO UPDATE

package/index.d.ts

@@ -2,7 +2,7 @@
 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 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';
@@ -23,7 +23,9 @@ 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 { 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, SlotlockApiKeyIdentity, SlotlockApiKeyScope, SlotlockApiKeyStore, } from './api-keys.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
 export type { ICalendarWorkerPool, ICalendarWorkerPoolOptions } from './ical-worker.js';

package/index.js

@@ -6,7 +6,7 @@
 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 { 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';
@@ -19,6 +19,7 @@ export { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlock
 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

@@ -63,6 +63,9 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
         }
     }
     options.signal?.throwIfAborted();
+    // Conversations last 2 hours after their last message (dashboard.ts): an expired one is
+    // unreadable already, and deleted here.
+    pruned += await store.withTenant(tenantRef, (tenant) => tenant.pruneAssistantConversations({ tenantRef }));
     const zones = await store.withTenant(tenantRef, (tenant) => tenant.followZoneRules({ tenantRef, move: options.followZoneRules === true }));
     const staleSources = await store.withTenant(tenantRef, (tenant) => tenant.reportStaleCoverage({ tenantRef }));
     // No-shows first: the time they free is offered to the waitlist in the same pass.
@@ -97,6 +100,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 +213,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotlock",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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

@@ -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
@@ -718,6 +723,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)),
             });
@@ -1099,6 +1120,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 +1273,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)

package/slotlock.manifest.json

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