@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/chat/vision-alt-generator.d.ts

@@ -0,0 +1,35 @@
+export interface VisionAltLogger {
+    warn?: (obj: object, msg: string) => void;
+}
+/**
+ * For inline "Generate alt text" / "Improve accessibility" / "Make more descriptive"
+ * wand actions on imageAlt fields. Bypasses the heavy planner (which routinely returns
+ * needs_clarification when the existing alt text looks like a user instruction or is
+ * empty) and asks the vision model directly for one clean alt-text string.
+ *
+ * Provider preference order: anthropic → openai. Falls back to the other if the
+ * preferred provider's API key is missing or the call fails. Returns null only
+ * when both providers fail or no API key is set anywhere.
+ */
+export declare function generateAltTextFromVision(opts: {
+    imageUrl: string;
+    preferredProvider: "anthropic" | "openai" | "gemini";
+    log?: VisionAltLogger;
+}): Promise<string | null>;
+/**
+ * Parse an editablePath into an op shape. Supports two cases:
+ *   - "imageAlt"                   → update_props { imageAlt: alt }
+ *   - "cards[0].imageAlt"          → update_item  cards index 0 { imageAlt: alt }
+ *
+ * Returns null when the path doesn't match either shape — callers should fall
+ * back to the planner.
+ */
+export declare function parseAltPathForOp(path: string): {
+    kind: "props";
+    key: string;
+} | {
+    kind: "item";
+    listKey: string;
+    index: number;
+    itemKey: string;
+} | null;

package/dist/chat/vision-alt-generator.js

