rift-ds 1.7.0 → 1.9.0

package/chat/types.d.ts

@@ -0,0 +1,246 @@
+import { ReactNode } from 'react';
+import { AttachmentItem } from '../components/Attachment/fileTypes';
+/**
+ * Rich content that can cross a network: a kind the host knows how to draw
+ * and the data to draw it from. The provider's `renderers` map turns one
+ * into a React node when the turn renders. A tool can answer with one from
+ * the server handler, and a script can attach one to a reply.
+ */
+export interface ChatCard {
+    /** The renderer key, e.g. "chart" or "plan". Unknown kinds render nothing. */
+    kind: string;
+    /** Whatever the renderer for `kind` expects. Must survive JSON. */
+    data: unknown;
+}
+/**
+ * Something the chat made that is worth more room than a turn can give it: a
+ * dashboard, a document, a page, a site. It travels as an ordinary card of
+ * kind `ARTIFACT_CARD_KIND`, so any transport that can send a card can send
+ * one; the thread draws it as a tile, and the tile opens the artifact panel
+ * beside the conversation.
+ */
+export interface ChatArtifact {
+    /** Stable identity: the same id reopened is the same artifact. */
+    id: string;
+    /** The artifact's name, on the tile and in the panel's header. */
+    title: string;
+    /**
+     * How to draw it. `html` frames the `html` document, `url` frames the
+     * `url`, `code` shows the `code` alone; any other kind is drawn by the
+     * provider's `artifactRenderers`. An unknown kind with no renderer falls
+     * back to whichever of `html`, `url` and `code` it carries.
+     */
+    kind: string;
+    /** A quiet line beside the name: what it is, or which version. */
+    meta?: string;
+    /** A Material Symbol name for the tile and the header. */
+    icon?: string;
+    /** A complete HTML document, drawn in a sandboxed frame. */
+    html?: string;
+    /** A page to frame. Only http(s) URLs and same-site paths are framed. */
+    url?: string;
+    /** The source, offered as the panel's Code view. An `html` artifact offers its document when this is absent. */
+    code?: string;
+    /** The source's language. */
+    language?: string;
+    /** Whatever a custom renderer for `kind` expects. Must survive JSON. */
+    data?: unknown;
+}
+/** The card kind an artifact travels as. Its `data` is a `ChatArtifact`. */
+export declare const ARTIFACT_CARD_KIND = "artifact";
+export type ChatEvent = 
+/** A live status step: the AgentStatus label, with an optional reasoning trace point. */
+{
+    type: 'status';
+    label: string;
+    point?: string;
+}
+/** The model serving this exchange, as a display label ("Sonnet 5").
+    The server's per-answer ground truth; kept in state but not rendered
+    by the widget today, whose picker follows the `models` offer event. */
+ | {
+    type: 'model';
+    label: string;
+}
+/** What the server is offering right now: the wire value it defaults to,
+    and any values the day's budget has locked out. The picker follows
+    this: the server owns the default and the lock, the client only
+    expresses a preference. */
+ | {
+    type: 'models';
+    default: string;
+    locked: string[];
+}
+/** A chunk of response text. The first delta ends the thinking phase. */
+ | {
+    type: 'delta';
+    text: string;
+}
+/** The server-side log id for this exchange. Feedback references it, so a
+    thumbs verdict can be joined back to the logged question and answer.
+    A transport that never sends one hides the thumbs, which is what a
+    script does. */
+ | {
+    type: 'exchange';
+    id: string;
+}
+/** Follow-up questions to offer under the finished answer. A transport that
+    can produce them yields this before `done`; the fetch transport cannot
+    (they are written from the completed answer, so waiting for them would
+    hold the turn open) and the provider fetches them after the turn
+    commits instead. */
+ | {
+    type: 'followups';
+    items: string[];
+}
+/** Rich content to render with the committed turn, as a React node. Only
+    an in-browser transport can yield one (a script, or `injectTurn`); the
+    network form is `card`. */
+ | {
+    type: 'content';
+    node: ReactNode;
+}
+/** Rich content to render with the committed turn, as serialisable data
+    the provider's `renderers` draw. The form a server can send. */
+ | {
+    type: 'card';
+    card: ChatCard;
+}
+/** Terminal: the response is complete. */
+ | {
+    type: 'done';
+}
+/** A guardrail response (rate limit, circuit breaker): rendered as a normal assistant message. */
+ | {
+    type: 'notice';
+    text: string;
+}
+/** A failure the user should see, phrased for humans. */
+ | {
+    type: 'error';
+    message: string;
+};
+/** Every event kind, for documentation that enumerates the protocol. */
+export declare const CHAT_EVENT_KINDS: readonly ["status", "model", "models", "delta", "exchange", "followups", "content", "card", "done", "notice", "error"];
+export interface ChatTransportMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    /**
+     * What was attached to a user message: names and kinds, never bytes. The
+     * scripted transport reads it to answer about the files. The fetch
+     * transport drops it before the request is built, so nothing about an
+     * attachment reaches the server.
+     */
+    attachments?: {
+        name: string;
+        kind: AttachmentItem['kind'];
+        size?: number;
+    }[];
+}
+/**
+ * A transport streams events for one exchange. Abort the signal to stop it.
+ *
+ * Contract notes for implementations:
+ * - The consumer `break`s out of its `for await` loop on `done` (and on
+ *   abort), which invokes the iterator's `return()`: close any underlying
+ *   reader or connection in a `try/finally`.
+ * - Check the signal between yields; the consumer also guards its own loop,
+ *   but a transport that ignores abort keeps its own work running.
+ * - There is no first-event timeout on the consumer side: a transport that
+ *   can hang before its first yield should implement its own watchdog.
+ */
+export type ChatTransport = (messages: ChatTransportMessage[], signal: AbortSignal) => AsyncIterable<ChatEvent>;
+/** One committed turn. Assistant turns keep their reasoning for the collapsed disclosure. */
+export interface ChatTurn {
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+    /** Reasoning trace points gathered while the response was live (assistant turns). */
+    tracePoints?: string[];
+    /** Seconds spent before the first response text (assistant turns). */
+    durationSeconds?: number;
+    /** The server's log id for the exchange, absent on scripted and placeholder turns. */
+    exchangeId?: string;
+    /** The visitor's thumbs verdict on this turn, kept for the session only. */
+    feedback?: 'up' | 'down';
+    /**
+     * Follow-up questions offered under this answer. Undefined means none have
+     * been asked for yet; an empty array means they were and none came back,
+     * which is what stops a failed attempt being retried on every render.
+     */
+    followups?: string[];
+    /**
+     * Files sent with a user turn, drawn above its bubble. Their picture
+     * previews are object URLs the hook owns from the moment of the send:
+     * they are revoked on reset and on unmount.
+     */
+    attachments?: AttachmentItem[];
+    /**
+     * Rich content rendered with the turn as a React node: a tool call, a
+     * card. Set by `injectTurn` or carried from a transport's `content` event.
+     * Assistant turns render it between the reasoning and the prose; user
+     * turns stack it above the bubble, like an attachment.
+     */
+    content?: ReactNode;
+    /**
+     * Rich content rendered with the turn through the provider's `renderers`,
+     * carried from a transport's `card` event. Drawn where `content` is.
+     */
+    card?: ChatCard;
+    /**
+     * Render `content` on its own in the thread, outside any message chrome,
+     * for conversation furniture like a day marker.
+     */
+    bare?: boolean;
+}
+export type LivePhase = 'thinking' | 'streaming';
+/** The assistant turn currently in flight, rendered after the committed turns. */
+export interface LiveResponse {
+    /**
+     * The turn's stable id, minted at send time and kept when the turn
+     * commits, so the rendered element keeps its identity and React
+     * reconciles the finished response in place instead of remounting it.
+     */
+    id: string;
+    phase: LivePhase;
+    /** Current AgentStatus label while thinking. */
+    statusLabel: string;
+    tracePoints: string[];
+    text: string;
+    durationSeconds?: number;
+    /** Carried from the transport's `exchange` event into the committed turn. */
+    exchangeId?: string;
+    /** Carried from the transport's `followups` event into the committed turn. */
+    followups?: string[];
+    /** Carried from the transport's `content` event into the committed turn. */
+    content?: ReactNode;
+    /** Carried from the transport's `card` event into the committed turn. */
+    card?: ChatCard;
+}
+/**
+ * One model the widget can offer in its picker and the server handler can
+ * serve. Shared by both halves so the wire value the client sends is one the
+ * server knows.
+ */
+export interface ChatModelOption {
+    /** Stable wire value: what the picker holds and the client sends. */
+    value: string;
+    /** The provider's model id the server calls. */
+    id: string;
+    /** Display name in the picker. */
+    label: string;
+    /** One line under the name in the picker. */
+    description: string;
+    /**
+     * Whether the model takes adaptive thinking and the effort dial. A model
+     * that predates them rejects both, so the handler sends it a plain request.
+     */
+    adaptiveThinking: boolean;
+}
+/** One conversation starter on the welcome screen. */
+export interface Starter {
+    id: string;
+    label: string;
+}
+/** The thumbs verdict a visitor can give an answer. */
+export type ChatFeedbackVerdict = 'up' | 'down';

