@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.0

package/dist/http/access-tokens.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Access tokens for the orchestrator's protected surfaces.
+ *
+ * Lives in orchestrator-core because there are two surfaces to protect and
+ * they must agree on what a token is. The standalone Fastify server reads one
+ * off a `FastifyRequest`; library mode reads one off a Web `Request`. Same
+ * mint, same TTL, same in-memory table — only the carrier differs, which is
+ * why `extractAccessToken` takes either.
+ *
+ * The editor has always shipped the *client* half of this: PasswordGate reads
+ * `accessToken` off the /auth/verify response, a fetch shim attaches it as
+ * `x-access-token` on every orchestrator request, and EventSource URLs carry it
+ * as a query parameter because the browser API cannot send headers. The server
+ * half was never written — /auth/verify returned `{ok:true}` and nothing ever
+ * read the header. This module is that missing half.
+ *
+ * Tokens are opaque random strings held in memory. They do not survive a
+ * restart, which is correct for a bearer credential with no revocation list:
+ * the editor treats a 401 as "re-prompt for the password" and already wires
+ * that path, so a restart costs the user one password entry.
+ *
+ * Only the SHA-256 of a token is stored. A lookup therefore hashes the
+ * candidate and probes a Map by digest, so neither the probe nor a failure
+ * compares raw secret bytes.
+ */
+/** True when a password gate is configured, i.e. tokens mean something. */
+export declare function isAccessGateEnabled(): boolean;
+export declare function mintAccessToken(): string;
+export declare function isValidAccessToken(token: string | undefined | null): boolean;
+/** Drop every issued token. Used by tests; also a crude "log everyone out". */
+export declare function revokeAllAccessTokens(): void;
+type TokenCarrier = {
+    headers: Record<string, unknown>;
+    query?: unknown;
+};
+/**
+ * Pull a token off a request. Three carriers, because three transports:
+ * `x-access-token` (the editor's fetch shim), `Authorization: Bearer` (the
+ * conventional spelling, for scripts), and `?accessToken=` (EventSource, which
+ * cannot set headers at all).
+ *
+ * Accepts either a Fastify-shaped request (plain `headers` object, parsed
+ * `query`) or a Web `Request`, whose query has to be parsed off the URL.
+ */
+export declare function extractAccessToken(request: TokenCarrier | Request): string;
+/**
+ * Check a submitted password against `ACCESS_PASSWORD_HASH`.
+ *
+ * Read at call time, never at module load: route modules are imported before
+ * `dotenv.config()` runs, so a hash set in `.env` is invisible to anything that
+ * captured it in a module-level `const`. That bug shipped once already — the
+ * gate reported itself disabled and `/auth/verify` accepted anything.
+ *
+ * Returns `false` when no hash is configured. Callers decide what an
+ * unconfigured gate means; it is not this function's business to invent a pass.
+ */
+export declare function verifyAccessPassword(password: string | undefined | null): boolean;
+export {};

package/dist/http/access-tokens.js

