slotlock 0.5.1 → 0.5.3

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 {};