@perxel/spotlight 0.0.0-stage → 0.1.1

package/dist/server/handler.d.ts

@@ -0,0 +1,102 @@
+import { type LanguageModel } from "ai";
+import type { AskContext, AskSource, Cited, ToolRun } from "./types.js";
+/**
+ * `createAskHandler(options)`: a Web-standard `(Request) => Promise<Response>` that answers a chat
+ * from the AI SDK's `useChat` (the whole conversation in each request) with a streamed UI message
+ * response. Mount it as a Next route handler (`export const POST = handler`), a Worker's `fetch`,
+ * Hono, Node. Stateless: the history comes from the client and only its text is used (tool
+ * parts and sources from the client are dropped, so a client cannot hand the model tool results).
+ *
+ * Checks, in order: CORS origin (when `origins` is set) → method and size → body shape and limits
+ * → `verify` (bot check) → `rateLimit` → the model call. A refusal is `{code}` JSON with an HTTP
+ * status; the panel maps the code to its copy.
+ */
+export type AskErrorCode = "origin" | "bad_request" | "verify_failed" | "rate_limited" | "conversation_limit" | "budget" | "config" | "upstream";
+/**
+ * A model error's code: `config` when the route is set up wrong (no API key, or the provider
+ * refused it: 401/403), so the visitor is not told to try again and the log says what to fix;
+ * `upstream` for the rest (provider down, timeout).
+ */
+export declare function modelErrorCode(err: unknown): "config" | "upstream";
+/** One answered turn, for `onFinish` (log it, store it, count its cost). */
+export interface AskTurn {
+    /** The chat id the client sent (`useChat`'s id), if any. */
+    id: string | null;
+    question: string;
+    answer: string;
+    /** Every tool the model ran this turn, in order. */
+    tools: ToolRun[];
+    /** The sources sent to the client. */
+    sources: Cited[];
+    /** Number of messages in the conversation, this question included. */
+    messages: number;
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    timing: {
+        totalMs: number;
+        /** Until the first answer text, -1 when none. */
+        firstTextMs: number;
+        /** Model time (step time minus tool time). */
+        modelMs: number;
+        toolMs: number;
+        steps: number;
+    };
+    /** The AI SDK's end event, for what is not lifted out above (provider metadata, cost). */
+    raw: unknown;
+}
+export interface AskHandlerOptions {
+    /** Any AI SDK language model, or one per request. */
+    model: LanguageModel | ((ctx: AskContext) => LanguageModel);
+    /** Instructions for the model; a function gets the request context (locale in the body, say). */
+    system?: string | ((ctx: AskContext) => string | Promise<string>);
+    /** Where the model's tools come from: `contentSource`, `toolSource`, `mcpSource`, mixed freely. */
+    sources?: AskSource[];
+    /** Allowlist of tool names the model may call (after prefixing); all when omitted. */
+    tools?: string[];
+    /**
+     * Tools that only drive the interface (an action, a handoff): not counted as lookups, and their
+     * results are never searched for sources.
+     */
+    uiTools?: string[];
+    /** Bot check: true to go on, false (or an error code) to refuse. `turnstile({secret})` is one. */
+    verify?: (ctx: AskContext) => boolean | string | Promise<boolean | string>;
+    /** Rate limit or budget: true to go on, false (`rate_limited`) or an error code to refuse. */
+    rateLimit?: (ctx: AskContext) => boolean | string | Promise<boolean | string>;
+    /** After each answered turn. Runs after the response has finished streaming. */
+    onFinish?: (turn: AskTurn, ctx: AskContext) => void | Promise<void>;
+    /** Keeps `onFinish` alive past the response on platforms that need it (a Worker's `ctx.waitUntil`). */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /** Allowed `Origin`s for cross-origin calls (CORS); same-origin only when omitted. */
+    origins?: string[];
+    /** Headers on every answer (a session, a version). */
+    headers?: (ctx: AskContext) => HeadersInit | undefined | Promise<HeadersInit | undefined>;
+    /** Cite sources: `{url, title}` pairs found in tool results become `source-url` parts. Default on, 4 at most, 2 per tool result. */
+    cite?: false | {
+        max?: number;
+        perResult?: number;
+    };
+    /** Characters in the visitor's question (default 1000). */
+    maxInputChars?: number;
+    /** Questions in one conversation (default 20); more is `conversation_limit`. */
+    maxQuestions?: number;
+    /** Earlier messages kept for the model (default 20, the newest). */
+    maxHistory?: number;
+    /** Characters kept per earlier message (default 4000). */
+    maxHistoryChars?: number;
+    /** Model steps per answer, tool calls included (default 4). */
+    maxSteps?: number;
+    /** Output tokens per answer (default 700). */
+    maxOutputTokens?: number;
+    /** Request body bytes (default 256 KB). */
+    maxBodyBytes?: number;
+    /** Called with errors (model, tool, `onFinish`); default `console.error`, with a hint when the model has no key or it was refused. */
+    onError?: (error: unknown, where: "model" | "tool" | "finish") => void;
+    /** Extra `streamText` settings (temperature, providerOptions…). */
+    settings?: Record<string, unknown>;
+}
+/** Every `{url, title}` pair in a tool result, in order (urls: http(s) or a path). Bounded walk. */
+export declare function sourcesIn(data: unknown, limit?: number): Cited[];
+export declare function createAskHandler(options: AskHandlerOptions): (request: Request) => Promise<Response>;

