summer-engine 2.8.2 → 3.1.0

package/dist/core/capability-skew.js

@@ -0,0 +1,386 @@
+/**
+ * Engine/CLI capability handshake.
+ *
+ * The MCP server and the engine build ship separately, so the tool surface can
+ * outrun the engine in the field. Newer engines advertise their dispatchable
+ * op kinds (and a protocol version) in /api/health `capabilities`. Two uses:
+ *
+ *   1. summer_get_project_context compares the advertised `opKinds` against
+ *      the ops this CLI's tools send and surfaces a ONE-LINE, NON-FATAL
+ *      warning (plus one mcp.log line per process).
+ *   2. Tools whose op the engine does not advertise return a STRUCTURED
+ *      "engine lacks op X (engine version Y); update the engine" result
+ *      BEFORE sending anything, instead of a raw "unknown op" error.
+ *
+ * Engines that predate `capabilities.opKinds` stay silent on both paths — an
+ * absent list proves nothing, and the per-tool "unknown op" hints still cover
+ * the failure at call time.
+ */
+/** Protocol generation this CLI speaks. Bump only alongside a real wire
+ *  change; used purely for the skew warning, never to refuse a connection. */
+export const CLI_PROTOCOL_VERSION = 1;
+/**
+ * Every engine op kind this package's tools CONSTRUCT themselves (every
+ * `op: "<Kind>"` literal under src/, MCP tools and the CLI dispatcher alike).
+ * capability-skew.test.ts scans the sources and fails when a literal is
+ * missing here; src/core/op-registry-drift.test.ts guards the other direction
+ * inside the engine monorepo (never send an op the engine has no branch for).
+ *
+ * Deliberately NOT listed: ops an agent may compose by hand through
+ * summer_batch / `summer tool batch` (MoveNode, ReparentNode, DisconnectSignal,
+ * Undo, Git*, RunCommand, ExtractZipFromUrl, CustomBake, ...). The CLI only
+ * classifies those for dispatch (single-only / scene-mutation sets) and never
+ * sends them on its own, so listing them would warn about skew the CLI cannot
+ * cause; the engine's per-op "unknown op" error still covers them at call time.
+ */
+export const CLI_KNOWN_OP_NEEDS = [
+    // Scene graph + properties
+    "AddNode", "RemoveNode", "ReplaceNode", "SetProp", "SetResourceProperty",
+    "ConnectSignal", "SelectNode", "OpenScene", "SaveScene", "InstantiateScene",
+    // Navigation (summer_open: core/capabilities/navigation/) — Navigate is the
+    // one-table op (engine navigate_ops.cpp); the other three are the legacy
+    // fallbacks on engines that predate it.
+    "Navigate", "OpenResource", "FocusDock", "RevealInFileSystem",
+    // Project + input
+    "ProjectSetting", "InputMapAddAction", "InputMapBind",
+    // Files (summer_write_file / summer_replace_text / summer_create_scene)
+    "WriteFile",
+    // Import
+    "ImportFromUrl", "ImportFromUrlBatch",
+    // Diagnostics + runtime control
+    "GetConsoleOutput", "ClearConsoleOutput", "GetDebuggerErrors", "IsGameRunning",
+    // summer_play / summer_stop send these as ops for the instance-aware and
+    // determinism variants (seed / fixed_fps / time_scale, instance / mode) —
+    // the legacy /api/play route forwards only `scene`, so the plain launch
+    // stays there.
+    "PlayGame", "StopGame",
+    // runtime control & playtest ops (summer_runtime_* / summer_game_*)
+    "SetRuntimeProp", "CallRuntimeMethod", "SpawnRuntimeScene", "FreeRuntimeNode",
+    "RuntimeAnimation", "RuntimeAnimationTree", "GetRuntimeBones",
+    "GamePause", "GameStep", "GameSpeed",
+    "SimulateInputScript", "InputRecordStart", "InputRecordStop", "InputReplay",
+    "GameProbe", "ListGameInstances",
+    // Capture (+ camera bookmarks: summer_camera_bookmark, perception)
+    "ViewportSnapshot", "GameSnapshot", "ScenePreview",
+    "SaveCameraBookmark", "ListCameraBookmarks", "DeleteCameraBookmark",
+    // Scripting + verification
+    "RunSceneScript", "RunEditorScript", "RunVerification", "SimulateInput",
+    // Perception
+    "GetWorldSnapshot", "DiffWorldSnapshot", "GetRuntimeSceneTree", "GetRuntimeNode",
+    // Spatial / world building
+    "TestPlacement3D", "SnapToSurface", "AlignDistribute3D", "NavigationProbe3D",
+    "Starcast3D",
+    // Mesh fabrication (summer_fabricate_3d — the user's own Blender, engine-supervised)
+    "FabricateMesh",
+    // Editor UI control (editor UI control: summer_ui_actions / summer_ui_tree /
+    // summer_ui_activate / summer_ui_screenshot). All synchronous and
+    // batchable — none joins the single-only set.
+    "UiListActions", "UiInvoke", "UiTree", "UiActivate", "UiScreenshot",
+    "UiDialogs", "UiDismissDialog",
+];
+/** The `capabilities` block of /api/health, shape-checked. Every field is
+ *  optional: an older engine advertises none of them. */
+/**
+ * Escape hatch for the capability pre-flight. The op advert and the ops
+ * themselves ship on different engine branches, so an engine can IMPLEMENT an
+ * op it does not yet ADVERTISE; with the pre-flight on, such a tool would be
+ * refused before sending. `SUMMER_CAPABILITY_PREFLIGHT=off` sends every call
+ * and lets the engine's own "unknown op" error decide. The skew warning still
+ * prints (it is informational) but notes that the pre-flight is off.
+ */
+export const CAPABILITY_PREFLIGHT_ENV = "SUMMER_CAPABILITY_PREFLIGHT";
+export function isCapabilityPreflightDisabled(env = process.env) {
+    const raw = env[CAPABILITY_PREFLIGHT_ENV]?.trim().toLowerCase();
+    return raw === "off" || raw === "0" || raw === "false";
+}
+const PREFLIGHT_OFF_HINT = `If your engine build implements this op but does not advertise it yet, set ${CAPABILITY_PREFLIGHT_ENV}=off in the MCP server's environment to skip this pre-flight and let the engine answer.`;
+function stringList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((entry) => typeof entry === "string");
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Parse a raw `capabilities.events` value. Any plain object counts as an
+ *  advert (an engine may advertise `events: {}`); anything else is "absent". */
+function parseEventsCapability(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const out = {};
+    const kinds = stringList(record.kinds);
+    if (kinds)
+        out.kinds = kinds;
+    for (const key of ["ring", "retainMs", "maxPayloadBytes", "maxStreams", "heartbeatMs"]) {
+        const value = finiteNumber(record[key]);
+        if (value !== undefined)
+            out[key] = value;
+    }
+    for (const key of ["sse", "poll"]) {
+        if (typeof record[key] === "boolean")
+            out[key] = record[key];
+    }
+    return out;
+}
+function parseRuntimeControl(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const out = {};
+    const ops = stringList(record.ops);
+    if (ops)
+        out.ops = ops;
+    if (typeof record.summerCapture === "boolean")
+        out.summerCapture = record.summerCapture;
+    if (typeof record.maxOffscreenInstances === "number" && Number.isFinite(record.maxOffscreenInstances)) {
+        out.maxOffscreenInstances = record.maxOffscreenInstances;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Every op kind the engine advertises: `opKinds` plus the
+ *  `runtimeControl.ops` block (an engine may list the runtime kinds only
+ *  there). Undefined when the engine advertises no op list at all. */
+export function advertisedOpKinds(capabilities) {
+    if (!capabilities?.opKinds)
+        return undefined;
+    return new Set([...capabilities.opKinds, ...(capabilities.runtimeControl?.ops ?? [])]);
+}
+/** Parse a raw /api/health `capabilities` value. Tolerates any shape; returns
+ *  undefined when nothing usable is advertised. Never throws. */
+export function parseEngineCapabilities(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const out = {};
+    const rawProtocol = record.protocolVersion;
+    const protocolVersion = typeof rawProtocol === "number"
+        ? rawProtocol
+        : typeof rawProtocol === "string" && /^\d+$/.test(rawProtocol)
+            ? Number.parseInt(rawProtocol, 10)
+            : undefined;
+    if (protocolVersion !== undefined)
+        out.protocolVersion = protocolVersion;
+    const opKinds = stringList(record.opKinds);
+    if (opKinds)
+        out.opKinds = opKinds;
+    const singleOnlyOps = stringList(record.singleOnlyOps);
+    if (singleOnlyOps)
+        out.singleOnlyOps = singleOnlyOps;
+    const events = parseEventsCapability(record.events);
+    if (events)
+        out.events = events;
+    const runtimeControl = parseRuntimeControl(record.runtimeControl);
+    if (runtimeControl)
+        out.runtimeControl = runtimeControl;
+    const navigation = parseNavigation(record.navigation);
+    if (navigation)
+        out.navigation = navigation;
+    const launchPostures = stringList(record.launchPostures) ?? stringList(record.launch_postures);
+    if (launchPostures)
+        out.launchPostures = launchPostures;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function parseNavigation(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    if (!Array.isArray(record.targets))
+        return undefined;
+    const targets = [];
+    for (const entry of record.targets) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const item = entry;
+        if (typeof item.id !== "string" || item.id.length === 0)
+            continue;
+        const args = stringList(item.args);
+        targets.push({
+            id: item.id,
+            ...(typeof item.title === "string" ? { title: item.title } : {}),
+            ...(args ? { args } : {}),
+        });
+    }
+    const version = typeof record.version === "number" ? record.version : undefined;
+    return { ...(version !== undefined ? { version } : {}), targets };
+}
+/**
+ * True ONLY when the engine advertises an op list and `op` is not on it. An
+ * engine without an advert returns false — we cannot prove absence, so the
+ * call goes through and the per-tool "unknown op" hint handles the failure.
+ */
+export function engineLacksOp(capabilities, op) {
+    const advertised = advertisedOpKinds(capabilities);
+    if (!advertised)
+        return false;
+    return !advertised.has(op);
+}
+/**
+ * The structured result a tool returns when the engine provably lacks its op.
+ * Shaped like an engine op failure ({ok:false, op, error, failure_reason}) so
+ * withEngine/extractOpError classify it the same way, and the model reads the
+ * upgrade path instead of retrying.
+ */
+export function buildMissingOpResult(op, engineVersion, fallback) {
+    const version = engineVersion ?? null;
+    return {
+        ok: false,
+        op,
+        failure_reason: "engine_lacks_op",
+        engine_version: version,
+        error: `This Summer Engine build${version ? ` (engine version ${version})` : ""} does not support the ${op} op — ` +
+            "nothing was sent. Update Summer Engine (restart it after updating). " +
+            `Until then: ${fallback}. ${PREFLIGHT_OFF_HINT}`,
+        hint: `${fallback}. ${PREFLIGHT_OFF_HINT}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Events channel pre-flight (a capability, not an op — deliberately NOT folded
+// into CLI_KNOWN_OP_NEEDS / engineLacksOp)
+// ---------------------------------------------------------------------------
+/**
+ * True when the engine does NOT advertise the events channel. Unlike ops,
+ * where an absent `opKinds` list proves nothing (ops predate the advert), the
+ * events channel and its `capabilities.events` advert ship together: a build
+ * with the channel always advertises it, so absence — including an engine that
+ * advertises no capabilities at all — is proof.
+ */
+export function engineLacksEvents(capabilities) {
+    return !capabilities?.events;
+}
+/** What the events tools tell the model to do when the channel is missing. */
+export const EVENTS_FALLBACK = "poll the state you are waiting for instead (summer_is_running after summer_play; summer_get_debugger_errors / summer_get_console for script errors; summer_get_scene_tree after a long op)";
+const EVENTS_PREFLIGHT_OFF_HINT = `If your engine build serves GET /api/events/poll but does not advertise capabilities.events yet, set ${CAPABILITY_PREFLIGHT_ENV}=off in the MCP server's environment to skip this pre-flight and let the engine answer.`;
+/**
+ * The structured result an events tool returns when the engine provably lacks
+ * the channel. Shaped like buildMissingOpResult ({ok:false, failure_reason,
+ * engine_version, error, hint}) so withEngine/extractOpError classify it the
+ * same way and `summer tool` prints it whole — but under its own
+ * failure_reason, because no op was ever involved.
+ */
+export function buildMissingEventsResult(engineVersion, fallback = EVENTS_FALLBACK) {
+    const version = engineVersion ?? null;
+    return {
+        ok: false,
+        failure_reason: "engine_lacks_events",
+        engine_version: version,
+        error: `This Summer Engine build${version ? ` (engine version ${version})` : ""} does not expose the events channel ` +
+            "(no capabilities.events in /api/health) — nothing was sent. Update Summer Engine to a build with the events channel " +
+            `(restart it after updating). Until then: ${fallback}. ${EVENTS_PREFLIGHT_OFF_HINT}`,
+        hint: `${fallback}. ${EVENTS_PREFLIGHT_OFF_HINT}`,
+    };
+}
+/**
+ * Capability pre-flight for the events tools (summer_wait_for_event,
+ * summer_recent_events, `summer events`). Returns a structured
+ * engine_lacks_events result (nothing is sent) when the engine's /api/health
+ * advert lacks `capabilities.events`; null when the channel is advertised or
+ * the SUMMER_CAPABILITY_PREFLIGHT=off escape hatch is set. Sibling of
+ * missingEngineOpResult — kept separate because events are a capability, not
+ * an op kind.
+ */
+export function missingEngineEventsResult(client, fallback = EVENTS_FALLBACK) {
+    if (isCapabilityPreflightDisabled())
+        return null;
+    const capabilities = typeof client.getEngineCapabilities === "function"
+        ? client.getEngineCapabilities()
+        : undefined;
+    if (!engineLacksEvents(capabilities))
+        return null;
+    const version = typeof client.getEngineVersion === "function" ? client.getEngineVersion() : undefined;
+    return buildMissingEventsResult(version ?? null, fallback);
+}
+/**
+ * Build the one-line skew warning from a raw /api/health payload, or null when
+ * there is nothing trustworthy to say (no capabilities advertised, or no skew).
+ * Shape-tolerant: never throws on odd payloads.
+ */
+export function buildCapabilitySkewWarning(health) {
+    if (!health || typeof health !== "object")
+        return null;
+    const capabilities = parseEngineCapabilities(health.capabilities);
+    if (!capabilities)
+        return null;
+    const parts = [];
+    if (capabilities.protocolVersion !== undefined &&
+        capabilities.protocolVersion !== CLI_PROTOCOL_VERSION) {
+        parts.push(`engine protocolVersion ${capabilities.protocolVersion} != CLI protocolVersion ${CLI_PROTOCOL_VERSION}`);
+    }
+    const advertised = advertisedOpKinds(capabilities);
+    if (advertised) {
+        const missing = CLI_KNOWN_OP_NEEDS.filter((op) => !advertised.has(op));
+        if (missing.length > 0) {
+            parts.push(`engine does not advertise ${missing.length} op(s) this CLI can send (${missing.join(", ")})`);
+        }
+    }
+    if (parts.length === 0)
+        return null;
+    const preflight = isCapabilityPreflightDisabled()
+        ? `Non-fatal — ${CAPABILITY_PREFLIGHT_ENV}=off is set, so affected tools are sent anyway and the engine's own unknown-op error decides.`
+        : `Non-fatal — affected tools return a structured engine_lacks_op result instead of running (set ${CAPABILITY_PREFLIGHT_ENV}=off to send them anyway if your engine implements an op it does not advertise).`;
+    return (`Engine/CLI version skew detected: ${parts.join("; ")}. ` +
+        `${preflight} Update Summer Engine (or the summer-engine CLI) so both sides match.`);
+}
+// ---------------------------------------------------------------------------
+// Single-only dispatch classification
+// ---------------------------------------------------------------------------
+/**
+ * Engine ops that MUST be dispatched as their own single-op request. Mirrors
+ * _summer_requires_single_async_dispatch (local_api_server.cpp, engine
+ * 0.5.60+): the engine rejects any multi-op batch containing one of these
+ * WHOLESALE — nothing in the batch executes, and the batch fails with per-op
+ * failure_reason "unsupported_transport"/"skipped". Git ops are covered by a
+ * prefix check in the dispatchers.
+ *
+ * This hardcoded list is the FALLBACK for engines that predate the
+ * /api/health `capabilities.singleOnlyOps` advert; when the engine advertises
+ * its own list, that list is authoritative (resolveSingleOnlyOps).
+ */
+export const FALLBACK_SINGLE_ONLY_OPS = new Set([
+    "SaveScene", "InstantiateScene", "ReplaceNode",
+    "SimulateInput", "ViewportSnapshot", "GameSnapshot",
+    // Runtime debugger reads share GameSnapshot's async single-only dispatch
+    // classification.
+    "GetRuntimeSceneTree", "GetRuntimeNode",
+    "RunCommand", "RunVerification", "RunEditorScript", "RunSceneScript",
+    "ImportFromUrl", "ImportFromUrlBatch", "ExtractZipFromUrl",
+    // Mesh fabrication: a headless Blender child on the same async single-op lane as
+    // RunEditorScript (local_api_server.cpp SUMMER_SINGLE_ASYNC_OPS).
+    "FabricateMesh",
+    // runtime control (RuntimeOps::async_op_kinds): every op below rides
+    // the `summer` debugger capture, so like GameSnapshot each needs the async
+    // single-op reply channel. ListGameInstances is deliberately NOT here — it
+    // is a cheap synchronous editor read that batches fine (runtime_ops.h).
+    "SetRuntimeProp", "CallRuntimeMethod", "SpawnRuntimeScene", "FreeRuntimeNode",
+    "RuntimeAnimation", "RuntimeAnimationTree", "GetRuntimeBones",
+    "GamePause", "GameSpeed", "GameStep",
+    "SimulateInputScript", "InputRecordStart", "InputRecordStop", "InputReplay",
+    "GameProbe",
+]);
+/** The single-only op set for THIS engine: its advertised
+ *  `capabilities.singleOnlyOps` when present, else the hardcoded fallback. An
+ *  empty advertised list counts as no advert — never as "everything batches". */
+export function resolveSingleOnlyOps(client) {
+    const advertised = typeof client.getEngineCapabilities === "function"
+        ? client.getEngineCapabilities()?.singleOnlyOps
+        : undefined;
+    return advertised && advertised.length > 0 ? new Set(advertised) : FALLBACK_SINGLE_ONLY_OPS;
+}
+/**
+ * Capability pre-flight for tools that depend on an op an older engine may
+ * lack. Returns a structured engine_lacks_op result (nothing is sent) when
+ * the engine's /api/health advert PROVES the op is missing; null otherwise —
+ * including for engines that advertise nothing, where the per-tool
+ * "unknown op" hint still covers the failure at call time.
+ */
+export function missingEngineOpResult(client, op, fallback) {
+    if (isCapabilityPreflightDisabled())
+        return null;
+    const capabilities = typeof client.getEngineCapabilities === "function"
+        ? client.getEngineCapabilities()
+        : undefined;
+    if (!engineLacksOp(capabilities, op))
+        return null;
+    const version = typeof client.getEngineVersion === "function" ? client.getEngineVersion() : undefined;
+    return buildMissingOpResult(op, version ?? null, fallback);
+}

package/dist/{lib → core}/config.d.ts

@@ -16,5 +16,15 @@ export declare function getConfigValue(config: SummerConfig, key: ConfigKey): st
 export declare function setConfigValue(key: ConfigKey, rawValue: string): Promise<SummerConfig>;
 export declare function unsetConfigValue(key: ConfigKey): Promise<SummerConfig>;
 export declare function isConfigKey(value: string): value is ConfigKey;
-export declare function getGatewayUrl(): Promise<string>;
+/**
+ * The ONE gateway base URL for every Summer gateway call: login, generation,
+ * asset search/get, job polling, telemetry, and library feedback all resolve
+ * through here so a token minted against one gateway is never posted to
+ * another. Precedence: SUMMER_GATEWAY_URL env > ~/.summer/config.json
+ * gateway.url > production. Resolved at CALL time (never at import) so a
+ * config change is seen by every caller in the same process, and validated on
+ * every read: HTTPS only, except plain HTTP to loopback for local development.
+ * Returns an origin-like base without a trailing slash.
+ */
+export declare function resolveGatewayUrl(): Promise<string>;
 export declare function getCreatorApiUrl(): Promise<string>;

package/dist/{lib → core}/config.js

@@ -129,12 +129,23 @@ export async function unsetConfigValue(key) {
 export function isConfigKey(value) {
     return CONFIG_KEYS.includes(value);
 }
-export async function getGatewayUrl() {
+/**
+ * The ONE gateway base URL for every Summer gateway call: login, generation,
+ * asset search/get, job polling, telemetry, and library feedback all resolve
+ * through here so a token minted against one gateway is never posted to
+ * another. Precedence: SUMMER_GATEWAY_URL env > ~/.summer/config.json
+ * gateway.url > production. Resolved at CALL time (never at import) so a
+ * config change is seen by every caller in the same process, and validated on
+ * every read: HTTPS only, except plain HTTP to loopback for local development.
+ * Returns an origin-like base without a trailing slash.
+ */
+export async function resolveGatewayUrl() {
     const environment = process.env.SUMMER_GATEWAY_URL?.trim();
     if (environment)
         return validateGatewayUrl(environment);
     const config = await readSummerConfig();
-    return config.gateway?.url ?? DEFAULT_GATEWAY_URL;
+    const configured = config.gateway?.url?.trim();
+    return configured ? validateGatewayUrl(configured) : DEFAULT_GATEWAY_URL;
 }
 export async function getCreatorApiUrl() {
     const config = await readSummerConfig();

package/dist/core/embeddings.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Embeddings — the one implementation of the wire protocol, the vector
+ * encoding, and the vector math behind semantic library search.
+ *
+ * Shared by the runtime (src/core/library-search.ts: embed the QUERY) and the
+ * registry compiler (scripts/generate-registry/embed.ts: embed every ENTRY
+ * into registry/generated/embeddings.json). Deliberately free of relative
+ * imports so the compiler script can load it as plain TypeScript the way
+ * evals/routing/runner.ts loads registry-search.ts.
+ *
+ * Provider protocol (SUMMER_EMBED_URL, or <gateway>/api/mcp/embed):
+ *   POST { text } -> 2xx JSON { vector: number[], model?: string }
+ * Anything else — non-2xx, timeout, malformed body, wrong dims — is a
+ * provider failure. Callers decide what that means (the runtime degrades to
+ * lexical search; the compiler aborts the embed step).
+ *
+ * File format (registry/generated/embeddings.json), a sidecar of index.json:
+ *   { _generated, model, dims, encoding: "base64-float32",
+ *     entries: { "<id>": { content_hash, vector: "<base64 float32 LE>" } } }
+ * base64 float32 is ~2x smaller than rounded JSON number arrays and ~5x
+ * smaller than full-precision ones (measured on 384-dim vectors), and
+ * lossless for float32 providers.
+ */
+export declare const EMBEDDINGS_FILE = "embeddings.json";
+export declare const EMBEDDINGS_ENCODING = "base64-float32";
+export declare const EMBED_PATH = "/api/mcp/embed";
+export interface EmbeddingsEntry {
+    content_hash: string;
+    /** base64-encoded little-endian float32 array (EMBEDDINGS_ENCODING). */
+    vector: string;
+}
+export interface EmbeddingsFile {
+    _generated?: string;
+    model: string;
+    dims: number;
+    encoding: typeof EMBEDDINGS_ENCODING;
+    entries: Record<string, EmbeddingsEntry>;
+}
+export interface EmbedResponse {
+    vector: number[];
+    model?: string;
+}
+export type EmbedProvider = (text: string) => Promise<EmbedResponse>;
+export interface EmbedProviderOptions {
+    url: string;
+    /** Summer account token; sent as an Authorization header when present. */
+    token?: string | null;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function encodeVector(vector: readonly number[]): string;
+export declare function decodeVector(encoded: string): Float32Array;
+export declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
+/** Reciprocal rank fusion (Cormack et al. 2009): score(d) = sum over lists of
+ *  1 / (k + rank), rank starting at 1. Ties break on id for determinism. */
+export declare const RRF_K = 60;
+export declare function reciprocalRankFusion(rankedLists: ReadonlyArray<readonly string[]>, k?: number): Array<{
+    id: string;
+    score: number;
+}>;
+export interface EmbeddableEntry {
+    summary?: unknown;
+    use_when?: unknown;
+    facets?: unknown;
+}
+/** The text an entry is embedded from: summary + use_when + facets. Same
+ *  function at compile time and (for tests/tools) at runtime so the two can
+ *  never drift. */
+export declare function buildEmbeddingText(entry: EmbeddableEntry): string;
+/** Shape-tolerant parse; returns null for anything unusable so callers can
+ *  fall back to lexical search instead of throwing. */
+export declare function parseEmbeddingsFile(json: unknown): EmbeddingsFile | null;
+/**
+ * Build a provider: POST { text } to `url`, expect { vector, model? }.
+ * Throws on every failure mode (network, timeout, non-2xx, malformed body).
+ * Never logs: the runtime caller runs inside a stdio MCP server.
+ */
+export declare function createEmbedProvider(options: EmbedProviderOptions): EmbedProvider;

package/dist/core/embeddings.js

@@ -0,0 +1,166 @@
+/**
+ * Embeddings — the one implementation of the wire protocol, the vector
+ * encoding, and the vector math behind semantic library search.
+ *
+ * Shared by the runtime (src/core/library-search.ts: embed the QUERY) and the
+ * registry compiler (scripts/generate-registry/embed.ts: embed every ENTRY
+ * into registry/generated/embeddings.json). Deliberately free of relative
+ * imports so the compiler script can load it as plain TypeScript the way
+ * evals/routing/runner.ts loads registry-search.ts.
+ *
+ * Provider protocol (SUMMER_EMBED_URL, or <gateway>/api/mcp/embed):
+ *   POST { text } -> 2xx JSON { vector: number[], model?: string }
+ * Anything else — non-2xx, timeout, malformed body, wrong dims — is a
+ * provider failure. Callers decide what that means (the runtime degrades to
+ * lexical search; the compiler aborts the embed step).
+ *
+ * File format (registry/generated/embeddings.json), a sidecar of index.json:
+ *   { _generated, model, dims, encoding: "base64-float32",
+ *     entries: { "<id>": { content_hash, vector: "<base64 float32 LE>" } } }
+ * base64 float32 is ~2x smaller than rounded JSON number arrays and ~5x
+ * smaller than full-precision ones (measured on 384-dim vectors), and
+ * lossless for float32 providers.
+ */
+export const EMBEDDINGS_FILE = "embeddings.json";
+export const EMBEDDINGS_ENCODING = "base64-float32";
+export const EMBED_PATH = "/api/mcp/embed";
+// ── Vector encoding ────────────────────────────────────────────────────────
+export function encodeVector(vector) {
+    const floats = new Float32Array(vector.length);
+    for (let i = 0; i < vector.length; i++)
+        floats[i] = vector[i];
+    return Buffer.from(floats.buffer, floats.byteOffset, floats.byteLength).toString("base64");
+}
+export function decodeVector(encoded) {
+    const bytes = Buffer.from(encoded, "base64");
+    if (bytes.byteLength % 4 !== 0)
+        throw new Error("embedding vector: byte length is not a multiple of 4");
+    // Copy into an aligned buffer: Buffer slices from the pool are not 4-aligned.
+    const aligned = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(aligned).set(bytes);
+    return new Float32Array(aligned);
+}
+// ── Vector math ────────────────────────────────────────────────────────────
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/** Reciprocal rank fusion (Cormack et al. 2009): score(d) = sum over lists of
+ *  1 / (k + rank), rank starting at 1. Ties break on id for determinism. */
+export const RRF_K = 60;
+export function reciprocalRankFusion(rankedLists, k = RRF_K) {
+    const scores = new Map();
+    for (const list of rankedLists) {
+        list.forEach((id, index) => {
+            scores.set(id, (scores.get(id) ?? 0) + 1 / (k + index + 1));
+        });
+    }
+    return [...scores.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+/** The text an entry is embedded from: summary + use_when + facets. Same
+ *  function at compile time and (for tests/tools) at runtime so the two can
+ *  never drift. */
+export function buildEmbeddingText(entry) {
+    const parts = [];
+    if (typeof entry.summary === "string")
+        parts.push(entry.summary.trim());
+    if (Array.isArray(entry.use_when)) {
+        for (const line of entry.use_when)
+            if (typeof line === "string")
+                parts.push(line.trim());
+    }
+    if (entry.facets && typeof entry.facets === "object" && !Array.isArray(entry.facets)) {
+        const facetWords = [];
+        for (const value of Object.values(entry.facets)) {
+            if (Array.isArray(value))
+                for (const v of value)
+                    if (typeof v === "string")
+                        facetWords.push(v);
+        }
+        if (facetWords.length > 0)
+            parts.push(facetWords.join(" "));
+    }
+    return parts.filter((p) => p.length > 0).join("\n");
+}
+// ── File parsing ───────────────────────────────────────────────────────────
+/** Shape-tolerant parse; returns null for anything unusable so callers can
+ *  fall back to lexical search instead of throwing. */
+export function parseEmbeddingsFile(json) {
+    if (!json || typeof json !== "object" || Array.isArray(json))
+        return null;
+    const raw = json;
+    if (raw.encoding !== EMBEDDINGS_ENCODING)
+        return null;
+    if (typeof raw.dims !== "number" || !Number.isInteger(raw.dims) || raw.dims <= 0)
+        return null;
+    if (!raw.entries || typeof raw.entries !== "object" || Array.isArray(raw.entries))
+        return null;
+    const entries = {};
+    for (const [id, value] of Object.entries(raw.entries)) {
+        if (!value || typeof value !== "object")
+            continue;
+        const entry = value;
+        if (typeof entry.content_hash !== "string" || typeof entry.vector !== "string")
+            continue;
+        entries[id] = { content_hash: entry.content_hash, vector: entry.vector };
+    }
+    return {
+        _generated: typeof raw._generated === "string" ? raw._generated : undefined,
+        model: typeof raw.model === "string" ? raw.model : "unknown",
+        dims: raw.dims,
+        encoding: EMBEDDINGS_ENCODING,
+        entries,
+    };
+}
+// ── Provider client ────────────────────────────────────────────────────────
+function isFiniteNumberArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((n) => typeof n === "number" && Number.isFinite(n));
+}
+/**
+ * Build a provider: POST { text } to `url`, expect { vector, model? }.
+ * Throws on every failure mode (network, timeout, non-2xx, malformed body).
+ * Never logs: the runtime caller runs inside a stdio MCP server.
+ */
+export function createEmbedProvider(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    return async (text) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+        try {
+            const headers = { "Content-Type": "application/json" };
+            if (options.token)
+                headers.Authorization = `Bearer ${options.token}`;
+            const response = await fetchImpl(options.url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ text }),
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                throw new Error(`embedding provider responded ${response.status}`);
+            const body = (await response.json());
+            if (!isFiniteNumberArray(body.vector))
+                throw new Error("embedding provider returned no numeric vector");
+            return {
+                vector: body.vector,
+                ...(typeof body.model === "string" && body.model ? { model: body.model } : {}),
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}