@blinkk/root-cms 3.1.2 → 3.1.4

package/dist/core/ai.d.ts

@@ -1,98 +1,26 @@
 import { RootConfig } from '@blinkk/root';
-import { ImageModel, LanguageModel, UIMessage } from 'ai';
-import { Timestamp } from 'firebase-admin/firestore';
-import { RootCMSClient } from './client.js';
-import { Collection } from './schema.js';
+import { AiConfig, AiExecutionMode, AiModelConfig, resolveLanguageModel } from '../shared/ai/models.js';
+import { deriveChatTitle } from '../shared/ai/prompt-utils.js';
+export type { AiConfig, AiExecutionMode, AiModelCapabilities, AiModelConfig, AiProvider, } from '../shared/ai/models.js';
+export { normalizeExecutionMode, resolveImageModel, resolveLanguageModel, withBrowserHeaders, } from '../shared/ai/models.js';
+export { buildTitlePrompt, buildTitlePromptContext, deriveChatTitle, extractJsonFromResponse, mergeIncomingMessage, sanitizeDanglingToolCalls, sanitizeGeneratedTitle, stripUndefined, TITLE_GENERATION_SYSTEM_PROMPT, } from '../shared/ai/prompt-utils.js';
 /** Filename of the project-level instructions file loaded into the AI prompt. */
 export declare const ROOT_MD_FILENAME = "ROOT.md";
-export type AiExecutionMode = 'read' | 'approve' | 'auto';
+/** Default base system prompt for the Root AI chat. */
+export declare const DEFAULT_CHAT_SYSTEM_PROMPT: string;
 /**
- * Provider type for an AI model. Use `openai-compatible` for any OpenAI-style
- * endpoint (e.g. local Ollama, vLLM, OpenRouter).
+ * Strips secrets from `AiConfig` before sending to the browser. Used by the
+ * `/cms/api/ai.config` endpoint and the inlined `window.__ROOT_CTX.ai` to
+ * populate the model picker. The key-bearing connection config is sent
+ * separately (and only for the selected model) via `serializeAiClientModel`.
  */