@@ -0,0 +1,161 @@
+/**
+ * Access tokens for the orchestrator's protected surfaces.
+ *
+ * Lives in orchestrator-core because there are two surfaces to protect and
+ * they must agree on what a token is. The standalone Fastify server reads one
+ * off a `FastifyRequest`; library mode reads one off a Web `Request`. Same
+ * mint, same TTL, same in-memory table — only the carrier differs, which is
+ * why `extractAccessToken` takes either.
+ *
+ * The editor has always shipped the *client* half of this: PasswordGate reads
+ * `accessToken` off the /auth/verify response, a fetch shim attaches it as
+ * `x-access-token` on every orchestrator request, and EventSource URLs carry it
+ * as a query parameter because the browser API cannot send headers. The server
+ * half was never written — /auth/verify returned `{ok:true}` and nothing ever
+ * read the header. This module is that missing half.
+ *
+ * Tokens are opaque random strings held in memory. They do not survive a
+ * restart, which is correct for a bearer credential with no revocation list:
+ * the editor treats a 401 as "re-prompt for the password" and already wires
+ * that path, so a restart costs the user one password entry.
+ *
+ * Only the SHA-256 of a token is stored. A lookup therefore hashes the
+ * candidate and probes a Map by digest, so neither the probe nor a failure
+ * compares raw secret bytes.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/** How long a minted token stays valid. */
+const TOKEN_TTL_MS = 12 * 60 * 60 * 1000;
+/** Swept lazily on each mint; the map only ever holds one operator's sessions. */
+const issued = new Map();
+function digest(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+function sweep(now) {
+    for (const [hash, expiresAt] of issued) {
+        if (expiresAt <= now)
+            issued.delete(hash);
+    }
+}
+/** True when a password gate is configured, i.e. tokens mean something. */
+export function isAccessGateEnabled() {
+    return Boolean(process.env.ACCESS_PASSWORD_HASH?.trim());
+}
+/**
+ * A static token for non-browser callers (CI, scripts, an MCP client) that have
+ * no way to complete a password exchange. Optional; unset means browser-only.
+ */
+function staticToken() {
+    return process.env.ORCHESTRATOR_ACCESS_TOKEN?.trim() ?? "";
+}
+export function mintAccessToken() {
+    const now = Date.now();
+    sweep(now);
+    const token = randomBytes(32).toString("base64url");
+    issued.set(digest(token), now + TOKEN_TTL_MS);
+    return token;
+}
+/** Constant-time equality for two strings of any length. */
+function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    // timingSafeEqual throws on a length mismatch, which would itself leak the
+    // length. Compare digests instead: always 32 bytes, whatever the inputs.
+    const ah = createHash("sha256").update(ab).digest();
+    const bh = createHash("sha256").update(bb).digest();
+    return timingSafeEqual(ah, bh);
+}
+export function isValidAccessToken(token) {
+    const candidate = token?.trim();
+    if (!candidate)
+        return false;
+    const fixed = staticToken();
+    if (fixed && safeEqual(candidate, fixed))
+        return true;
+    const expiresAt = issued.get(digest(candidate));
+    if (expiresAt === undefined)
+        return false;
+    if (expiresAt <= Date.now()) {
+        issued.delete(digest(candidate));
+        return false;
+    }
+    return true;
+}
+/** Drop every issued token. Used by tests; also a crude "log everyone out". */
+export function revokeAllAccessTokens() {
+    issued.clear();
+}
+function isWebRequest(value) {
+    return typeof value.url === "string" && typeof value.headers === "object"
+        && typeof value.headers?.get === "function";
+}
+/**
+ * Pull a token off a request. Three carriers, because three transports:
+ * `x-access-token` (the editor's fetch shim), `Authorization: Bearer` (the
+ * conventional spelling, for scripts), and `?accessToken=` (EventSource, which
+ * cannot set headers at all).
+ *
+ * Accepts either a Fastify-shaped request (plain `headers` object, parsed
+ * `query`) or a Web `Request`, whose query has to be parsed off the URL.
+ */
+export function extractAccessToken(request) {
+    if (isWebRequest(request)) {
+        const header = request.headers.get("x-access-token");
+        if (header?.trim())
+            return header.trim();
+        const auth = request.headers.get("authorization");
+        if (auth) {
+            const match = /^Bearer\s+(.+)$/i.exec(auth.trim());
+            if (match?.[1])
+                return match[1].trim();
+        }
+        try {
+            const fromQuery = new URL(request.url).searchParams.get("accessToken");
+            if (fromQuery?.trim())
+                return fromQuery.trim();
+        }
+        catch { /* a relative URL cannot carry a query we can read */ }
+        return "";
+    }
+    const header = request.headers["x-access-token"];
+    if (typeof header === "string" && header.trim())
+        return header.trim();
+    const auth = request.headers.authorization;
+    if (typeof auth === "string") {
+        const match = /^Bearer\s+(.+)$/i.exec(auth.trim());
+        if (match?.[1])
+            return match[1].trim();
+    }
+    const query = request.query;
+    if (query && typeof query === "object") {
+        const fromQuery = query.accessToken;
+        if (typeof fromQuery === "string" && fromQuery.trim())
+            return fromQuery.trim();
+    }
+    return "";
+}
+/**
+ * Check a submitted password against `ACCESS_PASSWORD_HASH`.
+ *
+ * Read at call time, never at module load: route modules are imported before
+ * `dotenv.config()` runs, so a hash set in `.env` is invisible to anything that
+ * captured it in a module-level `const`. That bug shipped once already — the
+ * gate reported itself disabled and `/auth/verify` accepted anything.
+ *
+ * Returns `false` when no hash is configured. Callers decide what an
+ * unconfigured gate means; it is not this function's business to invent a pass.
+ */
+export function verifyAccessPassword(password) {
+    const configuredHash = process.env.ACCESS_PASSWORD_HASH?.trim();
+    if (!configuredHash)
+        return false;
+    const candidate = password?.trim();
+    if (!candidate)
+        return false;
+    const hash = createHash("sha256").update(candidate).digest("hex");
+    const ab = Buffer.from(hash, "hex");
+    const bb = Buffer.from(configuredHash, "hex");
+    if (ab.length !== bb.length || ab.length === 0)
+        return false;
+    return timingSafeEqual(ab, bb);
+}

