slotlock 0.5.0 → 0.5.2

package/config.d.ts

@@ -36,6 +36,16 @@ export interface SlotlockServeDashboardConfig {
     organizations?: string[];
     /** What the deployment is called in the dashboard (SLOTLOCK_DASHBOARD_NAME). */
     name?: string;
+    /**
+     * Seals each tenant's model API key for the dashboard assistant (SLOTLOCK_ASSISTANT_SECRET).
+     * Without it the assistant is off.
+     */
+    assistantSecret?: string;
+    /**
+     * Let the assistant reach a model at a local or private network address
+     * (SLOTLOCK_ASSISTANT_PRIVATE_URLS=on): a self-hosted model on the same machine or network.
+     */
+    assistantPrivateUrls?: boolean;
 }
 /**
  * The dashboard's settings, or undefined when none is set. Setting any of them means serving the

package/config.js

@@ -134,6 +134,15 @@ export function readDashboardConfig(env) {
     if (users === undefined || (users !== '*' && !/^[1-9]\d{0,19}(,[1-9]\d{0,19})*$/.test(users))) {
         throw new SlotlockConfigError('SLOTLOCK_DASHBOARD_USERS is required to serve the dashboard: * for every GitHub account, or a comma-separated list of GitHub user ids (gh api users/<login> --jq .id)');
     }
+    const assistantSecret = readSecret(env, 'SLOTLOCK_ASSISTANT_SECRET');
+    if (assistantSecret !== undefined &&
+        [sessionSecret, ...others].includes(assistantSecret)) {
+        throw new SlotlockConfigError('SLOTLOCK_ASSISTANT_SECRET must differ from every other secret');
+    }
+    const privateUrls = optional(env, 'SLOTLOCK_ASSISTANT_PRIVATE_URLS') ?? 'off';
+    if (privateUrls !== 'on' && privateUrls !== 'off') {
+        throw new SlotlockConfigError('SLOTLOCK_ASSISTANT_PRIVATE_URLS must be on or off');
+    }
     const orgs = readDashboardOrganizations(env);
     const name = optional(env, 'SLOTLOCK_DASHBOARD_NAME')?.trim();
     if (name !== undefined && name !== '' && !SLOTLOCK_DASHBOARD_NAME_PATTERN.test(name)) {
@@ -146,6 +155,8 @@ export function readDashboardConfig(env) {
         allowedUsers: users === '*' ? '*' : [...new Set(users.split(','))],
         ...(orgs !== undefined ? { organizations: orgs } : {}),
         ...(name !== undefined && name !== '' ? { name } : {}),
+        ...(assistantSecret !== undefined ? { assistantSecret } : {}),
+        ...(assistantSecret !== undefined && privateUrls === 'on' ? { assistantPrivateUrls: true } : {}),
     };
 }
 /**

package/dashboard.d.ts

@@ -1,4 +1,7 @@
 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';
@@ -41,6 +44,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 +79,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 +177,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;
     /**