-export type AiProvider = 'openai' | 'openai-compatible' | 'anthropic' | 'google';
-/**
- * Configuration for a single chat model.
- *
- * Inspired by Ollama's `Modelfile` and LiteLLM's model config: each entry maps
- * a CMS-facing id to a provider, model id and credentials.
- */
-export interface AiModelConfig {
-    /** Stable id used by the CMS UI and stored alongside chat history. */
-    id: string;
-    /** Optional human-readable label rendered in the model picker. */
-    label?: string;
-    /** Optional description shown under the label. */
-    description?: string;
-    /** AI provider/family to route requests to. */
-    provider: AiProvider;
-    /**
-     * Provider-specific model id (e.g. `gpt-4o`, `claude-opus-4-5`,
-     * `gemini-2.5-pro`). Defaults to `id` if omitted.
-     */
-    modelId?: string;
-    /** API key for the provider. */
-    apiKey?: string;
-    /** Override the provider's base URL (required for `openai-compatible`). */
-    baseURL?: string;
-    /** Custom headers to send with each request. */
-    headers?: Record<string, string>;
-    /** Capabilities advertised to the UI. */
-    capabilities?: {
-        /** Whether the model can call tools. Defaults to `true`. */
-        tools?: boolean;
-        /** Whether the model can stream reasoning/thinking. Defaults to `false`. */
-        reasoning?: boolean;
-        /** Whether the model accepts image attachments. Defaults to `false`. */
-        attachments?: boolean;
-    };
-}
-/**
- * Full AI config registered on the cms plugin.
- */
-export interface AiConfig {
-    /** Models exposed in the model picker. The first entry is the default. */
-    models: AiModelConfig[];
-    /** Id of the default model. Defaults to the first model in `models`. */
-    defaultModel?: string;
-    /**
-     * Image generation models. Used by the image generator and any other
-     * features that produce images. Only the `openai` and `google` providers
-     * support image generation.
-     */
-    imageModels?: AiModelConfig[];
-    /** Id of the default image model. Defaults to the first entry in `imageModels`. */
-    defaultImageModel?: string;
-    /**
-     * Optional system prompt prepended to every conversation. If a `ROOT.md`
-     * file exists at the project root, its contents are appended to this
-     * prompt automatically.
-     */
-    systemPrompt?: string;
-    /** Maximum tool-loop steps before stopping. Defaults to 10. */
-    maxSteps?: number;
-}
-interface ChatRecord {
-    id: string;
-    createdBy: string;
-    createdAt: Timestamp;
-    modifiedAt: Timestamp;
-    modelId?: string;
-    title?: string;
-    messages: UIMessage[];
-}
-/** Resolves an `AiModelConfig` to an AI SDK `LanguageModel` instance. */
-export declare function resolveLanguageModel(model: AiModelConfig): LanguageModel;
-/** Resolves an `AiModelConfig` to an AI SDK `ImageModel` instance. */
-export declare function resolveImageModel(model: AiModelConfig): ImageModel;
-/** Strips secrets from `AiConfig` before sending to the browser. */
 export declare function serializeAiConfig(config: AiConfig): {
     defaultModel: string;
     models: {
         id: string;
         label: string;
         description: string | undefined;
-        provider: AiProvider;
+        provider: import("../shared/ai/models.js").AiProvider;
         capabilities: {
             tools: boolean;
             reasoning: boolean;
@@ -101,61 +29,37 @@ export declare function serializeAiConfig(config: AiConfig): {
     }[];
     imageGenerationEnabled: boolean;
 };
+/**
+ * Serializes a single chat model's full connection config — INCLUDING the API
+ * key, base URL and custom headers — for direct browser-to-provider calls.
+ *
+ * Security note: this intentionally exposes the provider API key to the
+ * authenticated CMS client (the project opted into direct client-side calls).
+ * Only return it from authenticated endpoints, and only for the model the user
+ * actually selected.
+ */
+export declare function serializeAiClientModel(model: AiModelConfig): {
+    id: string;
+    label: string;
+    description: string | undefined;
+    provider: import("../shared/ai/models.js").AiProvider;
+    modelId: string;
+    apiKey: string | undefined;
+    baseURL: string | undefined;
+    headers: Record<string, string> | undefined;
+    capabilities: {
+        tools: boolean;
+        reasoning: boolean;
+        attachments: boolean;
+    };
+};
+export type SerializedAiClientModel = ReturnType<typeof serializeAiClientModel>;
 /** Returns the AI config registered on the CMS plugin, or `null`. */
 export declare function getAiConfig(rootConfig: RootConfig): AiConfig | null;
 /** Returns the model config matching `modelId`, or the default model. */
 export declare function findModel(config: AiConfig, modelId?: string): AiModelConfig | null;
 /** Returns the image model config matching `modelId`, or the default image model. */
 export declare function findImageModel(config: AiConfig, modelId?: string): AiModelConfig | null;
-export declare function normalizeExecutionMode(value: unknown): AiExecutionMode;
-/**
- * Persists chat sessions to Firestore so that users can resume past
- * conversations from the chat history sidebar.
- */
-export declare class ChatStore {
-    cmsClient: RootCMSClient;
-    user: string;
-    constructor(cmsClient: RootCMSClient, user: string);
-    collection(): FirebaseFirestore.CollectionReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
-    createChat(options?: {
-        id?: string;
-        modelId?: string;
-    }): Promise<ChatRecord>;
-    getChat(id: string): Promise<ChatRecord | null>;
-    listChats(options?: {
-        limit?: number;
-    }): Promise<ChatRecord[]>;
-    deleteChat(id: string): Promise<void>;
-    updateMessages(id: string, messages: UIMessage[], options?: {
-        modelId?: string;
-        title?: string;
-    }): Promise<void>;
-}
-/**
- * Merges the latest incoming message into the persisted chat history.
- *
- * The client posts only the last message; the server holds the rest in
- * Firestore. After client-side tool execution the SDK resubmits the *same*
- * assistant message — now carrying tool results — under the id it was
- * streamed with. That id already exists in the persisted history (saved by
- * `onFinish` before the results came back), so a naive append would
- * duplicate it: the stored copy still has unresolved tool calls, which
- * convert to `tool_use` blocks with no following `tool_result` and the model
- * provider rejects the request.
- *
- * Replacing the matched entry (and dropping anything after it) keeps message
- * ids unique and the tool-call/result pairing intact. A genuinely new
- * message id is appended as usual.
- */
-export declare function mergeIncomingMessage(stored: UIMessage[], incoming: UIMessage): UIMessage[];
-/**
- * Synthesizes an aborted result for any tool-call part still awaiting one, so
- * every `tool_use` keeps a matching `tool_result` when the history is handed
- * to the model. Left unresolved, such parts (from an abandoned turn) make the
- * provider reject the next request. Returns the original array unchanged when
- * there is nothing to repair.
- */
-export declare function sanitizeDanglingToolCalls(messages: UIMessage[]): UIMessage[];
 /**
  * Reads the project's `ROOT.md` file, if present. Mirrors the convention used
  * by tools like `AGENTS.md` and `CLAUDE.md`: developers can drop a markdown
@@ -173,106 +77,44 @@ export declare function readRootMd(rootDir: string): Promise<string | null>;
  * distinguish it from the framework-provided instructions.
  */
 export declare function buildSystemPrompt(basePrompt: string, rootMd: string | null): string;
-/** Derives a short title from the first user message (used as fallback). */
-export declare function deriveChatTitle(messages: UIMessage[]): string;
-/**
- * Extracts the first user turn and first assistant text turn as a plain-text
- * transcript, suitable for the title-generation prompt. Skips tool-call
- * parts, reasoning chunks, and attachments so the model sees the
- * conversational substance and nothing else.
- *
- * Only the opening exchange is included on purpose — the chat title should
- * describe what the conversation is *about*, anchored on the user's initial
- * ask, not drift as later follow-ups arrive.
- */
-export declare function buildTitlePromptContext(messages: UIMessage[]): string;
-/**
- * Strips the cruft LLMs commonly emit around a title — leading "Title:"
- * preamble, surrounding quotes, trailing punctuation, internal newlines —
- * and enforces a hard length cap.
- */
-export declare function sanitizeGeneratedTitle(raw: string): string;
 /**
- * Uses the AI model to generate a short summary title for the chat. The
- * prompt is anchored on the user's initial question (and, if available, the
- * assistant's first reply) so the title captures *intent and topic* rather
- * than echoing the first line verbatim.
+ * Uses the AI model to generate a short summary title for a chat. Kept for
+ * server-side callers; the browser chat generates titles client-side using the
+ * shared `TITLE_GENERATION_SYSTEM_PROMPT` + `buildTitlePrompt` helpers.
  *
  * Falls back to `deriveChatTitle` if the generation fails or returns an
  * empty result.
  */
-export declare function generateChatTitle(model: LanguageModel, messages: UIMessage[]): Promise<string>;
-export interface RunChatStreamOptions {
+export declare function generateChatTitle(model: ReturnType<typeof resolveLanguageModel>, messages: Parameters<typeof deriveChatTitle>[0]): Promise<string>;
+export declare function buildExecutionModePrompt(mode: AiExecutionMode): string;
+export interface BuildChatSystemPromptOptions {
     rootConfig: RootConfig;
-    cmsClient: RootCMSClient;
     config: AiConfig;
-    model: AiModelConfig;
-    messages: UIMessage[];
-    chatId: string;
-    user: string;
-    executionMode?: AiExecutionMode;
-    /**
-     * Title already saved on this chat. When non-empty the server will NOT
-     * regenerate it on this turn — titles are derived once, on the first
-     * assistant response, so they describe the original ask instead of
-     * thrashing as follow-up messages arrive.
-     */
-    existingTitle?: string;
+    executionMode: AiExecutionMode;
     /**
      * When set, tells the model which document the user is currently viewing
      * in the CMS UI so phrases like "this document" can be resolved.
      */
     activeDocId?: string;
-    /**
-     * Loads a single collection's schema. The caller owns dev-vs-prod schema
-     * resolution (Vite SSR vs. prebuilt `dist/collections/*.json`).
-     */
-    loadCollection: (collectionId: string) => Promise<Collection | null>;
-    /** Loads every project collection keyed by id. */
-    loadAllCollections: () => Promise<Record<string, Collection>>;
 }
-export declare function buildExecutionModePrompt(mode: AiExecutionMode): string;
 /**
- * Builds a streaming response that proxies the model's UI message stream
- * directly to the client. Persists the final message list to Firestore once
- * the stream finishes.
+ * Assembles the chat system prompt: base prompt + workspace context + tool
+ * safety policy + execution-mode workflow + (optional) active-doc context,
+ * with `ROOT.md` appended when present.
  */
-export declare function runChatStream(options: RunChatStreamOptions): Promise<Response>;
-export interface RunEditObjectStreamOptions {
+export declare function buildChatSystemPrompt(options: BuildChatSystemPromptOptions): Promise<string>;
+export interface BuildEditSystemPromptOptions {
     rootConfig: RootConfig;
-    cmsClient: RootCMSClient;
-    user: string;
-    config: AiConfig;
-    model: AiModelConfig;
-    messages: UIMessage[];
     /** The JSON object the user is editing. Injected as context for the model. */
     editData: unknown;
-    loadCollection: (collectionId: string) => Promise<Collection | null>;
-    loadAllCollections: () => Promise<Record<string, Collection>>;
 }
 /**
- * Streaming variant used by the array-item "Edit with AI" diff-viewer flow.
- *
- * Differences from `runChatStream`:
- *
- * - Uses an edit-specific system prompt that injects the JSON the user is
- *   editing and the project's `root-cms.d.ts` types, and instructs the model
- *   to end every response with a fenced ```json block containing the
- *   complete proposed new JSON. The client extracts that block to populate
- *   the diff viewer.
- * - Tools are filtered to read-only (see `createReadOnlyCmsTools`). The user
- *   approves changes via the modal's "Save" button, so the model must not
- *   mutate Firestore directly.
- * - No Firestore persistence — edit sessions are ephemeral and don't show up
- *   in the user's chat history.
- */
-export declare function runEditObjectStream(options: RunEditObjectStreamOptions): Promise<Response>;
-/**
- * Recursively removes `undefined` values from an object/array. Returns a new
- * structure; the input is not mutated. Used to clean payloads before sending
- * them to Firestore, which rejects `undefined` outright.
+ * Assembles the system prompt for the array-item "Edit with AI" diff-viewer
+ * flow: the edit instructions + output-format contract + read-only tool policy
+ * + the project's `root-cms.d.ts` types + the JSON being edited (wrapped as
+ * untrusted data), with `ROOT.md` appended when present.
  */
-export declare function stripUndefined<T>(value: T): T;
+export declare function buildEditSystemPrompt(options: BuildEditSystemPromptOptions): Promise<string>;
 export interface SummarizeDiffOptions {
     before: Record<string, any> | null;
     after: Record<string, any> | null;
@@ -322,9 +164,3 @@ export interface GenerateImageResult {
  * to storage.
  */
 export declare function generateImage(rootConfig: RootConfig, options: GenerateImageOptions): Promise<GenerateImageResult>;
-/**
- * Extracts JSON from an AI response that may contain markdown code blocks.
- * @internal
- */
-export declare function extractJsonFromResponse(responseText: string): string;
-export {};

package/dist/core/plugin.d.ts

@@ -182,11 +182,17 @@ export type CMSPluginOptions = {
     onAction?: (action: Action) => any;
     /**
      * Configures the Root CMS AI chat (`/cms/ai`). Provide one or more models
-     * — the CMS proxies user requests directly to the configured providers.
+     * — each entry declares the provider, model id and credentials. The shape
+     * mirrors open source tools like Ollama and LiteLLM.
      *
-     * The shape mirrors open source tools like Ollama and LiteLLM: each entry
-     * declares the provider, model id and credentials. Keys live on the server,
-     * never on the client.
+     * IMPORTANT: the streaming chat (`/cms/ai`, the document-editor AI panel and
+     * the "Edit with AI" modal) calls the provider DIRECTLY from the browser —
+     * SSE proxying through the server did not work on App Engine / Firebase
+     * Hosting. The selected model's API key is therefore delivered to the
+     * authenticated CMS client. Use keys scoped/billed for this trusted,
+     * signed-in audience. The one-shot helpers (diff summaries, publish
+     * messages, translations, alt text, image generation) still run server-side,
+     * so their keys stay on the server.
      *
      * Example:
      * ```ts

package/dist/functions.js

@@ -1,7 +1,6 @@
 import {
   runCronJobs
-} from "./chunk-AJDMNTZQ.js";
-import "./chunk-4VZTYUQ7.js";
+} from "./chunk-NC3CRIFA.js";
 import "./chunk-AFBSITEO.js";
 import "./chunk-J72JK4KR.js";
 import "./chunk-MLKGABMK.js";