package/dist/http/audio-actions.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Voice-input transcription, as a transport-agnostic action.
+ *
+ * It lived only in `apps/orchestrator/src/routes/media.ts`, wired straight into
+ * Fastify. Library mode — `createOrchestrator()` in the site SDK — serves the
+ * same editor from a plain `Request`/`Response` handler and reimplements
+ * whichever routes somebody remembered to add. It never had this one, so a host
+ * that had funded an `OPENAI_API_KEY` still got a mic button that answered "not
+ * handled by createOrchestrator()" — the editor shows the button off the very
+ * same key that this route reads.
+ *
+ * The route is entirely session-free: no SQLite, no runtime, nothing from
+ * `session-state.js`. Its only coupling to Fastify was multipart decoding, so
+ * the action takes bytes that the transport has already decoded and both sides
+ * keep their own reader — Fastify streams the part (aborting mid-upload once it
+ * crosses the cap), library mode reads a `File` off `request.formData()`.
+ */
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+/**
+ * Formats both providers read natively.
+ *
+ * `audio/ogg` is here because Firefox's MediaRecorder emits it and nothing else;
+ * dropping it would silently disable voice input on one browser.
+ */
+export declare const TRANSCRIPTION_MIME_TYPES: ReadonlySet<string>;
+/** OpenAI's own per-file ceiling for the transcription endpoint. */
+export declare const MAX_TRANSCRIPTION_BYTES: number;
+/** One decoded upload. `filename` is optional because only OpenAI's SDK wants one. */
+export type AudioInput = {
+    bytes: Uint8Array;
+    mimeType: string;
+    filename?: string;
+};
+export type TranscriptionBody = {
+    text: string;
+    provider: "openai" | "gemini";
+    model: string;
+    bytes: number;
+    mimeType: string;
+    /** True when the transcript did not come from the first thing we tried. */
+    fallbackUsed: boolean;
+};
+/**
+ * Seams for tests. Both providers are reached by network on every real call, so
+ * without these the action is only testable down to its validation branches.
+ */
+export type TranscribeDeps = {
+    transcribeWithOpenAI?: (args: {
+        input: AudioInput;
+        filename: string;
+        model: string;
+    }) => Promise<string>;
+    transcribeWithGemini?: (args: {
+        input: AudioInput;
+        model: string;
+    }) => Promise<string>;
+};
+/** Whether either provider key is present — the same test `/status/planner` reports as `features.audioTranscription`. */
+export declare function isTranscriptionConfigured(): boolean;
+/**
+ * The 503 to send when neither key is set, or `null` when at least one provider
+ * is usable. Callers check this before touching the body: an unconfigured
+ * deployment should not be made to upload 25MB to learn that.
+ */
+export declare function transcriptionUnavailable(): ActionResult | null;
+/**
+ * `audio/webm;codecs=opus` → `audio/webm`.
+ *
+ * The two transports disagree about this and only one of them is visible in a
+ * test. `MediaRecorder` reports its type *with* the codec parameter, and the
+ * editor puts that string on the `File` it uploads. Busboy hands Fastify the
+ * bare `type/subtype`, so the standalone server never saw the parameter and the
+ * exact-set check below has always passed there — while `request.formData()`
+ * preserves the whole header value, so library mode would have answered 415 to
+ * every recording Chrome makes.
+ *
+ * Normalizing here rather than at each call site is deliberate: a caller that
+ * forgets is not wrong at compile time and not wrong on Firefox, only on the
+ * browser most people use. The normalized form is also what goes to the
+ * providers and comes back in the response body, so both transports report the
+ * same `mimeType` for the same recording.
+ */
+export declare function normalizeAudioMimeType(raw: string): string;
+/**
+ * The half of the check that needs no bytes, split out for streaming callers.
+ *
+ * A transport that reads the part incrementally knows the MIME type from the
+ * part headers and wants to refuse an unsupported one before pulling 25MB off
+ * the socket. Without this it would have to either buffer first or write its
+ * own 415 — and a second copy of that body is how the two hosts start
+ * answering the same bad upload differently.
+ */
+export declare function validateAudioMimeType(mimeType: string): ActionResult | null;
+/**
+ * Reject an upload we cannot transcribe, or `null` when it is acceptable.
+ *
+ * The order matters and mirrors what a streaming transport can actually check:
+ * the MIME type is known from the part headers before a single byte is read, so
+ * it is rejected first; size and emptiness are only knowable afterwards. A
+ * transport that enforces the cap while streaming will never see the 413 here,
+ * but a caller that buffers first (library mode, an MCP tool, a test) gets the
+ * same answer from one place instead of inventing its own.
+ */
+export declare function validateAudioInput(input: {
+    mimeType: string;
+    byteLength: number;
+}): ActionResult | null;
+/** Comma-separated env lists, tolerant of stray whitespace and trailing commas. */
+export declare function parseTranscriptionModelList(raw: string | undefined): string[];
+export declare function getGeminiTranscribeModel(): string;
+/**
+ * Transcribe already-decoded audio, OpenAI first and Gemini second.
+ *
+ * Every attempt that fails contributes a line to `errors` rather than ending
+ * the call, because the whole point of the ladder is that one dead provider
+ * must not cost the user their recording. Only when nothing worked do those
+ * lines come back as the 502 detail — that string is the only diagnostic a
+ * hosted deployment gets, so it is worth keeping specific.
+ */
+export declare function transcribeAudioAction(rawInput: AudioInput, deps?: TranscribeDeps): Promise<ActionResult>;

