rift-ds 1.7.0 → 1.9.0

package/chat/server.d.ts

@@ -0,0 +1,217 @@
+import { default as Anthropic } from '@anthropic-ai/sdk';
+import { ChatCard, ChatFeedbackVerdict, ChatModelOption } from './types';
+/** What a tool hands back: text for the model, and optionally a card for the visitor. */
+export interface ChatToolResult {
+    /** The tool result the model reads. */
+    text: string;
+    /** Rich content streamed to the widget as a `card` event, drawn by the provider's renderers. */
+    card?: ChatCard;
+}
+/** One deterministic tool the model may call. */
+export interface ChatTool {
+    /** The Anthropic tool definition: name, description, input schema. */
+    definition: Anthropic.Messages.Tool;
+    /** Runs the tool. Return a string for the model, or a result with a card for the visitor too. Never throw for bad input: return an error string the model can recover from. */
+    execute: (input: Record<string, unknown>) => string | ChatToolResult | Promise<string | ChatToolResult>;
+    /** The trace point shown while the round runs, e.g. "Checked the Button prop contract". */
+    tracePoint?: (input: Record<string, unknown>) => string;
+}
+/**
+ * How much of the day's budget remains, as a model policy: `open` means the
+ * default model serves, `reduced` means the budget model is the default (the
+ * better one stays selectable), `locked` means only the budget model serves.
+ */
+export type ModelTier = 'open' | 'reduced' | 'locked';
+export type GuardrailVerdict = {
+    allowed: true;
+    tier: ModelTier;
+} | {
+    allowed: false;
+    notice: string;
+};
+/** Anthropic's usage block, narrowed to the fields a spend estimate needs. */
+export interface TokenUsage {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+}
+/** One logged exchange: what was asked, what came back, and the numbers. */
+export interface ExchangeLog {
+    /** Minted per request and streamed to the widget, so a feedback verdict can be joined back to this line. */
+    id: string;
+    question: string;
+    answer: string;
+    /** The sanitised context the request carried, or null. */
+    path: string | null;
+    /** The model id that served, absent on guardrail notices. */
+    model?: string;
+    usage?: TokenUsage;
+    /** Milliseconds from request to the stream closing. */
+    latencyMs: number;
+    /** Milliseconds to the first response text, what the visitor feels. */
+    firstTextMs: number | null;
+    /** True when the answer is a guardrail notice, not a model response. */
+    notice: boolean;
+    /** The opaque per-visitor key. */
+    visitor: string;
+}
+/**
+ * The hooks the handlers call around a request. Every member is optional
+ * and every one fails open: a missing hook means no limit, no log, no
+ * tiering. `rift-ds/chat/upstash` implements the set over Redis.
+ */
+export interface ChatGuardrails {
+    /** Rate limits and the daily breaker. Return a notice to answer with instead of calling the model. */
+    check?: (request: Request) => Promise<GuardrailVerdict>;
+    /** A stable, opaque key for the visitor (a salted hash, never an address). */
+    visitorKey?: (request: Request) => Promise<string> | string;
+    /** Called with the real token counts after every model call. */
+    onUsage?: (usage: TokenUsage, modelId: string) => Promise<void>;
+    /** Called once per exchange. Its presence is what makes the handler stream an `exchange` id, and so what shows the thumbs. */
+    onExchange?: (entry: ExchangeLog) => Promise<void>;
+    /** Per-visitor limit for the follow-ups handler. */
+    checkFollowups?: (request: Request) => Promise<boolean>;
+    /** Per-visitor limit for the feedback handler. */
+    checkFeedback?: (request: Request) => Promise<boolean>;
+    /** Stores one verdict per exchange id. */
+    onFeedback?: (exchangeId: string, verdict: ChatFeedbackVerdict, visitor: string) => Promise<void>;
+}
+export interface ChatLimits {
+    /** Turns kept from the client's history. Older context is dropped. */
+    maxTurns: number;
+    /** Longest single message accepted, in characters. */
+    maxMessageChars: number;
+    /** Longest whole conversation accepted, summed across every kept turn. */
+    maxTotalChars: number;
+    /** Hard ceiling on the raw request body, rejected before it is parsed. */
+    maxBodyChars: number;
+    /** Trace points shown under the status label before the rest is dropped. */
+    maxTracePoints: number;
+}
+export declare const DEFAULT_CHAT_LIMITS: ChatLimits;
+export interface ChatHandlerCopy {
+    /** The reply when the chat is switched off or unconfigured. */
+    disabled: string;
+    /** The reply to a message over `maxMessageChars`. */
+    tooLong: string;
+    /** The reply when the model refuses and nothing was streamed. */
+    refusal: string;
+    /** Appended when the answer hit the token cap. */
+    cutOff: string;
+    /** The first status label, proving the stream opened. */
+    reading: string;
+    /** The status label while thinking. */
+    thinking: string;
+    /** The status label while a tool round runs. */
+    lookingUp: string;
+    /** The error for a busy or overloaded model. */
+    busy: string;
+    /** The error for a rejected key. */
+    unauthorised: string;
+    /** The error for anything else before the first text. */
+    failed: string;
+}
+export declare const DEFAULT_CHAT_COPY: ChatHandlerCopy;
+export type SystemBlocks = Anthropic.Messages.TextBlockParam[];
+export interface ChatHandlerOptions {
+    /** An Anthropic client to reuse, or `apiKey` to build one from. */
+    client?: Anthropic;
+    apiKey?: string;
+    /** The off switch. Defaults to whether a client or key is present. */
+    enabled?: boolean;
+    /**
+     * The system prompt, as blocks. A string is one block; a function builds
+     * them per request from the sanitised context. Put `cache_control` on the
+     * block that holds your corpus, and nothing volatile before it.
+     */
+    system: string | SystemBlocks | ((context: {
+        path: string | null;
+    }) => string | SystemBlocks);
+    /**
+     * An uncached trailing block built from the request's context, after the
+     * cache breakpoint. Defaults to naming the page; return null for none.
+     */
+    contextBlock?: (path: string) => string | null;
+    /** The models on offer. The client sends a `value`; the handler calls the matching `id`. */
+    models: ChatModelOption[];
+    /** The wire value that serves when the budget has headroom and the visitor has not chosen. Defaults to the first model. */
+    defaultModel?: string;
+    /** The wire value that serves once the budget steps down, and the only one past the lock. Defaults to `defaultModel`. */
+    budgetModel?: string;
+    tools?: ChatTool[];
+    /** Model calls per exchange: the first pass plus tool rounds. The last allowed pass withholds the tools. */
+    maxModelCalls?: number;
+    /** Caps thinking and response text together. */
+    maxTokens?: number;
+    /** Adaptive thinking's effort dial, for models that take it. */
+    effort?: 'low' | 'medium' | 'high';
+    guardrails?: ChatGuardrails;
+    limits?: Partial<ChatLimits>;
+    copy?: Partial<ChatHandlerCopy>;
+    /** Turns the request's raw `path` into context, or null to drop it. The default accepts lowercase slug paths only. */
+    sanitiseContext?: (value: unknown) => string | null;
+    /** Keeps a fire-and-forget promise alive on platforms that end work with the response. */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * The request's context, sanitised as untrusted input: it lands in a system
+ * block, a stronger position than the user turn. Lowercase slug segments
+ * only, capped short; nothing expressible in that alphabet can carry an
+ * instruction. Anything else is dropped, never rejected.
+ */
+export declare function sanitisePath(value: unknown): string | null;
+/**
+ * The chat handler: `(request) => Response`, streaming NDJSON `ChatEvent`s.
+ */
+export declare function createChatHandler(options: ChatHandlerOptions): (request: Request) => Promise<Response>;
+export interface FollowupsHandlerOptions {
+    client?: Anthropic;
+    apiKey?: string;
+    enabled?: boolean;
+    /** The model id that writes the questions. A small one: the job is three short lines. */
+    model: string;
+    /**
+     * What the chat is about, in a phrase the prompt can use: "the Acme
+     * workspace app and its documentation". Ignored when `system` is given.
+     */
+    about?: string;
+    /** A complete system prompt, replacing the built-in one. */
+    system?: string;
+    /** Example questions in the voice wanted, shown to the model. */
+    examples?: string[];
+    guardrails?: Pick<ChatGuardrails, 'checkFollowups' | 'onUsage'>;
+    /** Chips shown. */
+    wanted?: number;
+    /** Candidates asked for, so a few long ones still leave a full row. */
+    candidates?: number;
+    /** Cap on the upstream call, inside the widget's own wait. */
+    timeoutMs?: number;
+}
+/** The built-in follow-ups prompt. */
+export declare function followupsSystemPrompt({ about, candidates, examples, }: {
+    about: string;
+    candidates: number;
+    examples: string[];
+}): string;
+/**
+ * The model's lines to the chips that are safe to show: plain text, one
+ * short question each, no duplicates, at most `wanted`. Anything that does
+ * not fit the shape is dropped rather than repaired.
+ */
+export declare function parseFollowups(text: string, wanted?: number): string[];
+/**
+ * The follow-ups handler: POST `{ question, answer }`, respond
+ * `{ suggestions: string[] }`, empty on every failure. A second call rather
+ * than part of the answer's stream, because the questions are written from
+ * the completed answer.
+ */
+export declare function createFollowupsHandler(options: FollowupsHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * The feedback handler: POST `{ id, verdict }`, respond 204. The id is never
+ * trusted to exist; a verdict for an id no exchange used is a write nothing
+ * will join against, so validation is a shape check, not a lookup.
+ */
+export declare function createFeedbackHandler(options?: {
+    guardrails?: Pick<ChatGuardrails, 'checkFeedback' | 'onFeedback' | 'visitorKey'>;
+}): (request: Request) => Promise<Response>;