slotlock 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and semantic
 versioning.
 
+## 0.5.2 - 2026-10-28
+
+### Added
+
+- The dashboard assistant: with `SLOTLOCK_ASSISTANT_SECRET`, an organization's owners connect a
+  model of their own in Settings (the Anthropic Messages API, or OpenAI-compatible chat
+  completions: OpenAI, OpenRouter, vLLM, Ollama, LM Studio), with a connection test, and every
+  member can operate Slotlock by chat on a new Assistant page. The server runs the tool loop (up to
+  8 model calls a message) with a fixed list of agent tools: reads run through the agent operation
+  boundary, and every write is a proposed change the member approves on a form before it runs once,
+  recorded as `dashboard-assistant:github:<user id>`, whose card shows the change in full under the
+  confirmation question's sentence. A proposal takes no series-write slot or rate token until it
+  runs, a message's reads share a budget, maintenance deletes every tenant's expired conversations
+  (`slotlock.sweep_assistant_conversations`, over the `assistant_tenants` list), and a new provider
+  or base URL takes the key again. The API key is sealed with AES-256-GCM, bound to the
+  tenant, and only its last four characters are shown. Two tenant tables under forced row-level
+  security, `assistant_settings` and `assistant_conversations`, which erasure deletes.
+  `createSlotlockRateLimiter` is the per-key token bucket it limits members' messages with, and
+  organization sessions now remember each organization's role (owners are admins). As webhooks
+  do, it refuses a model URL whose host is, or resolves to, a loopback, private, link-local, CGNAT,
+  unique-local or metadata address, when saved and at each connection (the resolved address is
+  checked as the socket connects, against DNS rebinding); `SLOTLOCK_ASSISTANT_PRIVATE_URLS=on`
+  allows them for a self-hosted model. `createSlotlockGuardedFetch` is that `fetch`.
+
 ## 0.5.1 - 2026-10-28
 
 ### Fixed

package/README.md