package/dist/http/audio-actions.js

@@ -0,0 +1,248 @@
+/**
+ * Voice-input transcription, as a transport-agnostic action.
+ *
+ * It lived only in `apps/orchestrator/src/routes/media.ts`, wired straight into
+ * Fastify. Library mode — `createOrchestrator()` in the site SDK — serves the
+ * same editor from a plain `Request`/`Response` handler and reimplements
+ * whichever routes somebody remembered to add. It never had this one, so a host
+ * that had funded an `OPENAI_API_KEY` still got a mic button that answered "not
+ * handled by createOrchestrator()" — the editor shows the button off the very
+ * same key that this route reads.
+ *
+ * The route is entirely session-free: no SQLite, no runtime, nothing from
+ * `session-state.js`. Its only coupling to Fastify was multipart decoding, so
+ * the action takes bytes that the transport has already decoded and both sides
+ * keep their own reader — Fastify streams the part (aborting mid-upload once it
+ * crosses the cap), library mode reads a `File` off `request.formData()`.
+ */
+import OpenAI from "openai";
+import { toFile } from "openai/uploads";
+import { toErrorDetail } from "../errors.js";
+import { getGeminiClient } from "../image/image-helpers.js";
+/**
+ * Formats both providers read natively.
+ *
+ * `audio/ogg` is here because Firefox's MediaRecorder emits it and nothing else;
+ * dropping it would silently disable voice input on one browser.
+ */
+export const TRANSCRIPTION_MIME_TYPES = new Set([
+    "audio/mp3",
+    "audio/mpeg",
+    "audio/mp4",
+    "audio/mpga",
+    "audio/m4a",
+    "audio/wav",
+    "audio/webm",
+    "audio/ogg"
+]);
+/** OpenAI's own per-file ceiling for the transcription endpoint. */
+export const MAX_TRANSCRIPTION_BYTES = 25 * 1024 * 1024;
+/** Whether either provider key is present — the same test `/status/planner` reports as `features.audioTranscription`. */
+export function isTranscriptionConfigured() {
+    return Boolean(process.env.OPENAI_API_KEY?.trim() || process.env.GOOGLE_GENAI_API_KEY?.trim());
+}
+/**
+ * The 503 to send when neither key is set, or `null` when at least one provider
+ * is usable. Callers check this before touching the body: an unconfigured
+ * deployment should not be made to upload 25MB to learn that.
+ */
+export function transcriptionUnavailable() {
+    if (isTranscriptionConfigured())
+        return null;
+    return {
+        code: 503,
+        body: { error: "no transcription provider configured (set OPENAI_API_KEY or GOOGLE_GENAI_API_KEY)" }
+    };
+}
+/**
+ * `audio/webm;codecs=opus` → `audio/webm`.
+ *
+ * The two transports disagree about this and only one of them is visible in a
+ * test. `MediaRecorder` reports its type *with* the codec parameter, and the
+ * editor puts that string on the `File` it uploads. Busboy hands Fastify the
+ * bare `type/subtype`, so the standalone server never saw the parameter and the
+ * exact-set check below has always passed there — while `request.formData()`
+ * preserves the whole header value, so library mode would have answered 415 to
+ * every recording Chrome makes.
+ *
+ * Normalizing here rather than at each call site is deliberate: a caller that
+ * forgets is not wrong at compile time and not wrong on Firefox, only on the
+ * browser most people use. The normalized form is also what goes to the
+ * providers and comes back in the response body, so both transports report the
+ * same `mimeType` for the same recording.
+ */
+export function normalizeAudioMimeType(raw) {
+    return (raw.split(";")[0] ?? "").trim().toLowerCase();
+}
+/**
+ * The half of the check that needs no bytes, split out for streaming callers.
+ *
+ * A transport that reads the part incrementally knows the MIME type from the
+ * part headers and wants to refuse an unsupported one before pulling 25MB off
+ * the socket. Without this it would have to either buffer first or write its
+ * own 415 — and a second copy of that body is how the two hosts start
+ * answering the same bad upload differently.
+ */
+export function validateAudioMimeType(mimeType) {
+    if (!TRANSCRIPTION_MIME_TYPES.has(normalizeAudioMimeType(mimeType))) {
+        // The raw value is echoed, not the normalized one — someone reading this
+        // error wants to see what their client actually sent.
+        return { code: 415, body: { error: `unsupported audio type: ${mimeType}` } };
+    }
+    return null;
+}
+/**
+ * Reject an upload we cannot transcribe, or `null` when it is acceptable.
+ *
+ * The order matters and mirrors what a streaming transport can actually check:
+ * the MIME type is known from the part headers before a single byte is read, so
+ * it is rejected first; size and emptiness are only knowable afterwards. A
+ * transport that enforces the cap while streaming will never see the 413 here,
+ * but a caller that buffers first (library mode, an MCP tool, a test) gets the
+ * same answer from one place instead of inventing its own.
+ */
+export function validateAudioInput(input) {
+    const badType = validateAudioMimeType(input.mimeType);
+    if (badType)
+        return badType;
+    if (input.byteLength > MAX_TRANSCRIPTION_BYTES) {
+        return { code: 413, body: { error: "audio file is too large (max 25MB)" } };
+    }
+    if (input.byteLength === 0) {
+        return { code: 400, body: { error: "audio file is empty" } };
+    }
+    return null;
+}
+/** Comma-separated env lists, tolerant of stray whitespace and trailing commas. */
+export function parseTranscriptionModelList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+export function getGeminiTranscribeModel() {
+    return process.env.GOOGLE_GENAI_TRANSCRIBE_MODEL?.trim() || "gemini-2.5-flash";
+}
+// A view, not a copy: the transport already allocated these bytes and an audio
+// upload can be 25MB.
+function asBuffer(bytes) {
+    return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+/**
+ * Gemini reads audio natively (webm/ogg/wav/mp4/m4a/mp3 all verified), so it
+ * serves as a drop-in fallback when OpenAI is unavailable — and as the only
+ * transcriber in deployments that fund a Google key and nothing else.
+ */
+async function geminiTranscribe(args) {
+    const ai = await getGeminiClient();
+    const response = await ai.models.generateContent({
+        model: args.model,
+        contents: [
+            {
+                role: "user",
+                parts: [
+                    {
+                        text: "Transcribe this audio verbatim. Return only the spoken words as plain text — no preamble, quotes, or commentary. If there is no intelligible speech, return an empty string."
+                    },
+                    { inlineData: { mimeType: args.input.mimeType, data: asBuffer(args.input.bytes).toString("base64") } }
+                ]
+            }
+        ]
+    });
+    return (response.text ?? "").trim();
+}
+/**
+ * Transcribe already-decoded audio, OpenAI first and Gemini second.
+ *
+ * Every attempt that fails contributes a line to `errors` rather than ending
+ * the call, because the whole point of the ladder is that one dead provider
+ * must not cost the user their recording. Only when nothing worked do those
+ * lines come back as the 502 detail — that string is the only diagnostic a
+ * hosted deployment gets, so it is worth keeping specific.
+ */
+export async function transcribeAudioAction(rawInput, deps = {}) {
+    const input = { ...rawInput, mimeType: normalizeAudioMimeType(rawInput.mimeType) };
+    const hasOpenAI = Boolean(process.env.OPENAI_API_KEY?.trim());
+    const hasGemini = Boolean(process.env.GOOGLE_GENAI_API_KEY?.trim());
+    const bytes = input.bytes.byteLength;
+    const errors = [];
+    // Primary: OpenAI Whisper-family models (best quality). Try the configured
+    // model, then any fallbacks, before giving up on the provider.
+    if (hasOpenAI) {
+        const primaryModel = process.env.OPENAI_TRANSCRIBE_MODEL?.trim() || "gpt-4o-mini-transcribe";
+        const fallbackModels = parseTranscriptionModelList(process.env.OPENAI_TRANSCRIBE_FALLBACK_MODELS);
+        const modelsToTry = Array.from(new Set([primaryModel, ...fallbackModels]));
+        const filename = input.filename || `recording.${input.mimeType.split("/")[1] ?? "webm"}`;
+        try {
+            // Building the client and the uploadable file is done once, outside the
+            // model loop, and a failure here is attributed to the provider rather
+            // than to any one model — it means we never got as far as a request.
+            const transcribe = deps.transcribeWithOpenAI ?? (await createOpenAITranscriber(input, filename));
+            for (const model of modelsToTry) {
+                try {
+                    const text = await transcribe({ input, filename, model });
+                    return {
+                        code: 200,
+                        body: {
+                            text,
+                            provider: "openai",
+                            model,
+                            bytes,
+                            mimeType: input.mimeType,
+                            fallbackUsed: model !== primaryModel
+                        }
+                    };
+                }
+                catch (error) {
+                    errors.push(`openai/${model}: ${toErrorDetail(error)}`);
+                }
+            }
+        }
+        catch (error) {
+            errors.push(`openai: ${toErrorDetail(error)}`);
+        }
+    }
+    if (hasGemini) {
+        const model = getGeminiTranscribeModel();
+        try {
+            const text = await (deps.transcribeWithGemini ?? geminiTranscribe)({ input, model });
+            return {
+                code: 200,
+                body: {
+                    text,
+                    provider: "gemini",
+                    model,
+                    bytes,
+                    mimeType: input.mimeType,
+                    // Gemini is the fallback only if OpenAI was configured and lost; on a
+                    // Google-only deployment it is the primary.
+                    fallbackUsed: hasOpenAI
+                }
+            };
+        }
+        catch (error) {
+            errors.push(`gemini: ${toErrorDetail(error)}`);
+        }
+    }
+    return {
+        code: 502,
+        body: { error: "transcription failed", detail: errors.join(" | ").slice(0, 1200) }
+    };
+}
+/**
+ * Bind an OpenAI client and one uploadable copy of the audio to a per-model call.
+ *
+ * `maxRetries: 0` and a bounded timeout are load-bearing: the SDK otherwise
+ * retries a 429 with long backoff, so an over-quota account would stall the
+ * request for minutes before the Gemini fallback ever got its turn.
+ */
+async function createOpenAITranscriber(input, filename) {
+    const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, maxRetries: 0, timeout: 20000 });
+    const audioFile = await toFile(asBuffer(input.bytes), filename, { type: input.mimeType });
+    return async ({ model }) => {
+        const transcription = await client.audio.transcriptions.create({ file: audioFile, model });
+        return transcription.text ?? "";
+    };
+}

