slotlock 0.5.1 → 0.5.3

package/dashboard.d.ts

@@ -1,8 +1,11 @@
 import type { SlotlockApiKeyStore } from './api-keys.js';
+import { type SlotlockAgentCalendarBackend, type SlotlockAgentOperation, type SlotlockAgentOperationDispatchOptions, type SlotlockAgentPrincipal } from './agent-server.js';
+import { type SlotlockAssistantStore } from './assistant.js';
+import { type SlotlockRate } from './config.js';
 import { type SlotlockBookingRules } from './booking-rules.js';
 import { type CreateWebhookEndpointResult, type SlotlockChange, type SlotlockWebhookEndpoint } from './event-feed.js';
 import type { SlotlockSql, SlotlockStore, SlotlockWaitlistEntry } from './store.js';
-import type { Interval, SlotlockAgendaEntry, SlotlockResource, WeeklyAvailabilityRule } from './types.js';
+import type { Interval, SlotlockAgendaEntry, SlotlockResource, SlotlockBookingRuleDefaults, WeeklyAvailabilityRule } from './types.js';
 /** Resources one dashboard tenant may hold. */
 export declare const SLOTLOCK_DASHBOARD_MAX_RESOURCES = 100;
 /**
@@ -34,6 +37,8 @@ export interface SlotlockDashboardResources {
      * null when it is not the tenant's. Invalid rules throw with `code: 'invalid_booking_rules'`.
      */
     setRules?(tenantRef: string, id: string, rules: SlotlockBookingRules | null, actor?: string): Promise<SlotlockResource | null>;
+    /** The tenant's default booking rules and its pools', which a resource's own rules overlay. */
+    ruleDefaults?(tenantRef: string): Promise<SlotlockBookingRuleDefaults>;
     /** Put one of the tenant's resources in a pool, or none: as setRules; `code: 'invalid_pool'`. */
     setPool?(tenantRef: string, id: string, pool: string | null, actor?: string): Promise<SlotlockResource | null>;
     /** The tenant's waitlist, oldest first, and leaving it (false when the entry is not the tenant's). */
@@ -41,6 +46,8 @@ export interface SlotlockDashboardResources {
         list(tenantRef: string, limit: number): Promise<SlotlockWaitlistEntry[]>;
         leave(tenantRef: string, id: string, actor?: string): Promise<boolean>;
     };
+    /** The tenant's assistant settings and its members' conversations (assistant.ts). */
+    assistant?: SlotlockAssistantStore;
     /** The tenant's webhook endpoints, as the event feed keeps them. */
     webhooks?: {
         list(tenantRef: string): Promise<SlotlockWebhookEndpoint[]>;
@@ -74,6 +81,60 @@ export interface SlotlockDashboardState {
      */
     sessionEnded(sid: string, expiresAt: number): Promise<boolean>;
 }
+/**
+ * The chat assistant (assistant.ts): each tenant's admins connect a model of their own in Settings,
+ * and every member may chat with it. Its reads and approved writes run through the agent operation
+ * boundary with `backend`, as the principal `dashboard-assistant:<GitHub login>` of the member's
+ * tenant, with `authorize` and `consumeRateLimit` as an agent's are. Needs the resources adapter's
+ * `assistant` too.
+ */
+export interface SlotlockDashboardAssistantOptions {
+    /** Seals each tenant's API key (SLOTLOCK_ASSISTANT_SECRET): 32+ random characters. */
+    secret: string;
+    backend: SlotlockAgentCalendarBackend;
+    /**
+     * As the agent server's: false refuses an operation. Every offered operation by default. It also
+     * checks a write the model proposes, so it must hold nothing: limits that hold a slot go in
+     * `admit`.
+     */
+    authorize?: SlotlockAgentOperationDispatchOptions['authorize'];
+    /**
+     * Taken when a read runs and when an approved write runs, never for a proposal: the agent
+     * request limits' `admit` (serve's series-write slots), which may hold a slot until the request
+     * is answered, or throw a SlotlockAgentOperationError to refuse.
+     */
+    admit?: (args: {
+        principal: SlotlockAgentPrincipal;
+        operation: SlotlockAgentOperation;
+        input: Record<string, unknown>;
+    }) => Promise<void>;
+    /** As the agent server's; charged for each read and each approved write, never for a proposal. */
+    consumeRateLimit?: SlotlockAgentOperationDispatchOptions['consumeRateLimit'];
+    /**
+     * Allow a model at a local or private network address (SLOTLOCK_ASSISTANT_PRIVATE_URLS): a
+     * base URL whose host is, or resolves to, a loopback, private, link-local, shared, unique-local
+     * or metadata address. Off by default: such URLs are refused when saved and at each call.
+     */
+    privateUrls?: boolean;
+    /**
+     * Reaches the model providers. By default Node.js's http client, which checks every address a
+     * host resolves to as the connection is made (createSlotlockGuardedFetch), so a name rebound to
+     * a private address is refused too. A replacement must make that check itself, or reach no
+     * private network (a Cloudflare Worker's fetch).
+     */
+    fetch?: typeof fetch;
+    /** The addresses a host resolves to, to refuse a private one when saved: dns.lookup by default. */
+    resolve?: (hostname: string) => Promise<string[]>;
+    /** Messages and connection tests one member may send: 10 a minute, 10 at once, by default. */
+    rate?: SlotlockRate;
+    /** One model call's limit (30 s by default) and one message's (90 s). */
+    timeoutMs?: number;
+    turnTimeoutMs?: number;
+    /** Model calls one message may make (8 by default, at most 20). */
+    maxSteps?: number;
+    /** How long a conversation is kept after its last message: 2 hours by default. */
+    conversationTtlMs?: number;
+}
 export interface SlotlockDashboardOptions {
     /** Where people reach the server; the dashboard lives at `<publicUrl>/dashboard`. */
     publicUrl: string;
@@ -118,6 +179,8 @@ export interface SlotlockDashboardOptions {
     state: SlotlockDashboardState;
     /** The server's bookable hours: shown, not edited, and used by resources without their own. */
     availability?: readonly WeeklyAvailabilityRule[];
+    /** The chat assistant; off unless set. */
+    assistant?: SlotlockDashboardAssistantOptions;
     fetch?: typeof fetch;
     now?: () => number;
     /**