package/chat/types.js

@@ -0,0 +1,18 @@
+const ARTIFACT_CARD_KIND = "artifact";
+const CHAT_EVENT_KINDS = [
+  "status",
+  "model",
+  "models",
+  "delta",
+  "exchange",
+  "followups",
+  "content",
+  "card",
+  "done",
+  "notice",
+  "error"
+];
+export {
+  ARTIFACT_CARD_KIND,
+  CHAT_EVENT_KINDS
+};

package/chat/upstash.d.ts

@@ -0,0 +1,63 @@
+import { ChatGuardrails } from './server';
+/** List prices in USD per million tokens for one model id. */
+export interface PriceRow {
+    input: number;
+    output: number;
+    /** Cache writes; 2x input for a 1-hour cache TTL, 1.25x for the default. */
+    cacheWrite: number;
+    cacheRead: number;
+}
+/**
+ * The built-in price table, keyed by model id. Over-estimating trips the
+ * breaker early, which is the safe direction to be wrong in; real billing
+ * comes from the provider's console. An unknown id prices at `fallbackPrice`.
+ */
+export declare const DEFAULT_PRICES: Record<string, PriceRow>;
+export interface UpstashGuardrailsCopy {
+    /** Too many messages in a minute. */
+    burst: string;
+    /** The per-visitor daily limit. */
+    daily: string;
+    /** The site-wide breaker. */
+    paused: string;
+}
+export declare const DEFAULT_GUARDRAILS_COPY: UpstashGuardrailsCopy;
+export interface UpstashGuardrailsOptions {
+    /** The Upstash REST URL. Missing means every check fails open. */
+    url?: string;
+    /** The Upstash REST token. */
+    token?: string;
+    /** Salts the hashed visitor address. Set it: an unsalted hash over the IPv4 space is reversible. */
+    salt?: string;
+    /** Redis key prefix, so several chats can share one database. */
+    prefix?: string;
+    /** Messages per visitor per minute. */
+    perMinute?: number;
+    /** Messages per visitor per day. */
+    perDay?: number;
+    /** Follow-up requests per visitor per minute. */
+    followupsPerMinute?: number;
+    /** Feedback posts per visitor per minute. */
+    feedbackPerMinute?: number;
+    /** The site-wide daily message cap. */
+    dailyMessageCap?: number;
+    /** The site-wide daily spend cap, in US cents. */
+    dailySpendCapCents?: number;
+    /** Past this fraction of the spend cap the default model steps down. */
+    stepdownFraction?: number;
+    /** Past this fraction only the budget model serves. */
+    lockFraction?: number;
+    /** Price rows by model id, merged over the built-in table. */
+    prices?: Record<string, PriceRow>;
+    /** The row an unknown model id prices at. Defaults to the dearest built-in row. */
+    fallbackPrice?: PriceRow;
+    /** How long an exchange log line lives, in seconds. */
+    logTtlSeconds?: number;
+    copy?: Partial<UpstashGuardrailsCopy>;
+}
+/**
+ * Guardrails over Upstash Redis: per-visitor rate limits, a daily breaker
+ * with model tiers, the exchange log (30 days by default) and the feedback
+ * store. Pass the result as `guardrails` to all three handlers.
+ */
+export declare function createUpstashGuardrails(options?: UpstashGuardrailsOptions): ChatGuardrails;