package/dist/server/handler.js

@@ -0,0 +1,274 @@
+import { createUIMessageStream, createUIMessageStreamResponse, isStepCount, streamText, toUIMessageStream, } from "ai";
+const STATUS = {
+    origin: 403,
+    bad_request: 400,
+    verify_failed: 403,
+    rate_limited: 429,
+    conversation_limit: 429,
+    budget: 503,
+    config: 503,
+    upstream: 502,
+};
+/**
+ * A model error's code: `config` when the route is set up wrong (no API key, or the provider
+ * refused it: 401/403), so the visitor is not told to try again and the log says what to fix;
+ * `upstream` for the rest (provider down, timeout).
+ */
+export function modelErrorCode(err) {
+    let e = err;
+    // A retried call fails with the last attempt's error inside.
+    if (e?.name === "AI_RetryError" && e.lastError)
+        e = e.lastError;
+    if (e?.name === "AI_LoadAPIKeyError")
+        return "config";
+    if (e?.name === "AI_APICallError" && (e.statusCode === 401 || e.statusCode === 403))
+        return "config";
+    return "upstream";
+}
+function logError(err, where) {
+    if (where === "model" && modelErrorCode(err) === "config")
+        console.error(`[spotlight] model: the AI provider has no API key or refused it. Check the key the route's model is created with (an empty Worker secret or env var is a common cause).`, err);
+    else
+        console.error(`[spotlight] ${where}:`, err);
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** The text of a client message: its text parts joined. */
+function messageText(m) {
+    if (!Array.isArray(m.parts))
+        return typeof m.content === "string" ? m.content : "";
+    return m.parts
+        .filter((p) => isRecord(p) && p.type === "text" && typeof p.text === "string")
+        .map((p) => p.text)
+        .join("\n")
+        .trim();
+}
+function cors(res, origin) {
+    if (!origin)
+        return res;
+    const headers = new Headers(res.headers);
+    headers.set("access-control-allow-origin", origin);
+    headers.set("access-control-expose-headers", "*");
+    headers.append("vary", "Origin");
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+/** Every `{url, title}` pair in a tool result, in order (urls: http(s) or a path). Bounded walk. */
+export function sourcesIn(data, limit = 50) {
+    const out = [];
+    const queue = [data];
+    let seen = 0;
+    while (queue.length && seen < 500 && out.length < limit) {
+        const node = queue.shift();
+        seen++;
+        if (Array.isArray(node))
+            queue.push(...node);
+        else if (isRecord(node)) {
+            const { url, title } = node;
+            if (typeof url === "string" && /^(https?:\/\/|\/)/.test(url) && typeof title === "string" && title.trim() && !out.some((o) => o.url === url)) {
+                out.push({ url, title: title.trim() });
+            }
+            for (const v of Object.values(node))
+                if (typeof v === "object" && v !== null)
+                    queue.push(v);
+        }
+    }
+    return out;
+}
+export function createAskHandler(options) {
+    const { sources = [], uiTools = [], maxInputChars = 1000, maxQuestions = 20, maxHistory = 20, maxHistoryChars = 4000, maxSteps = 4, maxOutputTokens = 700, maxBodyBytes = 256 * 1024, onError = logError, } = options;
+    const cite = options.cite === false ? null : { max: options.cite?.max ?? 4, perResult: options.cite?.perResult ?? 2 };
+    const ui = new Set(uiTools);
+    return async function handle(request) {
+        const t0 = Date.now();
+        const requestOrigin = request.headers.get("origin");
+        const sameOrigin = !requestOrigin || requestOrigin === new URL(request.url).origin;
+        const allowed = !sameOrigin && requestOrigin && options.origins?.includes(requestOrigin) ? requestOrigin : null;
+        const refuse = (code, headers) => cors(Response.json({ code }, { status: STATUS[code], headers }), allowed);
+        if (request.method === "OPTIONS") {
+            if (!allowed)
+                return new Response(null, { status: 403 });
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    "access-control-allow-origin": allowed,
+                    "access-control-allow-methods": "POST, OPTIONS",
+                    "access-control-allow-headers": request.headers.get("access-control-request-headers") ?? "content-type",
+                    "access-control-max-age": "86400",
+                    vary: "Origin",
+                },
+            });
+        }
+        if (!sameOrigin && !allowed)
+            return refuse("origin");
+        if (request.method !== "POST")
+            return refuse("bad_request");
+        // Body: size, JSON, messages.
+        if (Number(request.headers.get("content-length") ?? 0) > maxBodyBytes)
+            return refuse("bad_request");
+        const raw = await request.text().catch(() => "");
+        if (!raw || raw.length > maxBodyBytes)
+            return refuse("bad_request");
+        let body;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!isRecord(parsed))
+                return refuse("bad_request");
+            body = parsed;
+        }
+        catch {
+            return refuse("bad_request");
+        }
+        const list = Array.isArray(body.messages) ? body.messages.filter(isRecord) : [];
+        const turns = list
+            .filter((m) => m.role === "user" || m.role === "assistant")
+            .map((m) => ({ role: m.role, text: messageText(m) }))
+            .filter((m) => m.text);
+        const last = turns.at(-1);
+        if (!last || last.role !== "user" || last.text.length > maxInputChars)
+            return refuse("bad_request");
+        if (turns.filter((m) => m.role === "user").length > maxQuestions)
+            return refuse("conversation_limit");
+        const { messages: _messages, ...fields } = body;
+        const ctx = {
+            request,
+            body: fields,
+            id: typeof body.id === "string" ? body.id.slice(0, 100) : null,
+            question: last.text,
+            history: turns.slice(0, -1),
+        };
+        const verified = options.verify ? await options.verify(ctx) : true;
+        if (verified !== true)
+            return refuse(typeof verified === "string" ? verified : "verify_failed");
+        const limited = options.rateLimit ? await options.rateLimit(ctx) : true;
+        if (limited !== true)
+            return refuse(typeof limited === "string" ? limited : "rate_limited", { "retry-after": "60" });
+        // A model factory that throws (a missing key checked by the site) refuses with `config`.
+        let model;
+        try {
+            model = typeof options.model === "function" ? options.model(ctx) : options.model;
+        }
+        catch (err) {
+            onError(err, "model");
+            return refuse("config");
+        }
+        const system = typeof options.system === "function" ? await options.system(ctx) : options.system;
+        const history = turns
+            .slice(0, -1)
+            .slice(-maxHistory)
+            .map((m) => ({ role: m.role, content: m.text.slice(0, maxHistoryChars) }));
+        const runs = [];
+        const cited = [];
+        let firstTextMs = -1;
+        const stream = createUIMessageStream({
+            execute: async ({ writer }) => {
+                // Tools from every source; a name taken by an earlier source gets the source's prefix.
+                const tools = {};
+                const taken = new Set();
+                for (const source of sources) {
+                    let set;
+                    try {
+                        set = await source.tools(ctx);
+                    }
+                    catch (err) {
+                        onError(err, "tool");
+                        continue;
+                    }
+                    for (const [name, t] of Object.entries(set)) {
+                        const key = taken.has(name) ? `${source.name}_${name}` : name;
+                        taken.add(key);
+                        if (options.tools && !options.tools.includes(key))
+                            continue;
+                        tools[key] = wrapTool(key, t, (run, result) => {
+                            runs.push(run);
+                            if (!cite || ui.has(key) || !run.ok)
+                                return;
+                            for (const s of sourcesIn(result, cite.perResult)) {
+                                if (cited.length >= cite.max || cited.some((c) => c.url === s.url))
+                                    continue;
+                                cited.push(s);
+                                writer.write({ type: "source-url", sourceId: s.url, url: s.url, title: s.title });
+                            }
+                        }, (err) => onError(err, "tool"));
+                    }
+                }
+                const result = streamText({
+                    ...options.settings,
+                    model,
+                    ...(system ? { instructions: system } : {}),
+                    messages: [...history, { role: "user", content: ctx.question }],
+                    tools,
+                    stopWhen: isStepCount(maxSteps),
+                    maxOutputTokens,
+                    maxRetries: 1,
+                    onChunk: ({ chunk }) => {
+                        if (firstTextMs < 0 && chunk.type === "text-delta")
+                            firstTextMs = Date.now() - t0;
+                    },
+                    onEnd: (event) => {
+                        if (!options.onFinish)
+                            return;
+                        let modelMs = 0;
+                        let toolMs = 0;
+                        for (const s of event.steps) {
+                            const tools = Object.values(s.performance?.toolExecutionMs ?? {}).reduce((a, b) => a + b, 0);
+                            modelMs += Math.max(0, (s.performance?.stepTimeMs ?? 0) - tools);
+                            toolMs += tools;
+                        }
+                        const turn = {
+                            id: ctx.id,
+                            question: ctx.question,
+                            answer: event.text,
+                            tools: runs,
+                            sources: cited,
+                            messages: turns.length,
+                            model: event.response?.modelId ?? "",
+                            usage: { inputTokens: event.totalUsage.inputTokens ?? 0, outputTokens: event.totalUsage.outputTokens ?? 0 },
+                            timing: { totalMs: Date.now() - t0, firstTextMs, modelMs: Math.round(modelMs), toolMs: Math.round(toolMs), steps: event.steps.length },
+                            raw: event,
+                        };
+                        const done = Promise.resolve()
+                            .then(() => options.onFinish(turn, ctx))
+                            .catch((err) => onError(err, "finish"));
+                        options.waitUntil?.(done);
+                    },
+                });
+                writer.merge(toUIMessageStream({
+                    stream: result.stream,
+                    onError: (err) => {
+                        onError(err, "model");
+                        return modelErrorCode(err);
+                    },
+                }));
+            },
+            onError: (err) => {
+                onError(err, "model");
+                return modelErrorCode(err);
+            },
+        });
+        const headers = options.headers ? await options.headers(ctx) : undefined;
+        return cors(createUIMessageStreamResponse({ stream, ...(headers ? { headers } : {}) }), allowed);
+    };
+}
+/** The tool with its runs recorded; a thrown error becomes `{error}` for the model, not a failed turn. */
+function wrapTool(name, t, done, onError) {
+    if (!t.execute)
+        return t;
+    const execute = t.execute;
+    return {
+        ...t,
+        execute: async (input, opts) => {
+            const start = Date.now();
+            try {
+                const result = await execute(input, opts);
+                done({ name, ms: Date.now() - start, ok: true, input }, result);
+                return result;
+            }
+            catch (err) {
+                onError(err);
+                done({ name, ms: Date.now() - start, ok: false, input }, null);
+                return { error: err instanceof Error ? err.message : "The tool failed." };
+            }
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,4 @@
+export { createAskHandler, modelErrorCode, sourcesIn, type AskErrorCode, type AskHandlerOptions, type AskTurn } from "./handler.js";
+export { contentSource, mcpSource, toolSource, passagesOf, sectionOf, resetMcpCache, type ContentDoc, type ContentSourceOptions, type McpSourceOptions } from "./sources.js";
+export { turnstile, type TurnstileOptions } from "./turnstile.js";
+export type { AskContext, AskSource, Cited, ToolRun } from "./types.js";

package/dist/server/index.js

@@ -0,0 +1,5 @@
+// `@perxel/spotlight/server`: an optional chat endpoint for Ask. Web-standard (`Request` →
+// `Response`), any AI SDK model, tools from the site's pages, its own functions or a remote MCP.
+export { createAskHandler, modelErrorCode, sourcesIn } from "./handler.js";
+export { contentSource, mcpSource, toolSource, passagesOf, sectionOf, resetMcpCache } from "./sources.js";
+export { turnstile } from "./turnstile.js";

package/dist/server/sources.d.ts

@@ -0,0 +1,79 @@
+import { type ToolSet } from "ai";
+import { type SearchDoc } from "../core/search.js";
+import type { AskContext, AskSource } from "./types.js";
+/**
+ * The site's own AI SDK tools (live numbers, filters over structured data, an outside API), run
+ * in the same route. A function gets the request context (locale, say) and returns the tools.
+ */
+export declare function toolSource(tools: ToolSet | ((ctx: AskContext) => ToolSet | Promise<ToolSet>), { name }?: {
+    name?: string;
+}): AskSource;
+/** A page for `contentSource`: a search document, with its full text if there is one. */
+export type ContentDoc = SearchDoc & {
+    body?: string;
+};
+export interface ContentSourceOptions {
+    /** The pages: the same documents as search (with a `url`), or a function of the request (locale). */
+    docs: ContentDoc[] | ((ctx: AskContext) => ContentDoc[] | Promise<ContentDoc[]>);
+    /** Full text by document id, when it is not on the documents (`body`). Markdown headings (`#`) mark sections. */
+    bodies?: Record<string, string> | ((ctx: AskContext) => Record<string, string> | Promise<Record<string, string>>);
+    /** Makes relative urls absolute in what the model sees (and in the cited sources). */
+    baseUrl?: string;
+    /** Hits per search (default 5). */
+    maxHits?: number;
+    /** Passages per hit, from its full text (default 2), and their length in characters (default 320). */
+    passages?: number;
+    passageLength?: number;
+    /** Characters of a page `get_page` returns (default 6000); longer pages are cut and list their sections. */
+    pageLength?: number;
+    /** Tool names (default `search_site`, `get_page`). */
+    names?: {
+        search?: string;
+        page?: string;
+    };
+    /** What the tools say they search ("this site's pages"). */
+    about?: string;
+    name?: string;
+}
+/** Up to `count` paragraphs of `body` holding the most terms, each cut around its first match. */
+export declare function passagesOf(body: string, words: string[], count: number, length: number): string[];
+/**
+ * The section of a body under the heading that matches `section`: a markdown heading (until the
+ * next one of its level or higher), else, for plain text where headings became their own lines,
+ * a short heading-like line (until the next one).
+ */
+export declare function sectionOf(body: string, section: string): string | null;
+/**
+ * Search and read the site's own pages, with no MCP: two tools built from the same documents as
+ * the gate's search plus their full text. Answers stay cheap: a search returns a few short
+ * passages per hit (most answers need nothing more), a page is capped or read one section at a
+ * time.
+ */
+export declare function contentSource(options: ContentSourceOptions): AskSource;
+export interface McpSourceOptions {
+    /** The server's MCP endpoint (streamable HTTP), e.g. `https://mcp.example.com/mcp`. */
+    url: string;
+    /** Headers on every call (an API key). A function runs per request. */
+    headers?: Record<string, string> | ((ctx: AskContext) => Record<string, string> | Promise<Record<string, string>>);
+    /** Allowlist of the server's tool names to offer. Recommended: a tool added to the server later is not offered by accident. */
+    tools?: string[];
+    /**
+     * Arguments set by the site, hidden from the model: e.g. `{locale: ctx.body.locale}` for a tool
+     * whose input has a `locale`. Only applied to tools whose schema has that property.
+     */
+    fixed?: (ctx: AskContext) => Record<string, unknown>;
+    /** How long the tool list is kept (per server instance, default 5 minutes). */
+    listTtlMs?: number;
+    /** Per call (default 15 s). */
+    timeoutMs?: number;
+    name?: string;
+    fetcher?: typeof fetch;
+}
+/**
+ * Tools on a remote MCP server, called over streamable HTTP with no SDK (works on any runtime
+ * with `fetch`). The tool list is fetched once and kept for `listTtlMs`. Use `tools` to allowlist:
+ * an anonymous chat must only reach tools meant for the public.
+ */
+export declare function mcpSource(options: McpSourceOptions): AskSource;
+/** Test hook: forget the cached tool lists and sessions. */
+export declare function resetMcpCache(): void;