slotlock 0.6.3 → 0.7.0

package/approvals.d.ts

@@ -0,0 +1,88 @@
+import type { Sql, TransactionSql } from 'postgres';
+import type { SlotlockApproval, SlotlockApprovalKind, SlotlockApprovalPolicy } from './types.js';
+type StoreSql = Sql | TransactionSql;
+/** The longest a policy may let a write wait for a person: 30 days. */
+export declare const SLOTLOCK_MAX_APPROVAL_MINUTES: number;
+/** The wait a policy that names none gives a person: a day. */
+export declare const SLOTLOCK_DEFAULT_APPROVAL_MINUTES: number;
+/** The policy reference a key whose bookings all wait for a person is held by (RFC 0004 A5). */
+export declare const SLOTLOCK_KEY_APPROVAL_POLICY = "api-key";
+/** Policies one tenant may have. */
+export declare const SLOTLOCK_MAX_APPROVAL_POLICIES = 50;
+export declare const SLOTLOCK_APPROVAL_KINDS: readonly SlotlockApprovalKind[];
+export declare class SlotlockApprovalPolicyError extends Error {
+    readonly code: 'invalid_approval_policy';
+    constructor(message: string);
+}
+export interface PutApprovalPolicyParams {
+    tenantRef: string;
+    ref: string;
+    name: string;
+    appliesTo?: SlotlockApprovalPolicy['appliesTo'];
+    conditions?: SlotlockApprovalPolicy['conditions'];
+    outcome: SlotlockApprovalPolicy['outcome'];
+    approvalTtlMinutes?: number;
+    leadMinutes?: number;
+}
+/** Create or replace a policy by its reference. Throws `invalid_approval_policy`; at most 50. */
+export declare function putApprovalPolicy(sql: StoreSql, params: PutApprovalPolicyParams): Promise<SlotlockApprovalPolicy | null>;
+export declare function listApprovalPolicies(sql: StoreSql, tenantRef: string): Promise<SlotlockApprovalPolicy[]>;
+export declare function deleteApprovalPolicy(sql: StoreSql, tenantRef: string, ref: string): Promise<boolean>;
+/**
+ * The tenant's policies that apply to any of these resources: by id, pool, location (a resource in
+ * a location inside one named counts) or group, or every resource when a policy names none.
+ */
+export declare function approvalPoliciesFor(sql: StoreSql, tenantRef: string, resourceIds: readonly string[]): Promise<SlotlockApprovalPolicy[]>;
+interface ApprovalRow {
+    id: string;
+    policy_ref: string;
+    status: SlotlockApproval['status'];
+    operation: SlotlockApproval['operation'];
+    request: Record<string, unknown>;
+    requester: Record<string, unknown>;
+    hold_ids: string[];
+    resource_ids: string[];
+    starts_at: Date;
+    ends_at: Date;
+    expires_at: Date;
+    decided_by: string | null;
+    decided_at: Date | null;
+    reason: string | null;
+    created_at: Date;
+}
+export declare const APPROVAL_COLUMNS = "id, policy_ref, status, operation, request, requester, hold_ids, resource_ids, starts_at, ends_at, expires_at, decided_by, decided_at, reason, created_at";
+export declare function toApproval(row: ApprovalRow): SlotlockApproval;
+export type ApprovalRowWithRequester = ApprovalRow;
+export declare function listApprovals(sql: StoreSql, params: {
+    tenantRef: string;
+    status?: SlotlockApproval['status'];
+    limit: number;
+}): Promise<SlotlockApproval[]>;
+/** One approval with whom it runs as, for a grant. */
+export declare function getApproval(sql: StoreSql, tenantRef: string, id: string): Promise<(SlotlockApproval & {
+    requester: Record<string, unknown>;
+}) | null>;
+/** The approval a requester's retry made, by its request key. */
+export declare function approvalByRequestKey(sql: StoreSql, tenantRef: string, requestKey: string): Promise<SlotlockApproval | null>;
+declare function noteApproval(sql: StoreSql, tenantRef: string, type: string, approval: SlotlockApproval): Promise<void>;
+export { noteApproval as recordApprovalChange };
+type Decided = {
+    ok: true;
+    approval: SlotlockApproval;
+} | {
+    ok: false;
+    code: 'approval_not_found' | 'approval_not_pending' | 'approval_expired';
+};
+/** Lock a pending, unexpired approval and let its holds go: the first half of a grant. */
+export declare function beginApprovalGrant(sql: StoreSql, tenantRef: string, id: string): Promise<Decided>;
+/** Mark a granted approval, in the transaction that made its write: the second half. */
+export declare function finishApprovalGrant(sql: StoreSql, tenantRef: string, id: string, decidedBy: string): Promise<SlotlockApproval>;
+/** Decline a pending approval: its holds go, and the feed says so. */
+export declare function declineApproval(sql: StoreSql, params: {
+    tenantRef: string;
+    id: string;
+    decidedBy: string;
+    reason?: string;
+}): Promise<Decided>;
+/** Maintenance: pending approvals past their wait expire, their holds go. How many did. */
+export declare function expireApprovals(sql: StoreSql, tenantRef: string, limit: number): Promise<number>;