package/chat/upstash.js

@@ -0,0 +1,147 @@
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+const DEFAULT_PRICES = {
+  "claude-sonnet-5": { input: 3, output: 15, cacheWrite: 6, cacheRead: 0.3 },
+  "claude-haiku-5-5": { input: 0.5, output: 2.5, cacheWrite: 1, cacheRead: 0.05 }
+};
+const DEFAULT_GUARDRAILS_COPY = {
+  burst: "That is a lot of questions at once. Give it a minute and ask again.",
+  daily: "You have reached the daily limit for this chat. It resets tomorrow.",
+  paused: "This chat has hit its budget for today and is paused until midnight UTC."
+};
+const dayKey = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+const COUNTER_TTL_SECONDS = 60 * 60 * 48;
+async function sha256Hex(text) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createUpstashGuardrails(options = {}) {
+  const prefix = options.prefix ?? "chat";
+  const perMinute = options.perMinute ?? 10;
+  const perDay = options.perDay ?? 60;
+  const followupsPerMinute = options.followupsPerMinute ?? 15;
+  const feedbackPerMinute = options.feedbackPerMinute ?? 30;
+  const dailyMessageCap = options.dailyMessageCap ?? 300;
+  const dailySpendCapTenths = (options.dailySpendCapCents ?? 500) * 10;
+  const stepdownFraction = options.stepdownFraction ?? 0.5;
+  const lockFraction = options.lockFraction ?? 0.85;
+  const prices = { ...DEFAULT_PRICES, ...options.prices };
+  const fallbackPrice = options.fallbackPrice ?? DEFAULT_PRICES["claude-sonnet-5"];
+  const logTtl = options.logTtlSeconds ?? 60 * 60 * 24 * 30;
+  const copy = { ...DEFAULT_GUARDRAILS_COPY, ...options.copy };
+  const salt = options.salt ?? "";
+  let warned = false;
+  const redis = options.url && options.token ? new Redis({ url: options.url, token: options.token }) : null;
+  const getRedis = () => {
+    if (!redis && !warned) {
+      warned = true;
+      console.warn("[chat] Upstash url/token unset: rate limits and the daily breaker are inactive.");
+    }
+    return redis;
+  };
+  const limiter = (instance, name, limit, window) => new Ratelimit({
+    redis: instance,
+    limiter: Ratelimit.slidingWindow(limit, window),
+    prefix: `${prefix}:rl:${name}`,
+    analytics: false
+  });
+  const messagesKey = () => `${prefix}:day:${dayKey()}:messages`;
+  const spendKey = () => `${prefix}:day:${dayKey()}:tenths-cents`;
+  const logKey = () => `${prefix}:log:${dayKey()}`;
+  const feedbackKey = (id) => `${prefix}:feedback:${id}`;
+  const visitorKey = async (request) => {
+    const forwarded = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+    const ip = forwarded || request.headers.get("x-real-ip")?.trim() || "local";
+    return (await sha256Hex(salt + ip)).slice(0, 32);
+  };
+  const ALLOWED = { allowed: true, tier: "open" };
+  const check = async (request) => {
+    const instance = getRedis();
+    if (!instance) return ALLOWED;
+    try {
+      const visitor = await visitorKey(request);
+      const [burst, daily] = await Promise.all([
+        limiter(instance, "burst", perMinute, "60 s").limit(visitor),
+        limiter(instance, "day", perDay, "24 h").limit(visitor)
+      ]);
+      if (!burst.success) return { allowed: false, notice: copy.burst };
+      if (!daily.success) return { allowed: false, notice: copy.daily };
+      const [messages, spendTenths] = await Promise.all([
+        instance.get(messagesKey()),
+        instance.get(spendKey())
+      ]);
+      if ((messages ?? 0) >= dailyMessageCap || (spendTenths ?? 0) >= dailySpendCapTenths) {
+        return { allowed: false, notice: copy.paused };
+      }
+      const count = await instance.incr(messagesKey());
+      if (count === 1) await instance.expire(messagesKey(), COUNTER_TTL_SECONDS);
+      const spentFraction = (spendTenths ?? 0) / dailySpendCapTenths;
+      const tier = spentFraction >= lockFraction ? "locked" : spentFraction >= stepdownFraction ? "reduced" : "open";
+      return { allowed: true, tier };
+    } catch (error) {
+      console.error("[chat] guardrail check failed, allowing the request:", error);
+      return ALLOWED;
+    }
+  };
+  const onUsage = async (usage, modelId) => {
+    const instance = getRedis();
+    if (!instance) return;
+    const price = prices[modelId] ?? fallbackPrice;
+    const usd = ((usage.input_tokens ?? 0) * price.input + (usage.output_tokens ?? 0) * price.output + (usage.cache_creation_input_tokens ?? 0) * price.cacheWrite + (usage.cache_read_input_tokens ?? 0) * price.cacheRead) / 1e6;
+    const tenths = Math.ceil(usd * 1e3);
+    if (tenths <= 0) return;
+    try {
+      const total = await instance.incrby(spendKey(), tenths);
+      if (total === tenths) await instance.expire(spendKey(), COUNTER_TTL_SECONDS);
+    } catch (error) {
+      console.error("[chat] recording spend failed:", error);
+    }
+  };
+  const onExchange = async (entry) => {
+    const instance = getRedis();
+    if (!instance) return;
+    try {
+      const line = JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry });
+      const length = await instance.rpush(logKey(), line);
+      if (length === 1) await instance.expire(logKey(), logTtl);
+    } catch (error) {
+      console.error("[chat] recording exchange failed:", error);
+    }
+  };
+  const perVisitorLimit = (name, limit) => async (request) => {
+    const instance = getRedis();
+    if (!instance) return true;
+    try {
+      const { success } = await limiter(instance, name, limit, "60 s").limit(await visitorKey(request));
+      return success;
+    } catch (error) {
+      console.error(`[chat] ${name} limit check failed, allowing:`, error);
+      return true;
+    }
+  };
+  const onFeedback = async (id, verdict, visitor) => {
+    const instance = getRedis();
+    if (!instance) return;
+    try {
+      await instance.set(feedbackKey(id), JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), verdict, visitor }), {
+        ex: logTtl
+      });
+    } catch (error) {
+      console.error("[chat] recording feedback failed:", error);
+    }
+  };
+  return {
+    check,
+    visitorKey,
+    onUsage,
+    onExchange,
+    checkFollowups: perVisitorLimit("followups", followupsPerMinute),
+    checkFeedback: perVisitorLimit("feedback", feedbackPerMinute),
+    onFeedback
+  };
+}
+export {
+  DEFAULT_GUARDRAILS_COPY,
+  DEFAULT_PRICES,
+  createUpstashGuardrails
+};