@@ -0,0 +1,152 @@
+import Anthropic from "@anthropic-ai/sdk";
+import OpenAI from "openai";
+import { looksLikeUserInstruction } from "./chat-pipeline-ui.js";
+const MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp"
+};
+function resolveImageFetchUrl(rawUrl) {
+    if (/^https?:\/\//i.test(rawUrl))
+        return rawUrl;
+    if (rawUrl.startsWith("/")) {
+        const origin = (process.env.ORCHESTRATOR_PUBLIC_ORIGIN ?? "http://localhost:4200").replace(/\/+$/, "");
+        return `${origin}${rawUrl}`;
+    }
+    return null;
+}
+async function fetchImageBytes(url) {
+    const resolved = resolveImageFetchUrl(url);
+    if (!resolved)
+        return null;
+    try {
+        const res = await fetch(resolved);
+        if (!res.ok)
+            return null;
+        const buffer = Buffer.from(await res.arrayBuffer());
+        const contentType = res.headers.get("content-type");
+        let mediaType = contentType?.split(";")[0]?.trim() ?? "";
+        if (!mediaType || mediaType === "application/octet-stream") {
+            const ext = resolved.match(/(\.[a-z]+)(?:\?|$)/i)?.[1]?.toLowerCase() ?? "";
+            mediaType = MIME_BY_EXT[ext] ?? "image/jpeg";
+        }
+        return { base64: buffer.toString("base64"), mediaType };
+    }
+    catch {
+        return null;
+    }
+}
+const ALT_PROMPT = "Write a 1-2 sentence noun-phrase description of this image suitable as accessibility alt text. " +
+    "Be specific about the main subject, action, and setting. " +
+    "Do not start with 'image of', 'photo of', or 'a/an '. " +
+    "Do not mention 'AI-generated', watermarks, or metadata. " +
+    "Reply with only the alt text — no quotes, no preamble, no labels.";
+/**
+ * For inline "Generate alt text" / "Improve accessibility" / "Make more descriptive"
+ * wand actions on imageAlt fields. Bypasses the heavy planner (which routinely returns
+ * needs_clarification when the existing alt text looks like a user instruction or is
+ * empty) and asks the vision model directly for one clean alt-text string.
+ *
+ * Provider preference order: anthropic → openai. Falls back to the other if the
+ * preferred provider's API key is missing or the call fails. Returns null only
+ * when both providers fail or no API key is set anywhere.
+ */
+export async function generateAltTextFromVision(opts) {
+    const img = await fetchImageBytes(opts.imageUrl);
+    if (!img) {
+        opts.log?.warn?.({ imageUrl: opts.imageUrl }, "vision alt-text: failed to fetch image bytes");
+        return null;
+    }
+    const order = opts.preferredProvider === "openai" ? ["openai", "anthropic"] : ["anthropic", "openai"];
+    for (const provider of order) {
+        const text = await tryProvider(provider, img, opts.log);
+        if (text) {
+            const sanitized = sanitizeAltText(text);
+            if (sanitized && !looksLikeUserInstruction(sanitized))
+                return sanitized;
+        }
+    }
+    return null;
+}
+async function tryProvider(provider, img, log) {
+    try {
+        if (provider === "anthropic") {
+            if (!process.env.ANTHROPIC_API_KEY)
+                return null;
+            const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+            const model = process.env.ANTHROPIC_VISION_ALT_MODEL?.trim() || "claude-haiku-4-5-20251001";
+            const result = await client.messages.create({
+                model,
+                max_tokens: 250,
+                messages: [
+                    {
+                        role: "user",
+                        content: [
+                            {
+                                type: "image",
+                                source: {
+                                    type: "base64",
+                                    media_type: img.mediaType,
+                                    data: img.base64
+                                }
+                            },
+                            { type: "text", text: ALT_PROMPT }
+                        ]
+                    }
+                ]
+            });
+            const textBlock = result.content.find((c) => c.type === "text");
+            return textBlock && textBlock.type === "text" ? textBlock.text : null;
+        }
+        if (!process.env.OPENAI_API_KEY)
+            return null;
+        const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+        const model = process.env.OPENAI_VISION_ALT_MODEL?.trim() || process.env.OPENAI_VISION_MODEL?.trim() || "gpt-4o-mini";
+        const dataUrl = `data:${img.mediaType};base64,${img.base64}`;
+        const completion = await client.chat.completions.create({
+            model,
+            max_tokens: 250,
+            messages: [
+                {
+                    role: "user",
+                    content: [
+                        { type: "text", text: ALT_PROMPT },
+                        { type: "image_url", image_url: { url: dataUrl } }
+                    ]
+                }
+            ]
+        });
+        return completion.choices[0]?.message?.content ?? null;
+    }
+    catch (err) {
+        log?.warn?.({ provider, err: err instanceof Error ? err.message : String(err) }, "vision alt-text direct call failed");
+        return null;
+    }
+}
+function sanitizeAltText(raw) {
+    return raw
+        .trim()
+        .replace(/^["'`“‘]+|["'`”’]+$/g, "")
+        .replace(/^(alt(\s+text)?\s*[:\-—]\s*)/i, "")
+        .trim();
+}
+/**
+ * Parse an editablePath into an op shape. Supports two cases:
+ *   - "imageAlt"                   → update_props { imageAlt: alt }
+ *   - "cards[0].imageAlt"          → update_item  cards index 0 { imageAlt: alt }
+ *
+ * Returns null when the path doesn't match either shape — callers should fall
+ * back to the planner.
+ */
+export function parseAltPathForOp(path) {
+    const nested = path.match(/^(\w+)\[(\d+)\]\.(\w+)$/);
+    if (nested) {
+        const [, listKey, indexStr, itemKey] = nested;
+        return { kind: "item", listKey, index: Number(indexStr), itemKey };
+    }
+    if (/^\w+$/.test(path))
+        return { kind: "props", key: path };
+    return null;
+}

package/dist/cms/adapter.d.ts

@@ -0,0 +1,62 @@
+import type { PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
+/**
+ * A single inline image asset attached to a publish call. Used for
+ * chat-generated images that live as base64 blobs (no public URL yet) — the
+ * adapter is responsible for uploading these to its content store and
+ * swapping the original blob URLs for the resulting public URLs.
+ */
+export interface CmsInlineAsset {
+    /** base64-encoded image bytes */
+    data: string;
+    /** MIME type, e.g. "image/png" */
+    mimeType: string;
+    /** Original filename */
+    fileName: string;
+}
+/**
+ * Extra context passed to `onPublish` alongside the page list. Optional —
+ * adapters that don't care about inline assets can ignore it.
+ */
+export interface CmsPublishContext {
+    /**
+     * Inline assets keyed by their placeholder URL inside the PageDoc[]
+     * (typically a `blob:` or `localhost` URL the adapter wouldn't be able to
+     * fetch). The adapter should upload each one, replace the placeholder URL
+     * in block props, and emit the resulting public URL.
+     */
+    assets?: Record<string, CmsInlineAsset>;
+}
+/**
+ * Result of an `onPublish` call. `void` means "success, nothing to report";
+ * an explicit `{ ok: false, error }` lets the adapter surface a per-publish
+ * error message that the orchestrator returns to the client.
+ */
+export type CmsPublishResult = void | {
+    ok: true;
+} | {
+    ok: false;
+    error?: string;
+};
+export interface CmsAdapter {
+    /**
+     * Stable identifier for telemetry and per-adapter bootstrap caches.
+     * Keep it short and DNS-safe: `json-file`, `editor-api`, `sanity`, etc.
+     */
+    readonly id: string;
+    /**
+     * Return every page the orchestrator should know about for this site.
+     * Called lazily on the first chat for a fresh session. Failures are
+     * logged but non-fatal — the session simply starts empty.
+     */
+    getPages(): Promise<PageDoc[]>;
+    /**
+     * Optional publish hook. If present, called when the editor publishes
+     * a session's draft. If absent, publish remains a no-op against the
+     * external store — SQLite still records the publish locally.
+     *
+     * Second arg carries the session's current SiteConfig (navLabels, theme
+     * overrides, etc.); third arg carries any inline image blobs the editor
+     * collected during the session.
+     */
+    onPublish?(pages: PageDoc[], config: SiteConfig, context?: CmsPublishContext): Promise<CmsPublishResult>;
+}

package/dist/cms/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/cms/bootstrap.d.ts

@@ -0,0 +1,17 @@
+import type { CmsAdapter } from "./adapter.ts";
+import type { Logger } from "../logger.ts";
+export interface CmsBootstrapCacheOptions {
+    /** Soft cap on remembered "already-attempted" sessions. Default 5000. */
+    maxAttempted?: number;
+}
+export interface CmsBootstrapCache {
+    ensure(session: string, adapter: CmsAdapter | null | undefined, log: Logger): Promise<void>;
+    /** Test helper — drop all remembered state. */
+    reset(): void;
+    /** Inspection — number of remembered attempts (post-eviction). */
+    readonly attemptedSize: number;
+}
+export declare function createCmsBootstrapCache(opts?: CmsBootstrapCacheOptions): CmsBootstrapCache;
+export declare function ensureSessionBootstrapped(session: string, adapter: CmsAdapter | null | undefined, log: Logger): Promise<void>;
+/** Test helper — clears the default process cache. Runtime-scoped caches own their own `reset()`. */
+export declare function _resetCmsBootstrapCache(): void;

package/dist/cms/bootstrap.js

@@ -0,0 +1,85 @@
+import { getSessionDraft, ensureHeroImageProps, bumpVersion, schedulePersistState } from "../state/session-state.js";
+const DEFAULT_MAX_ATTEMPTED = 5000;
+export function createCmsBootstrapCache(opts = {}) {
+    const inFlight = new Map();
+    // Set is insertion-ordered, so FIFO eviction is just "delete the first key".
+    const attempted = new Set();
+    const maxAttempted = Math.max(1, opts.maxAttempted ?? DEFAULT_MAX_ATTEMPTED);
+    function markAttempted(session) {
+        attempted.add(session);
+        while (attempted.size > maxAttempted) {
+            const oldest = attempted.values().next().value;
+            if (oldest === undefined)
+                break;
+            attempted.delete(oldest);
+        }
+    }
+    async function ensure(session, adapter, log) {
+        if (!adapter)
+            return;
+        if (attempted.has(session))
+            return;
+        const existing = inFlight.get(session);
+        if (existing)
+            return existing;
+        const promise = (async () => {
+            const draft = getSessionDraft(session);
+            if (draft.size > 0)
+                return; // finally-block records the attempt
+            try {
+                const pages = await adapter.getPages();
+                if (pages.length === 0) {
+                    log.info({ session, adapter: adapter.id }, "cms-bootstrap: adapter returned no pages");
+                    return;
+                }
+                for (const page of pages) {
+                    const copy = structuredClone(page);
+                    ensureHeroImageProps(copy);
+                    draft.set(copy.slug, copy);
+                }
+                bumpVersion(session);
+                schedulePersistState(log);
+                log.info({ session, adapter: adapter.id, count: pages.length }, "cms-bootstrap: seeded session draft");
+            }
+            catch (err) {
+                log.warn({
+                    session,
+                    adapter: adapter.id,
+                    err: err instanceof Error ? err.stack ?? err.message : String(err)
+                }, "cms-bootstrap: adapter.getPages() failed");
+            }
+            finally {
+                markAttempted(session);
+            }
+        })();
+        inFlight.set(session, promise);
+        try {
+            await promise;
+        }
+        finally {
+            inFlight.delete(session);
+        }
+    }
+    return {
+        ensure,
+        reset() {
+            inFlight.clear();
+            attempted.clear();
+        },
+        get attemptedSize() {
+            return attempted.size;
+        }
+    };
+}
+// Process-default cache, retained so call sites that don't construct their
+// own runtime (e.g. the orchestrator-core test suite) can still call
+// `ensureSessionBootstrapped` directly. Library-mode runtimes built by
+// createOrchestrator() own their own cache via createCmsBootstrapCache.
+const defaultCache = createCmsBootstrapCache();
+export async function ensureSessionBootstrapped(session, adapter, log) {
+    return defaultCache.ensure(session, adapter, log);
+}
+/** Test helper — clears the default process cache. Runtime-scoped caches own their own `reset()`. */
+export function _resetCmsBootstrapCache() {
+    defaultCache.reset();
+}

package/dist/cms/editor-api-adapter.d.ts

@@ -0,0 +1,23 @@
+import type { CmsAdapter } from "./adapter.ts";
+import type { Logger } from "../logger.ts";
+export interface EditorApiAdapterOptions {
+    /** Site origin, e.g. `https://example.com`. Defaults to env AUTO_BOOTSTRAP_SITE_ORIGIN. */
+    origin?: string;
+    /** Path under the origin. Default `/api/editor/pages`. */
+    path?: string;
+    /** Optional siteId query param. */
+    siteId?: string;
+    /** Request timeout in ms. Default 8000. */
+    timeoutMs?: number;
+    /**
+     * Extra request headers (e.g. `{ authorization: "Bearer …", cookie: "…" }`)
+     * for protected `/api/editor/pages` endpoints. Merged on top of the
+     * default `accept: application/json`. Plain object form keeps this
+     * adapter usable from Node-only tsconfig setups that don't pull in DOM
+     * lib types.
+     */
+    headers?: Record<string, string>;
+    /** Logger for dropped-page warnings. Defaults to consoleLogger(). */
+    logger?: Logger;
+}
+export declare function editorApiAdapter(opts?: EditorApiAdapterOptions): CmsAdapter;

package/dist/cms/editor-api-adapter.js

@@ -0,0 +1,71 @@
+// editorApiAdapter — fetch PageDoc[] from a site's /api/editor/pages endpoint.
+//
+// This is the "Avocado is mounted inside the site itself" pattern: when the
+// orchestrator runs in library mode under the site's Next.js app, it can call
+// the site's own page-listing API to discover content. The legacy behavior
+// of apps/orchestrator's autoBootstrapIfEmpty is exactly this, modulo the
+// fact that the orchestrator now lives in-process so the loopback is purely
+// for sites that already exposed /api/editor/pages.
+//
+// Pass `origin` if the orchestrator runs separately from the site; omit
+// `origin` and pass `loopbackPath` (default `/api/editor/pages`) for the
+// same-process case where the route is a sibling.
+import { pageDocSchemaLenient } from "@avocadostudio-ai/shared";
+import { consoleLogger } from "../logger.js";
+export function editorApiAdapter(opts = {}) {
+    const path = opts.path ?? "/api/editor/pages";
+    const timeoutMs = opts.timeoutMs ?? 8000;
+    const log = opts.logger ?? consoleLogger();
+    return {
+        id: "editor-api",
+        async getPages() {
+            const origin = opts.origin ?? process.env.AUTO_BOOTSTRAP_SITE_ORIGIN?.trim();
+            if (!origin)
+                throw new Error("editorApiAdapter: no origin configured (pass origin or set AUTO_BOOTSTRAP_SITE_ORIGIN)");
+            const url = new URL(path, origin);
+            if (opts.siteId)
+                url.searchParams.set("siteId", opts.siteId);
+            const headers = { accept: "application/json" };
+            if (opts.headers) {
+                for (const [key, value] of Object.entries(opts.headers)) {
+                    headers[key] = value;
+                }
+            }
+            const res = await fetch(url.toString(), {
+                headers,
+                signal: AbortSignal.timeout(timeoutMs)
+            });
+            if (!res.ok)
+                throw new Error(`editorApiAdapter: ${url} returned ${res.status}`);
+            const body = (await res.json());
+            const rawPages = Array.isArray(body)
+                ? body
+                : body && typeof body === "object" && Array.isArray(body.pages)
+                    ? body.pages
+                    : [];
+            const pages = [];
+            for (let i = 0; i < rawPages.length; i++) {
+                const candidate = rawPages[i];
+                const result = pageDocSchemaLenient.safeParse(candidate);
+                if (result.success) {
+                    pages.push(result.data);
+                }
+                else {
+                    const firstIssue = result.error.issues[0];
+                    const slugHint = candidate && typeof candidate === "object" && "slug" in candidate
+                        ? String(candidate.slug ?? "")
+                        : "";
+                    log.warn({
+                        adapter: "editor-api",
+                        url: url.toString(),
+                        index: i,
+                        slug: slugHint,
+                        issuePath: firstIssue?.path,
+                        issueMessage: firstIssue?.message
+                    }, "editorApiAdapter: dropped page that failed lenient PageDoc parse");
+                }
+            }
+            return pages;
+        }
+    };
+}

package/dist/cms/index.d.ts

@@ -0,0 +1,4 @@
+export type { CmsAdapter, CmsInlineAsset, CmsPublishContext, CmsPublishResult } from "./adapter.ts";
+export { jsonFileAdapter, type JsonFileAdapterOptions } from "./json-file-adapter.ts";
+export { editorApiAdapter, type EditorApiAdapterOptions } from "./editor-api-adapter.ts";
+export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache, type CmsBootstrapCache, type CmsBootstrapCacheOptions } from "./bootstrap.ts";

package/dist/cms/index.js

@@ -0,0 +1,3 @@
+export { jsonFileAdapter } from "./json-file-adapter.js";
+export { editorApiAdapter } from "./editor-api-adapter.js";
+export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache } from "./bootstrap.js";

package/dist/cms/json-file-adapter.d.ts

@@ -0,0 +1,11 @@
+import type { CmsAdapter } from "./adapter.ts";
+import type { Logger } from "../logger.ts";
+export interface JsonFileAdapterOptions {
+    /** Path to the JSON file. Relative paths resolve against `process.cwd()`. */
+    path: string;
+    /** If true, onPublish() will overwrite the file. Default: false. */
+    writeOnPublish?: boolean;
+    /** Logger for dropped-page warnings. Defaults to consoleLogger(). */
+    logger?: Logger;
+}
+export declare function jsonFileAdapter(opts: JsonFileAdapterOptions): CmsAdapter;

package/dist/cms/json-file-adapter.js

@@ -0,0 +1,62 @@
+// jsonFileAdapter — read PageDoc[] from a JSON file on disk.
+//
+// Smallest possible adapter. Suitable for sites that keep their content as
+// a checked-in JSON array (the shape the orchestrator + blocks already
+// understand). villa-puravida-web's lib/published-content.json is the
+// canonical example.
+//
+// If `writeOnPublish` is true, onPublish() will overwrite the file with the
+// new PageDoc[]. Use sparingly — in production deployments the file is
+// typically read-only at runtime and republished via CI / git commit.
+import { readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { pageDocSchemaLenient } from "@avocadostudio-ai/shared";
+import { consoleLogger } from "../logger.js";
+export function jsonFileAdapter(opts) {
+    const resolved = isAbsolute(opts.path) ? opts.path : resolve(process.cwd(), opts.path);
+    const log = opts.logger ?? consoleLogger();
+    const adapter = {
+        id: "json-file",
+        async getPages() {
+            const raw = await readFile(resolved, "utf-8");
+            const parsed = JSON.parse(raw);
+            const candidates = Array.isArray(parsed)
+                ? parsed
+                : parsed && typeof parsed === "object" && Array.isArray(parsed.pages)
+                    ? parsed.pages
+                    : [];
+            const pages = [];
+            for (let i = 0; i < candidates.length; i++) {
+                const candidate = candidates[i];
+                const result = pageDocSchemaLenient.safeParse(candidate);
+                if (result.success) {
+                    pages.push(result.data);
+                }
+                else {
+                    const firstIssue = result.error.issues[0];
+                    const slugHint = candidate && typeof candidate === "object" && "slug" in candidate
+                        ? String(candidate.slug ?? "")
+                        : "";
+                    log.warn({
+                        adapter: "json-file",
+                        path: resolved,
+                        index: i,
+                        slug: slugHint,
+                        issuePath: firstIssue?.path,
+                        issueMessage: firstIssue?.message
+                    }, "jsonFileAdapter: dropped page that failed lenient PageDoc parse");
+                }
+            }
+            return pages;
+        }
+    };
+    if (opts.writeOnPublish === true) {
+        // SiteConfig + inline assets aren't relevant to a flat JSON dump — the
+        // file shape is just `PageDoc[]`. Adapters that map into a richer store
+        // (Contentful, Sanity, Strapi) consume those extra args.
+        adapter.onPublish = async (pages) => {
+            await writeFile(resolved, JSON.stringify(pages, null, 2) + "\n", "utf-8");
+        };
+    }
+    return adapter;
+}

package/dist/demo-mode.d.ts

@@ -0,0 +1,59 @@
+import type { Operation, PageDoc } from "@avocadostudio-ai/shared";
+/** Is demo mode enabled for this orchestrator process? */
+export declare function isDemoModeEnabled(): boolean;
+/** Operation types allowed in demo mode. Defaults to ["update_props"]. */
+export declare function getDemoAllowedOpTypes(): string[];
+/** Block types on which update_props is allowed. Defaults to ["Hero"]. */
+export declare function getDemoAllowedBlockTypes(): string[];
+/** Max requests per IP per hour. Defaults to 20. */
+export declare function getDemoRateLimitPerHour(): number;
+/** Should image generation be disabled in demo mode? Defaults to true. */
+export declare function isDemoImageGenDisabled(): boolean;
+/**
+ * Deterministic ephemeral session key for a demo visitor.
+ *
+ * We hash the IP to avoid leaking it, and keep the key short enough to read
+ * in logs. The key does NOT contain "::" so it routes through the default
+ * `getSessionDraft` path which auto-seeds from `demoPublishedPages()`.
+ */
+export declare function demoSessionKeyForIp(ip: string): string;
+/**
+ * Extract a client IP from a Fastify request. Render puts the real client IP
+ * in `x-forwarded-for` (first entry). Falls back to request.ip.
+ */
+export declare function extractClientIp(request: {
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+}): string;
+export type DemoEnforcement = {
+    allowed: Operation[];
+    rejected: Array<{
+        op: Operation;
+        reason: string;
+    }>;
+};
+/**
+ * Validate a list of operations against demo-mode rules. Returns the split
+ * between allowed and rejected ops; caller decides whether to proceed with
+ * the allowed subset or to throw.
+ */
+export declare function splitDemoOps(ops: Operation[], staged: Map<string, PageDoc>): DemoEnforcement;
+/**
+ * Throws an `OperationError` if any of the given ops violates demo-mode
+ * rules. Used as the final gate inside `applyOpsAtomically`, so both chat
+ * and direct `/ops` paths are covered.
+ */
+export declare function enforceDemoOps(ops: Operation[], staged: Map<string, PageDoc>): void;
+/**
+ * Consume one token for the given IP. Returns `{ ok: true }` if allowed,
+ * or `{ ok: false, retryAfterSeconds }` if the quota for the current
+ * hourly window is exhausted.
+ */
+export declare function consumeDemoRateToken(ip: string): {
+    ok: true;
+} | {
+    ok: false;
+    retryAfterSeconds: number;
+};
+/** Reset the rate limiter (test hook). */
+export declare function _resetDemoRateLimiterForTests(): void;