package/approvals.js

@@ -0,0 +1,293 @@
+/** The longest a policy may let a write wait for a person: 30 days. */
+export const SLOTLOCK_MAX_APPROVAL_MINUTES = 30 * 24 * 60;
+/** The wait a policy that names none gives a person: a day. */
+export const SLOTLOCK_DEFAULT_APPROVAL_MINUTES = 24 * 60;
+/** The policy reference a key whose bookings all wait for a person is held by (RFC 0004 A5). */
+export const SLOTLOCK_KEY_APPROVAL_POLICY = 'api-key';
+/** Policies one tenant may have. */
+export const SLOTLOCK_MAX_APPROVAL_POLICIES = 50;
+export const SLOTLOCK_APPROVAL_KINDS = Object.freeze(['single', 'pool', 'bundle', 'move']);
+const POLICY_REF = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+const GROUPING_REF = /^[a-z0-9][a-z0-9_.-]{0,99}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** References of each kind a policy's applies_to may name. */
+const MAX_APPLIES_TO = 50;
+export class SlotlockApprovalPolicyError extends Error {
+    code = 'invalid_approval_policy';
+    constructor(message) {
+        super(`Slotlock approval policy: ${message}`);
+    }
+}
+const POLICY_COLUMNS = 'ref, name, applies_to, conditions, outcome, approval_ttl_minutes, lead_minutes, created_at, updated_at';
+function toPolicy(row) {
+    const applies = row.applies_to;
+    const conditions = row.conditions;
+    return {
+        ref: row.ref,
+        name: row.name,
+        appliesTo: {
+            ...(applies.resource_ids ? { resourceIds: applies.resource_ids } : {}),
+            ...(applies.pools ? { pools: applies.pools } : {}),
+            ...(applies.locations ? { locations: applies.locations } : {}),
+            ...(applies.groups ? { groups: applies.groups } : {}),
+        },
+        conditions: {
+            ...(conditions.longer_than_minutes !== undefined ? { longerThanMinutes: conditions.longer_than_minutes } : {}),
+            ...(conditions.outside_hours !== undefined ? { outsideHours: conditions.outside_hours } : {}),
+            ...(conditions.kinds ? { kinds: conditions.kinds } : {}),
+        },
+        outcome: row.outcome,
+        approvalTtlMinutes: row.approval_ttl_minutes,
+        leadMinutes: row.lead_minutes,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function refList(values, pattern, what) {
+    if (values === undefined)
+        return undefined;
+    if (!Array.isArray(values) || values.length > MAX_APPLIES_TO || values.some((value) => !pattern.test(value))) {
+        throw new SlotlockApprovalPolicyError(`${what} must be at most ${MAX_APPLIES_TO} references`);
+    }
+    return [...new Set(values)].sort();
+}
+/** A policy's stored shape, checked: applies_to and conditions in snake_case JSON. */
+function storedPolicy(params) {
+    if (!POLICY_REF.test(params.ref))
+        throw new SlotlockApprovalPolicyError('ref must be 1-63 of a-z, 0-9, _ and -');
+    if (params.ref === SLOTLOCK_KEY_APPROVAL_POLICY) {
+        throw new SlotlockApprovalPolicyError(`ref ${SLOTLOCK_KEY_APPROVAL_POLICY} is the one a key's own approval uses`);
+    }
+    const name = params.name.trim();
+    if (name.length < 1 || name.length > 200)
+        throw new SlotlockApprovalPolicyError('name must be 1-200 characters');
+    if (params.outcome !== 'require_approval' && params.outcome !== 'refuse') {
+        throw new SlotlockApprovalPolicyError('outcome must be require_approval or refuse');
+    }
+    const ttl = params.approvalTtlMinutes ?? SLOTLOCK_DEFAULT_APPROVAL_MINUTES;
+    const lead = params.leadMinutes ?? 0;
+    if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > SLOTLOCK_MAX_APPROVAL_MINUTES) {
+        throw new SlotlockApprovalPolicyError(`approval_ttl_minutes must be 1-${SLOTLOCK_MAX_APPROVAL_MINUTES}`);
+    }
+    if (!Number.isSafeInteger(lead) || lead < 0 || lead > SLOTLOCK_MAX_APPROVAL_MINUTES) {
+        throw new SlotlockApprovalPolicyError(`lead_minutes must be 0-${SLOTLOCK_MAX_APPROVAL_MINUTES}`);
+    }
+    const applies = params.appliesTo ?? {};
+    const resourceIds = refList(applies.resourceIds, UUID, 'resource_ids');
+    const appliesTo = {
+        ...(resourceIds ? { resource_ids: resourceIds.map((id) => id.toLowerCase()) } : {}),
+        ...(applies.pools ? { pools: refList(applies.pools, GROUPING_REF, 'pools') } : {}),
+        ...(applies.locations ? { locations: refList(applies.locations, GROUPING_REF, 'locations') } : {}),
+        ...(applies.groups ? { groups: refList(applies.groups, GROUPING_REF, 'groups') } : {}),
+    };
+    const given = params.conditions ?? {};
+    if (given.longerThanMinutes !== undefined &&
+        (!Number.isSafeInteger(given.longerThanMinutes) || given.longerThanMinutes < 0 || given.longerThanMinutes > 5_270_400)) {
+        throw new SlotlockApprovalPolicyError('longer_than_minutes must be 0-5,270,400');
+    }
+    if (given.outsideHours !== undefined && typeof given.outsideHours !== 'boolean') {
+        throw new SlotlockApprovalPolicyError('outside_hours must be true or false');
+    }
+    if (given.kinds !== undefined &&
+        (!Array.isArray(given.kinds) ||
+            given.kinds.length === 0 ||
+            given.kinds.some((kind) => !SLOTLOCK_APPROVAL_KINDS.includes(kind)))) {
+        throw new SlotlockApprovalPolicyError(`kinds must name some of ${SLOTLOCK_APPROVAL_KINDS.join(', ')}`);
+    }
+    const conditions = {
+        ...(given.longerThanMinutes !== undefined ? { longer_than_minutes: given.longerThanMinutes } : {}),
+        ...(given.outsideHours !== undefined ? { outside_hours: given.outsideHours } : {}),
+        ...(given.kinds !== undefined ? { kinds: [...new Set(given.kinds)].sort() } : {}),
+    };
+    return { name, appliesTo, conditions, ttl, lead };
+}
+/** Create or replace a policy by its reference. Throws `invalid_approval_policy`; at most 50. */
+export async function putApprovalPolicy(sql, params) {
+    const stored = storedPolicy(params);
+    const [row] = await sql `
+    INSERT INTO slotlock.approval_policies (
+      tenant_ref, ref, name, applies_to, conditions, outcome, approval_ttl_minutes, lead_minutes
+    )
+    SELECT ${params.tenantRef}, ${params.ref}, ${stored.name}, ${sql.json(stored.appliesTo)},
+           ${sql.json(stored.conditions)}, ${params.outcome}, ${stored.ttl}, ${stored.lead}
+     WHERE EXISTS (SELECT 1 FROM slotlock.approval_policies WHERE tenant_ref = ${params.tenantRef} AND ref = ${params.ref})
+        OR (SELECT count(*) FROM slotlock.approval_policies WHERE tenant_ref = ${params.tenantRef})
+           < ${SLOTLOCK_MAX_APPROVAL_POLICIES}
+    ON CONFLICT (tenant_ref, ref) DO UPDATE
+      SET name = EXCLUDED.name, applies_to = EXCLUDED.applies_to, conditions = EXCLUDED.conditions,
+          outcome = EXCLUDED.outcome, approval_ttl_minutes = EXCLUDED.approval_ttl_minutes,
+          lead_minutes = EXCLUDED.lead_minutes, updated_at = statement_timestamp()
+    RETURNING ${sql.unsafe(POLICY_COLUMNS)}`;
+    return row ? toPolicy(row) : null;
+}
+export async function listApprovalPolicies(sql, tenantRef) {
+    const rows = await sql `
+    SELECT ${sql.unsafe(POLICY_COLUMNS)} FROM slotlock.approval_policies
+     WHERE tenant_ref = ${tenantRef} ORDER BY ref`;
+    return rows.map(toPolicy);
+}
+export async function deleteApprovalPolicy(sql, tenantRef, ref) {
+    if (!POLICY_REF.test(ref))
+        return false;
+    const rows = await sql `DELETE FROM slotlock.approval_policies WHERE tenant_ref = ${tenantRef} AND ref = ${ref} RETURNING ref`;
+    return rows.length > 0;
+}
+/**
+ * The tenant's policies that apply to any of these resources: by id, pool, location (a resource in
+ * a location inside one named counts) or group, or every resource when a policy names none.
+ */
+export async function approvalPoliciesFor(sql, tenantRef, resourceIds) {
+    const ids = resourceIds.filter((id) => UUID.test(id));
+    if (ids.length === 0)
+        return [];
+    const rows = await sql `
+    SELECT ${sql.unsafe(POLICY_COLUMNS.split(', ').map((column) => `policy.${column}`).join(', '))}
+      FROM slotlock.approval_policies policy
+     WHERE policy.tenant_ref = ${tenantRef}
+       AND EXISTS (
+         SELECT 1 FROM slotlock.resources resource
+          WHERE resource.tenant_ref = ${tenantRef} AND resource.id = ANY (${ids}::uuid[])
+            AND (policy.applies_to = '{}'::jsonb
+                 OR resource.id::text IN (SELECT pg_catalog.jsonb_array_elements_text(policy.applies_to -> 'resource_ids'))
+                 OR resource.pool_ref IN (SELECT pg_catalog.jsonb_array_elements_text(policy.applies_to -> 'pools'))
+                 OR (resource.location_ref IS NOT NULL
+                     AND slotlock.location_path(resource.tenant_ref, resource.location_ref)
+                         && ARRAY(SELECT pg_catalog.jsonb_array_elements_text(policy.applies_to -> 'locations')))
+                 OR EXISTS (
+                   SELECT 1 FROM slotlock.resource_group_members member
+                    WHERE member.tenant_ref = resource.tenant_ref AND member.resource_id = resource.id
+                      AND member.group_ref IN (SELECT pg_catalog.jsonb_array_elements_text(policy.applies_to -> 'groups')))))
+     ORDER BY policy.ref`;
+    return rows.map(toPolicy);
+}
+export const APPROVAL_COLUMNS = 'id, policy_ref, status, operation, request, requester, hold_ids, resource_ids, starts_at, ends_at, expires_at, decided_by, decided_at, reason, created_at';
+export function toApproval(row) {
+    return {
+        id: row.id,
+        policyRef: row.policy_ref,
+        status: row.status,
+        operation: row.operation,
+        request: row.request,
+        requestedBy: typeof row.requester.subject === 'string'
+            ? row.requester.subject.replace(/[\u0000-\u001f\u007f]/g, '').slice(0, 200) || null
+            : null,
+        holdIds: row.hold_ids,
+        resourceIds: row.resource_ids,
+        start: row.starts_at,
+        end: row.ends_at,
+        expiresAt: row.expires_at,
+        decidedBy: row.decided_by,
+        decidedAt: row.decided_at,
+        reason: row.reason,
+        createdAt: row.created_at,
+    };
+}
+export async function listApprovals(sql, params) {
+    const rows = await sql `
+    SELECT ${sql.unsafe(APPROVAL_COLUMNS)} FROM slotlock.approvals
+     WHERE tenant_ref = ${params.tenantRef}
+       AND (${params.status ?? null}::text IS NULL OR status = ${params.status ?? null})
+     ORDER BY created_at DESC, id
+     LIMIT ${params.limit}`;
+    return rows.map(toApproval);
+}
+/** One approval with whom it runs as, for a grant. */
+export async function getApproval(sql, tenantRef, id) {
+    if (!UUID.test(id))
+        return null;
+    const [row] = await sql `
+    SELECT ${sql.unsafe(APPROVAL_COLUMNS)} FROM slotlock.approvals WHERE tenant_ref = ${tenantRef} AND id = ${id}`;
+    return row ? { ...toApproval(row), requester: row.requester } : null;
+}
+/** The approval a requester's retry made, by its request key. */
+export async function approvalByRequestKey(sql, tenantRef, requestKey) {
+    const [row] = await sql `
+    SELECT ${sql.unsafe(APPROVAL_COLUMNS)} FROM slotlock.approvals
+     WHERE tenant_ref = ${tenantRef} AND request_key = ${requestKey}`;
+    return row ? toApproval(row) : null;
+}
+async function noteApproval(sql, tenantRef, type, approval) {
+    await sql `
+    INSERT INTO slotlock.outbox (tenant_ref, resource_id, type, subject, data, actor)
+    VALUES (${tenantRef}, ${approval.resourceIds[0] ?? null}, ${type}, ${approval.id},
+            ${sql.json({
+        id: approval.id,
+        policy: approval.policyRef,
+        operation: approval.operation,
+        status: approval.status,
+        resource_ids: approval.resourceIds,
+        start: approval.start.toISOString(),
+        end: approval.end.toISOString(),
+        expires_at: approval.expiresAt.toISOString(),
+        ...(approval.reason ? { reason: approval.reason } : {}),
+    })},
+            NULLIF(current_setting('slotlock.actor', true), ''))`;
+}
+export { noteApproval as recordApprovalChange };
+/** Lock a pending, unexpired approval and let its holds go: the first half of a grant. */
+export async function beginApprovalGrant(sql, tenantRef, id) {
+    if (!UUID.test(id))
+        return { ok: false, code: 'approval_not_found' };
+    const [row] = await sql `
+    SELECT ${sql.unsafe(APPROVAL_COLUMNS)}, expires_at > statement_timestamp() AS live
+      FROM slotlock.approvals WHERE tenant_ref = ${tenantRef} AND id = ${id} FOR UPDATE`;
+    if (!row)
+        return { ok: false, code: 'approval_not_found' };
+    if (row.status !== 'pending')
+        return { ok: false, code: 'approval_not_pending' };
+    if (!row.live)
+        return { ok: false, code: 'approval_expired' };
+    await sql `DELETE FROM slotlock.reservations WHERE status = 'held' AND holder_ref = ${`approval:${id}`}`;
+    return { ok: true, approval: toApproval(row) };
+}
+/** Mark a granted approval, in the transaction that made its write: the second half. */
+export async function finishApprovalGrant(sql, tenantRef, id, decidedBy) {
+    const [row] = await sql `
+    UPDATE slotlock.approvals
+       SET status = 'granted', decided_by = ${decidedBy}, decided_at = statement_timestamp()
+     WHERE tenant_ref = ${tenantRef} AND id = ${id} AND status = 'pending'
+     RETURNING ${sql.unsafe(APPROVAL_COLUMNS)}`;
+    if (!row)
+        throw new Error('slotlock: approval grant found no pending approval');
+    const approval = toApproval(row);
+    await noteApproval(sql, tenantRef, 'approval.granted', approval);
+    return approval;
+}
+/** Decline a pending approval: its holds go, and the feed says so. */
+export async function declineApproval(sql, params) {
+    if (!UUID.test(params.id))
+        return { ok: false, code: 'approval_not_found' };
+    const [row] = await sql `
+    SELECT ${sql.unsafe(APPROVAL_COLUMNS)} FROM slotlock.approvals
+     WHERE tenant_ref = ${params.tenantRef} AND id = ${params.id} FOR UPDATE`;
+    if (!row)
+        return { ok: false, code: 'approval_not_found' };
+    if (row.status !== 'pending')
+        return { ok: false, code: 'approval_not_pending' };
+    await sql `DELETE FROM slotlock.reservations WHERE status = 'held' AND holder_ref = ${`approval:${params.id}`}`;
+    const [declined] = await sql `
+    UPDATE slotlock.approvals
+       SET status = 'declined', decided_by = ${params.decidedBy}, decided_at = statement_timestamp(),
+           reason = ${params.reason ?? null}
+     WHERE id = ${params.id}
+     RETURNING ${sql.unsafe(APPROVAL_COLUMNS)}`;
+    const approval = toApproval(declined);
+    await noteApproval(sql, params.tenantRef, 'approval.declined', approval);
+    return { ok: true, approval };
+}
+/** Maintenance: pending approvals past their wait expire, their holds go. How many did. */
+export async function expireApprovals(sql, tenantRef, limit) {
+    const rows = await sql `
+    UPDATE slotlock.approvals
+       SET status = 'expired', decided_by = 'slotlock:maintenance', decided_at = statement_timestamp()
+     WHERE id IN (
+       SELECT id FROM slotlock.approvals
+        WHERE tenant_ref = ${tenantRef} AND status = 'pending' AND expires_at <= statement_timestamp()
+        ORDER BY expires_at, id LIMIT ${limit} FOR UPDATE SKIP LOCKED)
+     RETURNING ${sql.unsafe(APPROVAL_COLUMNS)}`;
+    for (const row of rows) {
+        await sql `DELETE FROM slotlock.reservations WHERE status = 'held' AND holder_ref = ${`approval:${row.id}`}`;
+        await noteApproval(sql, tenantRef, 'approval.expired', toApproval(row));
+    }
+    return rows.length;
+}

package/assistant.d.ts

@@ -21,6 +21,8 @@ export declare const SLOTLOCK_ASSISTANT_MAX_MESSAGE = 2000;
 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;
+/** Previous secrets a deployment may keep while keys are sealed again under its current one. */
+export declare const SLOTLOCK_ASSISTANT_MAX_PREVIOUS_SECRETS = 3;
 /** 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 @anthropic-ai/sdk 1.3.0 sends (read from its source 2026-10-28). */
@@ -87,6 +89,12 @@ export interface SlotlockAssistantStore {
         saved: boolean;
     }>;
     deleteSettings(tenantRef: string, actor?: string): Promise<boolean>;
+    /**
+     * Replace the sealed key `from` with `to` (the same key under the current secret) only while `from`
+     * is the one stored (store.ts resealAssistantKey). Without it, a key sealed under a previous secret
+     * still opens, and is opened that way each time.
+     */
+    resealKey?(tenantRef: string, from: string, to: 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
@@ -106,6 +114,15 @@ export declare function createSlotlockAssistantStore(store: SlotlockStore): Slot
 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, tried with each secret in turn (the current one first, then
+ * SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS), and which one opened it: 0 for the current secret. Null when
+ * none of them sealed it for this tenant.
+ */
+export declare function openSlotlockAssistantKeyWithAny(secrets: readonly string[], tenantRef: string, sealed: string): Promise<{
+    apiKey: string;
+    secretIndex: number;
+} | null>;
 /** 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>;
 /**
@@ -177,6 +194,29 @@ interface ModelRequest {
 }
 /** One model call. Throws SlotlockAssistantProviderError, whose message never holds the key. */
 export declare function callSlotlockAssistantModel(request: ModelRequest): Promise<SlotlockAssistantModelTurn>;
+/**
+ * Providers the Settings form fills in (RFC 0003 A4): each one's API and the base URL it documents
+ * for it. Custom fills nothing, for any other OpenAI-compatible API. Choosing one saves nothing.
+ */
+export declare const SLOTLOCK_ASSISTANT_PRESETS: readonly {
+    id: string;
+    name: string;
+    provider: SlotlockAssistantProvider;
+    baseUrl: string;
+}[];
+/**
+ * The models a provider offers (`GET /v1/models` on the Anthropic API, `GET /models` on an
+ * OpenAI-compatible one, listed under `data` or as a bare array), by id, sorted, for the Settings
+ * form's Model field. Throws
+ * SlotlockAssistantProviderError as a model call does, never with the key in its message.
+ */
+export declare function listSlotlockAssistantModels(args: {
+    provider: SlotlockAssistantProvider;
+    baseUrl: string;
+    apiKey: string | null;
+    fetch: typeof fetch;
+    timeoutMs: number;
+}): Promise<string[]>;
 /**
  * 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.

package/assistant.js

@@ -34,6 +34,9 @@ export const SLOTLOCK_ASSISTANT_TOOL_USE = Object.freeze({
     slotlock_create_event: 'propose',
     slotlock_update_event: 'propose',
     slotlock_delete_event: 'propose',
+    slotlock_confirm_slot: 'propose',
+    slotlock_reschedule: 'propose',
+    slotlock_cancel: 'propose',
 });
 for (const [operation, use] of Object.entries(SLOTLOCK_ASSISTANT_TOOL_USE)) {
     // A read the assistant runs freely must be one the agent server calls a read.
@@ -56,6 +59,8 @@ export const SLOTLOCK_ASSISTANT_MAX_STORED_BYTES = 160_000;
 const MAX_ACTIONS_BYTES = 80_000;
 /** UTF-8 bytes of one proposed change's arguments as JSON; a larger one is not proposed. */
 export const SLOTLOCK_ASSISTANT_MAX_ACTION_BYTES = 16_000;
+/** Previous secrets a deployment may keep while keys are sealed again under its current one. */
+export const SLOTLOCK_ASSISTANT_MAX_PREVIOUS_SECRETS = 3;
 /** Proposed changes one conversation may have waiting at once (4 of the largest fit the bound). */
 export const SLOTLOCK_ASSISTANT_MAX_PENDING = 4;
 /** Characters of one tool result the model is shown. */
@@ -80,6 +85,7 @@ export function createSlotlockAssistantStore(store) {
             ...(actor !== undefined ? { updatedBy: actor } : {}),
         }), by(actor)),
         deleteSettings: (tenantRef, actor) => store.withTenant(tenantRef, (tenant) => tenant.deleteAssistantSettings({ tenantRef }), by(actor)),