package/dist/http/blocks-actions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Block discovery, as a transport-agnostic action.
+ *
+ * The MCP server's `avocado-list-block-types` and `avocado-get-block-schema`
+ * used to read the block registry of their *own* process. That process never
+ * calls the target site's `registerBlocks()`, so for any site with custom
+ * blocks the answer was not merely incomplete, it was inverted: the agent was
+ * handed Avocado's twenty built-ins — types the site cannot render — and told
+ * that the site's own block types were unknown. Discovery is an agent's first
+ * move against a new site, so it planned every subsequent `add_block` from a
+ * confident, complete, wrong answer.
+ *
+ * The registry that matters is the one in the process that will render the
+ * page. In library mode that is this process: `createOrchestrator()` runs
+ * inside the host's Next app and calls its `registerBlocks()`. Serving the
+ * manifest from here therefore answers with the site's real vocabulary, and
+ * the MCP server can stop guessing from module scope.
+ */
+export type ActionResult = {
+    code: number;
+    body: unknown;
+};
+/**
+ * GET /blocks/manifest — every block type registered in this process.
+ *
+ * Deliberately unscoped: there is no `session` or `siteId` parameter, because
+ * the block vocabulary is a property of the running process, not of a draft.
+ * The standalone multi-site server therefore answers with its built-ins for
+ * every site it hosts, which is exactly what it can actually render.
+ */
+export declare function blocksManifestAction(): ActionResult;