@@ -304,6 +304,59 @@ resources, so you can give each person API keys without running `slotlock key cr
   own on the hours page: two windows a day, overnight or all day, or closed. One form sets them
   for every resource at once.
 
+#### Assistant: operate Slotlock by chat
+
+With `SLOTLOCK_ASSISTANT_SECRET` set (32+ random characters, `openssl rand -hex 32`), the dashboard
+gains an Assistant page where every member chats with a model their organization connects, instead
+of clicking. Each organization brings its own model:
+
+- **Connect it** in Settings, Assistant (owners only; with personal tenants, each person): the
+  provider (`Anthropic Messages API`, or `OpenAI-compatible`, which covers OpenAI, OpenRouter,
+  vLLM, Ollama and LM Studio), the base URL (`https://api.anthropic.com`, or the one ending in
+  `/v1`: `https://api.openai.com/v1`, `http://localhost:11434/v1`; https, or http only on
+  `localhost` or `127.0.0.1`), the model name (`your-model`) and the API key, which a local model
+  may not need. As with webhooks, a URL whose host is, or resolves to, a loopback, private,
+  link-local, shared (CGNAT), unique-local or metadata address (`169.254.169.254`) is refused, when
+  it is saved and at each connection (the address the socket connects to is checked, so a name
+  rebound to one is refused too), and the page says why. For a self-hosted model on the server's
+  own machine or network (Ollama, vLLM), the operator sets `SLOTLOCK_ASSISTANT_PRIVATE_URLS=on`.
+  On Cloudflare Workers the literal check applies and names are not resolved: a Worker's fetch
+  reaches no private network. Changing the provider or the base URL takes the key again (decided in the
+  database write, so racing saves cannot get past it), so the stored key is only ever sent where it
+  was entered for, even on an origin that serves several accounts. **Test connection** makes one real request
+  and checks the model answers with one correct tool call. The organization's messages, and the bookings and resources the assistant
+  reads, are sent to the provider it configures.
+- **The key** is stored sealed with AES-256-GCM under a key derived from `SLOTLOCK_ASSISTANT_SECRET`,
+  bound to the organization, in `slotlock.assistant_settings` (forced row-level security, erased
+  with the tenant). The dashboard shows only that it is set and its last four characters. Changing
+  the secret makes stored keys unreadable: owners enter them again.
+- **Reads run, writes wait.** The server runs the tool loop, up to 8 model calls a message, with a
+  fixed list of the agent tools (the reads: resources, free-busy, next free time, slots, pool
+  availability, events; the writes: holds, bookings, pool and bundle bookings, changes and
+  cancellations). A read runs at once through the same operation boundary as an agent's. A write
+  never runs when the model asks: it appears as a proposed change the member approves (or
+  dismisses) with a form, and only then runs, once (its idempotency key is the dashboard's), with
+  the same booking rules, tenant limits and rate limits as an agent, recorded as
+  `dashboard-assistant:github:<user id>` (shown as "Assistant for @login"). The card leads with
+  the sentence a confirmation would ask (the resource by name, the times in its zone, and for a
+  change or cancellation the event's title, resource and time as it stands) and then shows every
+  argument in full; a change too large to show (16 KB of arguments) is not proposed, and a
+  conversation has at most 4 waiting. A proposal is only checked: the series-write slot and the
+  write's rate token are taken when the approved change runs. A message's reads share a budget of
+  16 calls and 400 resource-days. API keys, webhooks, booking rules, pools, erasure and
+  coverage are never offered; a tool the model names outside the list is refused.
+- Tool results and booking data are data to the model, never instructions, and the system prompt
+  says so; the tool list does not change with what the model says. A member may send 10 messages
+  a minute; each model call has 30 seconds and a message 90. Conversations are kept per member in
+  `slotlock.assistant_conversations` for 2 hours after the last message, then deleted: by
+  `serve`'s maintenance, which sweeps every tenant's expired conversations every quarter hour (a
+  tenant only the dashboard serves included), by `slotlock maintain`, and whenever the tenant's
+  conversations are read (so on Workers too). They are bounded in UTF-8 bytes; **New conversation** forgets one. On Workers, the
+  assistant's agent calls are capped at 24 a request and by `tenant_read` and `tenant_write` of
+  `SLOTLOCK_LIMITS` in each isolate. A provider's failure is shown as a plain message, never with
+  the key or the provider's answer.
+- It works as plain forms: no script is needed.
+
 ### Dashboard on Cloudflare Workers
 
 The same dashboard can run as a Cloudflare Worker at an origin of its own (`workers/dashboard`),
@@ -337,7 +390,8 @@ this one and read its session secret, which signs in as any tenant.
 3. Create the GitHub OAuth app as above, with the callback URL
    `<SLOTLOCK_PUBLIC_URL>/dashboard/callback` on the Worker's origin.
 4. Store the secrets on the Worker: `npx wrangler secret put` for `SLOTLOCK_GITHUB_CLIENT_ID`,
-   `SLOTLOCK_GITHUB_CLIENT_SECRET` and `SLOTLOCK_SESSION_SECRET`.
+   `SLOTLOCK_GITHUB_CLIENT_SECRET` and `SLOTLOCK_SESSION_SECRET`, and `SLOTLOCK_ASSISTANT_SECRET`
+   for the assistant.
 5. Deploy: `npm ci --omit=dev` at the repository root (the Worker bundles Slotlock's sources), then
    `npx wrangler deploy --config <your configuration>` in `workers/dashboard`.
 

package/agent-server.d.ts

@@ -464,6 +464,20 @@ export declare function parseSlotlockA2ATimestamp(value: unknown): Date | null;
 export declare const SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE = "slotlock://resources/{resource_id}";
 /** The MCP resource URI of one calendar resource: `SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE`, expanded. */
 export declare function slotlockCalendarResourceUri(resourceId: string): string;
+/**
+ * The sentence a person is asked to confirm for a write, as the confirmation flow words it: the
+ * resource by name and the times in its own zone, and for a change or deletion the event as it
+ * stands (its title, resource and time), each read as `principal` only where its scopes and
+ * `authorize` allow that read. The dashboard assistant shows it on a proposed change.
+ */
+export declare function describeSlotlockAgentWrite(args: {
+    backend: SlotlockAgentCalendarBackend;
+    authorize: SlotlockAgentServerOptions['authorize'];
+    principal: SlotlockAgentPrincipal;
+    operation: SlotlockAgentWriteOperation;
+    input: Record<string, unknown>;
+    signal: AbortSignal;
+}): Promise<string>;
 export declare function createSlotlockAgentServer(options: SlotlockAgentServerOptions): {
     fetch(request: Request): Promise<Response>;
     manifest: Readonly<Record<string, unknown>>;

package/agent-server.js

@@ -1912,6 +1912,21 @@ function confirmationLookup(options, context) {
         },
     };
 }
+/**
+ * The sentence a person is asked to confirm for a write, as the confirmation flow words it: the
+ * resource by name and the times in its own zone, and for a change or deletion the event as it
+ * stands (its title, resource and time), each read as `principal` only where its scopes and
+ * `authorize` allow that read. The dashboard assistant shows it on a proposed change.
+ */
+export async function describeSlotlockAgentWrite(args) {
+    const lookup = confirmationLookup({ backend: args.backend, authorize: args.authorize }, { principal: args.principal, signal: args.signal });
+    try {
+        return await confirmationMessage(args.operation, args.input, lookup);
+    }
+    finally {
+        lookup.close();
+    }
+}
 /**
  * The sentence a person confirms: what changes, where and when. The facts the server establishes
  * (the resource, the times in its own zone, every date a repeat books, the event as it stands) come

package/assistant.d.ts

@@ -0,0 +1,263 @@
+import { type SlotlockAgentOperation } from './agent-server.js';
+import type { SlotlockAssistantConversationRecord, SlotlockAssistantSettingsRecord, SlotlockStore } from './store.js';
+export type SlotlockAssistantProvider = 'anthropic' | 'openai';
+/** What the assistant does with each agent operation: run it, propose it, or never offer it. */
+export type SlotlockAssistantToolUse = 'read' | 'propose' | 'excluded';
+/**
+ * The tools the model is offered, by agent operation. A record over every operation, so one a later
+ * release adds does not compile until it is placed here. Reads run when the model calls them;
+ * every write is only proposed, and runs when the member approves it. API keys, webhooks, booking
+ * rules, pools, erasure and coverage are application operations, never agent ones, so no entry can
+ * offer them.
+ */
+export declare const SLOTLOCK_ASSISTANT_TOOL_USE: Readonly<Record<SlotlockAgentOperation, SlotlockAssistantToolUse>>;
+/** Model calls one message may make before the assistant stops and says so. */
+export declare const SLOTLOCK_ASSISTANT_MAX_STEPS = 8;
+/** Characters of one message from a member. */
+export declare const SLOTLOCK_ASSISTANT_MAX_MESSAGE = 2000;
+/**
+ * UTF-8 bytes of the stored conversation as JSON, past which the oldest exchanges go first.
+ * PostgreSQL's jsonb text adds at most one space per `:` or `,`, so at most half again: under the
+ * table's 262,144-byte CHECK on `messages::text` whatever the text.
+ */
+export declare const SLOTLOCK_ASSISTANT_MAX_STORED_BYTES = 160000;
+/** UTF-8 bytes of one proposed change's arguments as JSON; a larger one is not proposed. */
+export declare const SLOTLOCK_ASSISTANT_MAX_ACTION_BYTES = 16000;
+/** Proposed changes one conversation may have waiting at once (4 of the largest fit the bound). */
+export declare const SLOTLOCK_ASSISTANT_MAX_PENDING = 4;
+/**
+ * The Messages API version this sends: the one @anthropic-ai/sdk 1.3.0 (2026-10-23) sends, read
+ * from its source on 2026-10-28. Top-level `system`, `tools[].input_schema`, `tool_use` and
+ * `tool_result` blocks are as before in it.
+ */
+export declare const SLOTLOCK_ANTHROPIC_VERSION = "2026-10-21";
+/** A model as the assistant calls it, with the key opened. */
+export interface SlotlockAssistantModel {
+    provider: SlotlockAssistantProvider;
+    baseUrl: string;
+    model: string;
+    apiKey: string | null;
+}
+export interface SlotlockAssistantCall {
+    id: string;
+    name: string;
+    input: unknown;
+}
+/** One entry of a stored conversation. `note`s are shown to the member and never sent to the model. */
+export type SlotlockAssistantEntry = {
+    role: 'user';
+    text: string;
+} | {
+    role: 'assistant';
+    text: string;
+    calls: SlotlockAssistantCall[];
+} | {
+    role: 'tool';
+    results: {
+        id: string;
+        name: string;
+        content: string;
+        error: boolean;
+        action?: string;
+    }[];
+} | {
+    role: 'event';
+    text: string;
+} | {
+    role: 'note';
+    text: string;
+};
+/** A proposed write, as the conversation keeps it. */
+export interface SlotlockAssistantAction {
+    id: string;
+    operation: SlotlockAgentOperation;
+    input: Record<string, unknown>;
+    status: 'pending' | 'approved' | 'dismissed' | 'done' | 'failed';
+    /** What it did (`done`), or the code it failed with (`failed`). */
+    outcome?: string;
+    /** The change in a sentence, with its resource and event resolved (the confirmation question). */
+    summary?: string;
+}
+/** Where the dashboard keeps assistant settings and conversations: the store, under each tenant's RLS. */
+export interface SlotlockAssistantStore {
+    getSettings(tenantRef: string): Promise<SlotlockAssistantSettingsRecord | null>;
+    putSettings(tenantRef: string, settings: {
+        provider: SlotlockAssistantProvider;
+        baseUrl: string;
+        model: string;
+        key: {
+            sealed: string;
+            hint: string;
+        } | null | 'keep';
+    }, actor?: string): Promise<{
+        saved: boolean;
+    }>;
+    deleteSettings(tenantRef: string, actor?: string): Promise<boolean>;
+    getConversation(tenantRef: string, memberRef: string): Promise<SlotlockAssistantConversationRecord | null>;
+    /**
+     * Replace a member's messages; keep the stored actions `keep` names, as they stand, and add the
+     * `added` ones not stored already (store.ts putAssistantConversation).
+     */
+    putConversation(tenantRef: string, memberRef: string, conversation: {
+        messages: unknown[];
+        added: Record<string, Record<string, unknown>>;
+        keep: readonly string[];
+    }, ttlMs: number): Promise<void>;
+    settleAction(tenantRef: string, memberRef: string, actionId: string, from: string, patch: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    deleteConversation(tenantRef: string, memberRef: string): Promise<boolean>;
+}
+/** The assistant's records in the store, each in a transaction under the tenant's row-level security. */
+export declare function createSlotlockAssistantStore(store: SlotlockStore): SlotlockAssistantStore;
+/** The assistant's records in this process: for tests, or a server that only ever runs as one. */
+export declare function createSlotlockMemoryAssistantStore(now?: () => number): SlotlockAssistantStore;
+/** The key sealed for one tenant: `v1.<iv>.<ciphertext and tag>`, base64url. */
+export declare function sealSlotlockAssistantKey(secret: string, tenantRef: string, apiKey: string): Promise<string>;
+/** The key a seal holds, or null when it is not one this secret sealed for this tenant. */
+export declare function openSlotlockAssistantKey(secret: string, tenantRef: string, sealed: string): Promise<string | null>;
+/**
+ * A provider base URL as stored: https, or http on localhost or 127.0.0.1 (a model on the server's
+ * own machine); no credentials, query or fragment; no trailing slash. Unless `privateUrls`, a URL
+ * whose host is `localhost` or a loopback, private, link-local, shared (CGNAT), unique-local or
+ * metadata address (the webhooks' isPrivateAddress) is refused as `private`; a name that resolves
+ * to one is refused when it is resolved (checkSlotlockAssistantHost, and at each connection).
+ */
+export declare function readSlotlockAssistantBaseUrl(value: string, options?: {
+    privateUrls?: boolean;
+}): {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    reason: 'invalid' | 'private';
+};
+/**
+ * Whether a base URL's host resolves only to public addresses: `resolve` lists them (dns.lookup's,
+ * on Node.js). True when `privateUrls`, or when the host is an IP literal readSlotlockAssistantBaseUrl
+ * already checked; false when any address is private. A name that does not resolve is not refused
+ * here: the connection fails later, plainly.
+ */
+export declare function checkSlotlockAssistantHost(baseUrl: string, options: {
+    privateUrls?: boolean;
+    resolve?: (hostname: string) => Promise<string[]>;
+}): Promise<boolean>;
+/** A model name: 1-200 printable characters, no spaces. */
+export declare const SLOTLOCK_ASSISTANT_MODEL_NAME: RegExp;
+/** An API key as typed: 1-4,096 printable characters, no spaces. */
+export declare const SLOTLOCK_ASSISTANT_API_KEY: RegExp;
+export interface SlotlockAssistantTool {
+    name: SlotlockAgentOperation;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    use: 'read' | 'propose';
+}
+/**
+ * The tools the model is offered: every agent tool the assistant reads or proposes, with its input
+ * schema less `idempotency_key`, which the dashboard sets itself so an approval runs once.
+ */
+export declare function slotlockAssistantTools(): SlotlockAssistantTool[];
+/** Why a provider call failed, in words safe to show (never the key, never the provider's body). */
+export declare class SlotlockAssistantProviderError extends Error {
+    readonly reason: 'timeout' | 'refused_key' | 'not_found' | 'rate_limited' | 'unavailable' | 'bad_answer' | 'private_address';
+    readonly status?: number | undefined;
+    constructor(reason: 'timeout' | 'refused_key' | 'not_found' | 'rate_limited' | 'unavailable' | 'bad_answer' | 'private_address', status?: number | undefined);
+}
+/** What to tell the member a provider failure was. */
+export declare function slotlockAssistantProviderMessage(error: unknown): string;
+/** One answer of the model: its text and the tools it called. */
+export interface SlotlockAssistantModelTurn {
+    text: string;
+    calls: SlotlockAssistantCall[];
+}
+interface ModelRequest {
+    model: SlotlockAssistantModel;
+    system: string;
+    entries: readonly SlotlockAssistantEntry[];
+    tools: readonly {
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+    }[];
+    /** Make the model call this tool (the connection test). */
+    force?: string;
+    fetch: typeof fetch;
+    signal: AbortSignal;
+}
+/** One model call. Throws SlotlockAssistantProviderError, whose message never holds the key. */
+export declare function callSlotlockAssistantModel(request: ModelRequest): Promise<SlotlockAssistantModelTurn>;
+/**
+ * The connection test: one request offering one read tool the model must call. True when it
+ * answers with exactly one call of that tool with object arguments.
+ */
+export declare function testSlotlockAssistantModel(args: {
+    model: SlotlockAssistantModel;
+    fetch: typeof fetch;
+    timeoutMs: number;
+}): Promise<boolean>;
+/** How a tool call came out, as the loop tells the model. */
+export type SlotlockAssistantToolOutcome = {
+    ok: true;
+    data: Record<string, unknown>;
+} | {
+    ok: false;
+    code: string;
+    details?: Readonly<Record<string, string>>;
+};
+/** A URL checked again before each call: one stored under looser rules is refused, not reached. */
+export declare function slotlockAssistantUrlAllowed(baseUrl: string, privateUrls: boolean): boolean;
+export interface SlotlockAssistantTurnOptions {
+    model: SlotlockAssistantModel;
+    system: string;
+    /** The conversation so far, ending with the member's new message. */
+    entries: readonly SlotlockAssistantEntry[];
+    fetch: typeof fetch;
+    /** Each model call's limit, and the whole turn's. */
+    timeoutMs: number;
+    turnTimeoutMs: number;
+    maxSteps?: number;
+    /** Run a read the model asked for. */
+    read(operation: SlotlockAgentOperation, input: unknown): Promise<SlotlockAssistantToolOutcome>;
+    /** Check a write the model asked for and keep it for the member to approve: its action id. */
+    propose(operation: SlotlockAgentOperation, input: unknown): Promise<{
+        ok: true;
+        actionId: string;
+    } | {
+        ok: false;
+        code: string;
+    }>;
+}
+export interface SlotlockAssistantTurnResult {
+    /** The entries this turn added. */
+    added: SlotlockAssistantEntry[];
+    /** Set when the provider failed; `added` then ends with a note saying so. */
+    failure?: unknown;
+}
+/**
+ * One member message: call the model, run what it reads, keep what it would write, and call it
+ * again with the results, up to `maxSteps` calls. Only the offered tools run, whatever the model
+ * names; everything else is answered `tool_not_available`.
+ */
+export declare function runSlotlockAssistantTurn(options: SlotlockAssistantTurnOptions): Promise<SlotlockAssistantTurnResult>;
+/**
+ * The conversation within its bounds: at most MAX_ENTRIES entries and MAX_STORED_CHARACTERS, the
+ * oldest exchanges dropped whole, so it always starts at a member's message (a tool result is never
+ * kept without the call it answers).
+ */
+export declare function boundSlotlockAssistantEntries(entries: readonly SlotlockAssistantEntry[]): SlotlockAssistantEntry[];
+/**
+ * The actions a conversation keeps: those its kept entries show, the oldest settled ones dropped
+ * first past MAX_ACTIONS_BYTES (a waiting one is kept: SLOTLOCK_ASSISTANT_MAX_PENDING bounds them).
+ */
+export declare function pruneSlotlockAssistantActions(entries: readonly SlotlockAssistantEntry[], actions: Readonly<Record<string, Record<string, unknown>>>): Record<string, Record<string, unknown>>;
+/** How many of a conversation's actions wait for the member. */
+export declare function pendingSlotlockAssistantActions(actions: Readonly<Record<string, Record<string, unknown>>>): number;
+/** Read stored entries back, dropping anything malformed. */
+export declare function readSlotlockAssistantEntries(value: unknown): SlotlockAssistantEntry[];
+/** The system prompt: who the model works for, and that what it reads is data, not instructions. */
+export declare function slotlockAssistantSystemPrompt(args: {
+    brand: string;
+    workspace: string;
+    login: string;
+    now: Date;
+}): string;
+export {};