+        resealKey: (tenantRef, from, to) => store.withTenant(tenantRef, (tenant) => tenant.resealAssistantKey({ tenantRef, from, to }), by(undefined)),
         // Each read deletes the tenant's expired conversations first, for deployments whose maintenance
         // never meets the tenant (a Worker's).
         getConversation: (tenantRef, memberRef) => store.withTenant(tenantRef, async (tenant) => {
@@ -133,6 +139,13 @@ export function createSlotlockMemoryAssistantStore(now = Date.now) {
         async deleteSettings(tenantRef) {
             return settings.delete(tenantRef);
         },
+        async resealKey(tenantRef, from, to) {
+            const stored = settings.get(tenantRef);
+            if (!stored || stored.sealedKey !== from || to.length === 0 || to === from)
+                return false;
+            settings.set(tenantRef, { ...stored, sealedKey: to });
+            return true;
+        },
         async getConversation(tenantRef, memberRef) {
             const found = live(tenantRef, memberRef);
             if (!found)
@@ -198,6 +211,19 @@ export async function sealSlotlockAssistantKey(secret, tenantRef, apiKey) {
     const sealed = await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: boundTo(tenantRef) }, await sealingKey(secret), encoder.encode(apiKey));
     return `${SEAL_VERSION}.${Buffer.from(iv).toString('base64url')}.${Buffer.from(sealed).toString('base64url')}`;
 }
+/**
+ * The key a seal holds, tried with each secret in turn (the current one first, then
+ * SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS), and which one opened it: 0 for the current secret. Null when
+ * none of them sealed it for this tenant.
+ */
+export async function openSlotlockAssistantKeyWithAny(secrets, tenantRef, sealed) {
+    for (const [secretIndex, secret] of secrets.entries()) {
+        const apiKey = await openSlotlockAssistantKey(secret, tenantRef, sealed);
+        if (apiKey !== null)
+            return { apiKey, secretIndex };
+    }
+    return null;
+}
 /** The key a seal holds, or null when it is not one this secret sealed for this tenant. */
 export async function openSlotlockAssistantKey(secret, tenantRef, sealed) {
     const [version, iv, body, ...rest] = sealed.split('.');
@@ -547,6 +573,95 @@ export async function callSlotlockAssistantModel(request) {
     const turn = anthropic ? readAnthropic(body) : readOpenai(body);
     return { text: turn.text.slice(0, MAX_MODEL_TEXT), calls: turn.calls };
 }
+/**
+ * Providers the Settings form fills in (RFC 0003 A4): each one's API and the base URL it documents
+ * for it. Custom fills nothing, for any other OpenAI-compatible API. Choosing one saves nothing.
+ */
+export const SLOTLOCK_ASSISTANT_PRESETS = Object.freeze([
+    { id: 'anthropic', name: 'Anthropic', provider: 'anthropic', baseUrl: 'https://api.anthropic.com' },
+    { id: 'openai', name: 'OpenAI', provider: 'openai', baseUrl: 'https://api.openai.com/v1' },
+    { id: 'openrouter', name: 'OpenRouter', provider: 'openai', baseUrl: 'https://openrouter.ai/api/v1' },
+    {
+        id: 'google',
+        name: 'Google',
+        provider: 'openai',
+        baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai',
+    },
+    { id: 'mistral', name: 'Mistral', provider: 'openai', baseUrl: 'https://api.mistral.ai/v1' },
+    { id: 'groq', name: 'Groq', provider: 'openai', baseUrl: 'https://api.groq.com/openai/v1' },
+    { id: 'together', name: 'Together', provider: 'openai', baseUrl: 'https://api.together.xyz/v1' },
+    { id: 'custom', name: 'Custom', provider: 'openai', baseUrl: '' },
+]);
+/** Models one list keeps: a provider may offer hundreds. */
+const MAX_LISTED_MODELS = 500;
+/**
+ * The models a provider offers (`GET /v1/models` on the Anthropic API, `GET /models` on an
+ * OpenAI-compatible one, listed under `data` or as a bare array), by id, sorted, for the Settings
+ * form's Model field. Throws
+ * SlotlockAssistantProviderError as a model call does, never with the key in its message.
+ */
+export async function listSlotlockAssistantModels(args) {
+    const anthropic = args.provider === 'anthropic';
+    const headers = { accept: 'application/json', 'user-agent': 'slotlock-dashboard-assistant' };
+    if (anthropic) {
+        headers['anthropic-version'] = SLOTLOCK_ANTHROPIC_VERSION;
+        if (args.apiKey)
+            headers['x-api-key'] = args.apiKey;
+    }
+    else if (args.apiKey) {
+        headers.authorization = `Bearer ${args.apiKey}`;
+    }
+    const signal = AbortSignal.timeout(args.timeoutMs);
+    let response;
+    try {
+        response = await args.fetch(anthropic ? `${args.baseUrl}/v1/models?limit=1000` : `${args.baseUrl}/models`, {
+            method: 'GET',
+            headers,
+            // Never follow a redirect: it would carry the key elsewhere.
+            redirect: 'manual',
+            signal,
+        });
+    }
+    catch (error) {
+        const name = error?.name;
+        if (error?.code === 'private_address') {
+            throw new SlotlockAssistantProviderError('private_address');
+        }
+        throw new SlotlockAssistantProviderError(name === 'TimeoutError' || name === 'AbortError' || signal.aborted ? 'timeout' : 'unavailable');
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => undefined);
+        const status = response.status;
+        throw new SlotlockAssistantProviderError(status === 401 || status === 403
+            ? 'refused_key'
+            : status === 404
+                ? 'not_found'
+                : status === 429
+                    ? 'rate_limited'
+                    : 'unavailable', status);
+    }
+    let body;
+    try {
+        body = JSON.parse(await readBounded(response));
+    }
+    catch (error) {
+        if (error instanceof SlotlockAssistantProviderError)
+            throw error;
+        throw new SlotlockAssistantProviderError(signal.aborted ? 'timeout' : 'bad_answer');
+    }
+    // `{ data: [...] }` as OpenAI and Anthropic answer, or the bare array some OpenAI-compatible
+    // providers (Together) answer instead.
+    const listed = Array.isArray(body) ? body : isRecord(body) && Array.isArray(body.data) ? body.data : null;
+    if (!listed)
+        throw new SlotlockAssistantProviderError('bad_answer');
+    const ids = new Set();
+    for (const entry of listed) {
+        const id = isRecord(entry) ? entry.id : undefined;
+        if (typeof id === 'string' && SLOTLOCK_ASSISTANT_MODEL_NAME.test(id))
+            ids.add(id);
+    }
+    return [...ids].sort().slice(0, MAX_LISTED_MODELS);
+}
 /**
  * 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.