package/dist/http/blocks-actions.js

@@ -0,0 +1,31 @@
+/**
+ * Block discovery, as a transport-agnostic action.
+ *
+ * The MCP server's `avocado-list-block-types` and `avocado-get-block-schema`
+ * used to read the block registry of their *own* process. That process never
+ * calls the target site's `registerBlocks()`, so for any site with custom
+ * blocks the answer was not merely incomplete, it was inverted: the agent was
+ * handed Avocado's twenty built-ins — types the site cannot render — and told
+ * that the site's own block types were unknown. Discovery is an agent's first
+ * move against a new site, so it planned every subsequent `add_block` from a
+ * confident, complete, wrong answer.
+ *
+ * The registry that matters is the one in the process that will render the
+ * page. In library mode that is this process: `createOrchestrator()` runs
+ * inside the host's Next app and calls its `registerBlocks()`. Serving the
+ * manifest from here therefore answers with the site's real vocabulary, and
+ * the MCP server can stop guessing from module scope.
+ */
+import { buildBlockManifest } from "@avocadostudio-ai/shared";
+/**
+ * GET /blocks/manifest — every block type registered in this process.
+ *
+ * Deliberately unscoped: there is no `session` or `siteId` parameter, because
+ * the block vocabulary is a property of the running process, not of a draft.
+ * The standalone multi-site server therefore answers with its built-ins for
+ * every site it hosts, which is exactly what it can actually render.
+ */
+export function blocksManifestAction() {
+    const manifest = buildBlockManifest();
+    return { code: 200, body: manifest };
+}