package/chat/useChat.d.ts

@@ -0,0 +1,64 @@
+import { ReactNode } from 'react';
+import { AttachmentItem } from '../components/Attachment/fileTypes';
+import { ChatTransport, ChatTurn, LiveResponse } from './types';
+/** The copy the hook shows when a transport ends a turn with nothing to show. */
+export interface ChatPlaceholderCopy {
+    /** A completion that produced no text. */
+    empty: string;
+    /** The reader stopped the response before any text arrived. */
+    stopped: string;
+    /** The transport failed before any text arrived. */
+    failed: string;
+}
+export declare const DEFAULT_PLACEHOLDER_COPY: ChatPlaceholderCopy;
+/** What `useChat` returns: the conversation and the actions that move it. */
+export interface ChatState {
+    /** The committed turns, oldest first. */
+    turns: ChatTurn[];
+    /** The assistant turn in flight, or null between exchanges. */
+    live: LiveResponse | null;
+    /** Whether a response is in flight. */
+    streaming: boolean;
+    /** Display label of the model the transport last reported, null before the first exchange. */
+    modelLabel: string | null;
+    /** The transport's current model offer (default + locked values), null before it first reports. */
+    modelPolicy: {
+        default: string;
+        locked: string[];
+    } | null;
+    /**
+     * Send a message. Returns whether the send was accepted: false while a
+     * response is in flight or for an empty draft, so the caller knows not to
+     * clear its input. Files alone are a whole message, so an empty draft is
+     * accepted when there are some.
+     */
+    send: (text: string, options?: {
+        content?: ReactNode;
+        attachments?: AttachmentItem[];
+    }) => boolean;
+    /** Stop the in-flight response, keeping the text that already arrived. */
+    stop: () => void;
+    /** New chat: abort anything in flight and clear the conversation. */
+    reset: () => void;
+    /**
+     * Append a committed turn directly, bypassing the transport. Injected turns
+     * are stage dressing: they never enter the transport history, so a live
+     * model is never fed words it did not say.
+     */
+    injectTurn: (turn: Omit<ChatTurn, 'id'>) => void;
+    /** Record the visitor's thumbs verdict on a committed turn. State only: the caller tells the server. */
+    setTurnFeedback: (turnId: string, feedback: 'up' | 'down') => void;
+    /**
+     * Attach follow-up questions to a committed turn. State only: the caller
+     * produces them. Writing an empty array records that the attempt was made
+     * and came back with nothing, so it is never repeated for that turn.
+     */
+    setTurnFollowups: (turnId: string, followups: string[]) => void;
+}
+/**
+ * useChat owns the conversation: the committed turns, the assistant turn in
+ * flight, and the phase machine that drives the AgentStatus, Reasoning and
+ * streamed-text choreography. It knows nothing about rendering or about
+ * where events come from; the transport decides that.
+ */
+export declare function useChat(transport: ChatTransport, placeholders?: ChatPlaceholderCopy): ChatState;