@evandu/super-pi 0.1.84 → 0.1.86

package/dist/server/http-server.js

@@ -1,6 +1,6 @@
 import { createReadStream, existsSync } from "node:fs";
 import { spawn } from "node:child_process";
-import { readdir, stat } from "node:fs/promises";
+import { readdir, rm, stat } from "node:fs/promises";
 import { createServer } from "node:http";
 import { homedir, networkInterfaces } from "node:os";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
@@ -9,6 +9,8 @@ import { findUploadFile, MAX_UPLOAD_BODY_BYTES, saveUpload } from "./upload.js";
 import { checkDiskVersion } from "./version.js";
 import { gitDiff, gitLog, gitStatus } from "./git.js";
 import { verifyCapability } from "./capability.js";
+import { MAX_KNOWLEDGE_REQUEST_BYTES } from "./knowledge.js";
+import { MAX_TOOL_BODY_BYTES } from "./tool-registry.js";
 import { packageUpdateArgs } from "./update.js";
 const MIME_TYPES = {
     ".css": "text/css; charset=utf-8",
@@ -49,6 +51,28 @@ function toolBrowserSdk() {
       }
     },
     runAndWait: async (params = {}, options) => { const run = await api.run(params); return api.wait(run.id, options); },
+    // THE MODEL, ASKED ON THE TOOL'S BEHALF. One call, one answer, no client to write: Super Pi owns the
+    // credentials, the model choice and the ceilings, and the tool only ever sees the text. It is a
+    // completion, not an agent - the model that answers has no tools, no files and no session history.
+    // Only a tool registered with permissions.llm may call it; otherwise the server refuses.
+    llm: (input = {}) => request("./api/llm", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(input) }),
+    llmGet: (callId) => request("./api/llm/" + encodeURIComponent(callId), { method: "GET" }),
+    llmCancel: (callId) => request("./api/llm/" + encodeURIComponent(callId), { method: "DELETE" }),
+    llmWait: async (callId, { intervalMs = 400, signal } = {}) => {
+      for (;;) {
+        if (signal && signal.aborted) throw new DOMException("Aborted", "AbortError");
+        const call = await api.llmGet(callId);
+        if (call.status !== "running") {
+          if (call.status !== "succeeded") throw new Error(call.error || "Super Pi's model call did not succeed");
+          return call;
+        }
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(resolve, Math.max(50, intervalMs));
+          if (signal) signal.addEventListener("abort", () => { clearTimeout(timer); reject(new DOMException("Aborted", "AbortError")); }, { once: true });
+        });
+      }
+    },
+    llmText: async (input = {}, options) => { const call = await api.llm(input); return (await api.llmWait(call.id, options)).text; },
   };
   Object.freeze(api);
   Object.defineProperty(window, "SuperPiTool", { value: api, writable: false, configurable: false });
@@ -164,6 +188,20 @@ export function parseServerArgs(argv) {
 export function isAuthorized(request, accessToken) {
     return !accessToken || request.headers.authorization === `Bearer ${accessToken}`;
 }
+/**
+ * A signal that fires when the caller goes away, so work started on its behalf can stop.
+ *
+ * WHY IT EXISTS HERE. A knowledge search may spawn a short-lived model call to re-rank its own
+ * candidates. If the agent aborted the turn that made the search, that work has no consumer left, and
+ * without this it would run to its timeout inside a server that is already shutting the turn down.
+ */
+function abortedAs(request) {
+    const controller = new AbortController();
+    request.once("aborted", () => controller.abort());
+    request.once("close", () => { if (!request.readableEnded)
+        controller.abort(); });
+    return controller.signal;
+}
 /**
  * Creates the HTTP server providing static client assets and all `/api/*` endpoints.
  */
@@ -179,17 +217,47 @@ export function createHttpServer(options) {
         // the registry have no such second channel, so they are NOT exempted here and fall through to the
         // ordinary token check below - exempting the whole path is what let any local process list and
         // delete a person's mounted tools on a server that had `SUPER_PI_ACCESS_TOKEN` set.
-        if (requestPath !== "/api/memory/tool" && (requestPath !== "/api/tools" || request.method !== "POST") && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
+        //
+        // `/api/knowledge/tool` is the same shape as `/api/memory/tool` and carries the same exemption for
+        // the same reason: it is reached only by the Pi process of one turn, carrying that turn's
+        // capability in a header. The MANAGEMENT half (`/api/knowledge`) is deliberately NOT exempted - it
+        // imports and deletes documents, so it stays behind the ordinary token.
+        if (requestPath !== "/api/memory/tool" && requestPath !== "/api/knowledge/tool" && (requestPath !== "/api/tools" || request.method !== "POST") && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
             response.writeHead(401, { "www-authenticate": "Bearer" }).end("Authentication required");
             return;
         }
         const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
         const remote = request.socket.remoteAddress ?? "";
         const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }); response.end(JSON.stringify(body)); };
+        if (url.pathname === "/api/tools/export") {
+            // NOT EXEMPT FROM THE TOKEN CHECK ABOVE, and that is deliberate: an export hands out a tool's
+            // whole source, so it is a management read exactly like GET and DELETE, not a capability call.
+            try {
+                const id = url.searchParams.get("id");
+                if (!id) {
+                    json(400, { error: "id required" });
+                    return;
+                }
+                const exported = await toolRegistry.exportBundle(id);
+                if (!exported) {
+                    json(404, { error: "tool not found" });
+                    return;
+                }
+                json(200, exported);
+                return;
+            }
+            catch (error) {
+                json(400, { error: error instanceof Error ? error.message : "tool export failed" });
+                return;
+            }
+        }
         if (url.pathname === "/api/tools") {
             try {
                 if (request.method === "GET") {
-                    json(200, { tools: await toolRegistry.list() });
+                    // The environment state is DERIVED per request and deliberately not stored: it changes when
+                    // the user installs Python, when a tool's venv is built, and when nothing at all happens.
+                    const tools = await toolRegistry.list();
+                    json(200, { tools: await Promise.all(tools.map(async (tool) => ({ ...tool, environmentState: await toolRunner.environmentState(tool) }))) });
                     return;
                 }
                 if (request.method === "DELETE") {
@@ -199,6 +267,11 @@ export function createHttpServer(options) {
                         return;
                     }
                     const removed = await toolRegistry.remove(id);
+                    // The venv is machine-local state that belongs to that tool and nothing else, so it goes with
+                    // it. Leaving it behind would mean a re-registered tool of the same slug silently inherits a
+                    // stale environment.
+                    if (removed)
+                        await rm(toolRunner.envDir(id), { recursive: true, force: true });
                     if (removed)
                         broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
                     json(removed ? 200 : 404, { ok: removed });
@@ -208,13 +281,18 @@ export function createHttpServer(options) {
                     json(405, { error: "method" });
                     return;
                 }
-                let raw = "";
+                // BYTES, NOT CHARACTERS, AND FROM THE REGISTRY'S OWN CONSTANT. The old cap counted UTF-16 code
+                // units at 256,000, below the registry's own 512,000-byte asset limit, so JSON escaping decided
+                // where the real ceiling was and an exported bundle could be refused on the way back in.
+                let raw = "", bytes = 0;
                 for await (const chunk of request) {
-                    raw += chunk;
-                    if (raw.length > 256_000) {
+                    const piece = chunk;
+                    bytes += piece.length;
+                    if (bytes > MAX_TOOL_BODY_BYTES) {
                         json(413, { error: "request too large" });
                         return;
                     }
+                    raw += piece.toString("utf8");
                 }
                 const body = JSON.parse(raw);
                 if (!isAuthorized(request, accessToken)) {
@@ -232,7 +310,16 @@ export function createHttpServer(options) {
                     json(400, { error: "slug, name and files are required" });
                     return;
                 }
-                const tool = await toolRegistry.register({ slug: body.slug, name: body.name, description: body.description, entrypoint: body.entrypoint, script: body.script, files: body.files });
+                // AN IMPORTED BUNDLE KEEPS THE EXPORTER'S FINGERPRINT. It describes where the tool was written
+                // and verified, and overwriting it with the importer's own machine would erase the very
+                // difference the tool list exists to show. A tool with no fingerprint gets one measured here.
+                let environment = body.environment;
+                if (environment && !environment.fingerprint) {
+                    const local = await toolRunner.describeLocalPython();
+                    if (local)
+                        environment = { ...environment, fingerprint: { python: local.python, platform: local.platform, packages: environment.requires } };
+                }
+                const tool = await toolRegistry.register({ slug: body.slug, name: body.name, description: body.description, entrypoint: body.entrypoint, script: body.script, environment, permissions: body.permissions, files: body.files });
                 broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
                 json(201, tool);
                 return;
@@ -296,7 +383,7 @@ export function createHttpServer(options) {
                         toolApi(404, { error: "python script is not registered" });
                         return;
                     }
-                    const run = toolRunner.start({ toolId: id, script: resolve(resolved.root, resolved.tool.script.path), cwd: resolved.root, definition: resolved.tool.script, params: body.params ?? {} });
+                    const run = toolRunner.start({ toolId: id, script: resolve(resolved.root, resolved.tool.script.path), cwd: resolved.root, definition: resolved.tool.script, params: body.params ?? {}, environment: resolved.tool.environment });
                     toolApi(202, run);
                 }
                 catch (error) {
@@ -343,6 +430,91 @@ export function createHttpServer(options) {
                 toolApi(405, { error: "method" });
                 return;
             }
+            // ---- THE MODEL, ON THE TOOL'S OWN BEHALF ---------------------------------------------------
+            // A tool asking the model a question, over the same relative API as its Python jobs, so the frame
+            // still never learns an id, a path or a credential. Three gates, in this order:
+            //   1. the opaque sandbox origin - identical to every other tool API here;
+            //   2. the tool must CARRY the grant (`permissions.llm`), which is the thing the review card showed
+            //      the person before they accepted the file. A tool that quietly started asking the model
+            //      would be spending the user's quota from inside a sandbox they were told was isolated;
+            //   3. the run is bound to this tool id, so one frame cannot read or cancel another's answer.
+            const llmStart = /^api\/llm$/.exec(resource);
+            const llmRun = /^api\/llm\/([^/]+)$/.exec(resource);
+            if (llmStart || llmRun) {
+                if (!toolOrigin) {
+                    toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
+                    return;
+                }
+                // GRANT FIRST, THEN RUNTIME. What a tool is allowed to ask is a fact about the tool and does not
+                // depend on whether this machine happens to have a model, so a tool with no grant gets the same
+                // 403 whether or not Pi is installed.
+                if (!listed.permissions?.llm) {
+                    toolApi(403, { error: "这个工具没有调用模型的权限；注册或导入时它必须声明 permissions: { llm: true }。" });
+                    return;
+                }
+                if (!context.toolLlm?.available) {
+                    toolApi(503, { error: "这台机器上没有可用的 Pi 运行时，工具无法调用模型。" });
+                    return;
+                }
+                if (llmStart) {
+                    if (request.method === "OPTIONS") {
+                        response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "POST", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
+                        return;
+                    }
+                    if (request.method !== "POST") {
+                        toolApi(405, { error: "method" });
+                        return;
+                    }
+                    let raw = "";
+                    for await (const chunk of request) {
+                        raw += chunk;
+                        if (raw.length > 64_000) {
+                            toolApi(413, { error: "request too large" });
+                            return;
+                        }
+                    }
+                    try {
+                        const body = JSON.parse(raw);
+                        toolApi(202, context.toolLlm.start({ toolId: id, prompt: body.prompt ?? "", system: body.system, timeoutMs: body.timeoutMs }));
+                    }
+                    catch (error) {
+                        toolApi(400, { error: error instanceof Error ? error.message : "model call failed" });
+                    }
+                    return;
+                }
+                if (request.method === "OPTIONS") {
+                    response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "GET, DELETE", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
+                    return;
+                }
+                let llmId;
+                try {
+                    llmId = decodeURIComponent(llmRun[1]);
+                }
+                catch {
+                    toolApi(400, { error: "Malformed tool resource" });
+                    return;
+                }
+                if (request.method === "GET") {
+                    const run = context.toolLlm.get(llmId, id);
+                    if (!run) {
+                        toolApi(404, { error: "model call not found" });
+                        return;
+                    }
+                    toolApi(200, run);
+                    return;
+                }
+                if (request.method === "DELETE") {
+                    const run = context.toolLlm.cancel(llmId, id);
+                    if (!run) {
+                        toolApi(404, { error: "model call not found" });
+                        return;
+                    }
+                    toolApi(200, run);
+                    return;
+                }
+                toolApi(405, { error: "method" });
+                return;
+            }
             if (resource === "super-pi-tool.js") {
                 response.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" }).end(toolBrowserSdk());
                 return;
@@ -409,6 +581,44 @@ export function createHttpServer(options) {
             }
             return;
         }
+        if (url.pathname === "/api/knowledge/tool" || url.pathname === "/api/knowledge") {
+            if (!context.knowledge) {
+                response.writeHead(503).end();
+                return;
+            }
+            if ((url.pathname.endsWith("/tool") && request.method !== "POST") || !["GET", "POST"].includes(request.method ?? "")) {
+                response.writeHead(405).end();
+                return;
+            }
+            const origin = request.headers.origin;
+            if (origin && origin !== url.origin) {
+                response.writeHead(403).end("Origin not allowed");
+                return;
+            }
+            try {
+                let raw = "";
+                let totalBytes = 0;
+                // A pasted document rides in the body, so the cap is the document cap - past it the request is
+                // refused outright rather than truncated into a document that silently lost its tail.
+                for await (const chunk of request) {
+                    totalBytes += chunk.length;
+                    if (totalBytes > MAX_KNOWLEDGE_REQUEST_BYTES) {
+                        response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "知识库请求过大" }));
+                        return;
+                    }
+                    raw += chunk;
+                }
+                const body = raw ? JSON.parse(raw) : {};
+                const result = url.pathname.endsWith("/tool")
+                    ? await context.knowledge.tool(String(request.headers["x-knowledge-capability"] ?? ""), body, abortedAs(request))
+                    : await context.knowledge.manage(url.searchParams.get("workspaceId") ?? "", body);
+                response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(result));
+            }
+            catch (error) {
+                response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if (url.pathname === "/api/shutdown") {
             if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
                 response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Shutdown requires a loopback or private network POST");

package/dist/server/index.js

@@ -1,5 +1,7 @@
 import { validateConversationModel } from "./model-filter.js";
 import { ActiveMemory } from "./active-memory.js";
+import { KnowledgeBase } from "./knowledge.js";
+import { VectorIndex } from "./knowledge-vectors.js";
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -24,6 +26,7 @@ import { WsBroadcaster, WsServer } from "./ws-server.js";
 import { initRunningVersion } from "./version.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { ToolRunner } from "./tool-runner.js";
+import { ToolLlmService } from "./tool-llm.js";
 // ------------------------------------------------------------- Environment & paths
 const rootDir = resolve(import.meta.dirname, "../..");
 initRunningVersion(rootDir);
@@ -52,7 +55,9 @@ const toolsEndpoint = `http://${internalHost}:${port}/api/tools`;
 // ------------------------------------------------------------- Core singletons
 const store = await openStateStore(dataDir, process.env.SUPER_PI_PERSISTENCE ?? "sqlite");
 const toolRegistry = new ToolRegistry(dataDir);
-const toolRunner = new ToolRunner();
+// The data dir is what makes a per-tool virtual environment possible: it lives at
+// `<dataDir>/tool-envs/<toolId>`, beside the tools rather than inside one.
+const toolRunner = new ToolRunner(dataDir);
 const initialAgentDirs = resolveAgentDirectories({
     customDirs: store.snapshot().customAgentDirs,
     rootDir,
@@ -75,6 +80,13 @@ const memory = new ActiveMemory(join(dataDir, "memories"), store, runtime);
 process.env.SUPER_PI_MEMORY_ENDPOINT = `http://${internalHost}:${port}/api/memory/tool`;
 if (runtime instanceof PiRpcRuntime)
     runtime.setMemory(memory);
+// The model a mounted tool may ask. It IS Pi: `PiRpcRuntime.askOnce` spawns its own child with nothing
+// attached but Pi, and a runtime without one reports itself unavailable rather than faking an answer.
+const toolLlm = new ToolLlmService(runtime, rootDir);
+const knowledge = new KnowledgeBase(join(dataDir, "knowledge"), store, runtime, new VectorIndex(join(dataDir, "knowledge")));
+process.env.SUPER_PI_KNOWLEDGE_ENDPOINT = `http://${internalHost}:${port}/api/knowledge/tool`;
+if (runtime instanceof PiRpcRuntime)
+    runtime.setKnowledge(knowledge);
 const extensionUiService = new ExtensionUiService(broadcaster);
 const supervisor = new SubagentSupervisor(join(dataDir, "pi-sessions"), undefined, {
     dir: initialAgentDirs,
@@ -148,6 +160,7 @@ const execService = new ExecService((event) => broadcaster.broadcast(event), (se
 runService.setExecService(execService);
 const serverContext = {
     memory,
+    knowledge,
     paths,
     store,
     runtime,
@@ -162,6 +175,7 @@ const serverContext = {
     execService,
     toolRegistry,
     toolRunner,
+    toolLlm,
     terminalEnabled: () => terminalService.enabled,
     terminalDisabledReason: () => terminalDisabledReason(),
 };

package/dist/server/knowledge-vectors.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The model, and the only one this feature can use.
+ *
+ * WHY THIS ONE. `bge-small-zh` scores 0.618 nDCG@10 averaged over the Chinese retrieval tasks it is
+ * benchmarked on - against 0.695 for `bge-base-zh`, which is four times the download. `gte-multilingual-base`
+ * scores higher on both Chinese and English, at 324 MB against this one's 23 MB. For a workspace-sized
+ * corpus the next thing that would help is not a bigger model but fusing this one with the lexical
+ * channels, which costs nothing and is what `KnowledgeBase.search` does.
+ */
+export declare const KNOWLEDGE_MODEL = "Xenova/bge-small-zh-v1.5";
+/**
+ * HOW BIG ONE EMBEDDED PIECE MAY BE, in characters.
+ *
+ * THIS NUMBER IS A MODEL LIMIT, NOT A TUNING KNOB, and getting it wrong is invisible. The model
+ * declares `max_position_embeddings: 512`, and a Chinese character costs roughly one token, so a piece
+ * is a little under half the window: 300 characters leaves room for the `[CLS]`/`[SEP]` pair and for
+ * tokenisation that splits a few characters into two. The retrieval chunks are 1200 characters - more
+ * than double this - which is fine for something a MODEL reads and fatal for something a MODEL
+ * ENCODES: handed a 1200-character chunk, roughly 60% of it is silently discarded past the window.
+ * English would survive it, so the degradation would land only on Chinese: the language this project
+ * is written in.
+ */
+export declare const EMBED_PIECE_CHARS = 300;
+export type VectorRecord = {
+    chunk: number;
+    values: number[];
+};
+/** What the settings panel shows, so "off" and "broken here" are never the same silent nothing. */
+export type VectorStatus = {
+    enabled: boolean;
+    ready: boolean;
+    indexed: number;
+    error?: string;
+    bundled?: boolean;
+};
+/**
+ * Splits a retrieval chunk into pieces small enough for the model's window.
+ *
+ * WHY NOT SHRINK THE RETRIEVAL CHUNKS INSTEAD. 1200 characters is the right size for a passage a model
+ * READS - it holds enough context to answer from. Encoding is a different constraint from reading, and
+ * conflating them would trade retrieval quality for a convenience the encoder does not need.
+ */
+export declare function embedPieces(text: string): string[];
+/** Element-wise max over the pieces, then unit length. See `pool` for why max and not mean. */
+export declare function pool(vectors: number[][]): number[];
+export declare function cosine(a: number[], b: number[]): number;
+/** One document's vectors, on disk next to the document they describe. */
+export type VectorDocument = {
+    digest: string;
+    records: VectorRecord[];
+};
+/**
+ * The optional vector half of retrieval.
+ *
+ * EVERY FAILURE HERE IS A FALLBACK TO LEXICAL, NEVER AN ERROR. The model is an optional npm package
+ * that a skipped optional install can take away, and it is a 512-token window
+ * wrapped around a Chinese corpus. Any of those failing is a reason to answer from the lexical
+ * channels and say so - never a reason to fail a search that the lexical channels can already serve.
+ */
+export declare class VectorIndex {
+    private readonly directory;
+    private extractor?;
+    private loading?;
+    private failure?;
+    private cache;
+    private pending;
+    private queue;
+    private background?;
+    constructor(directory: string);
+    /**
+     * Where the shipped weights live, relative to this module.
+     *
+     * `dist/server/knowledge-vectors.js` is two levels below the package root both in a published
+     * package and in this repository's own build - the same `../../assets/...` shape `runtime.ts` uses to
+     * reach `agents/`. The directory keeps the upstream id in its path because that is how the library
+     * looks the model up under `localModelPath`.
+     */
+    bundledModel(): string;
+    enabled(): boolean;
+    status(indexed: number): VectorStatus;
+    private workspace;
+    private folder;
+    private file;
+    /**
+     * Loads the model once, from the copy that ships with this package. The `dtype` is not optional: on
+     * Node the library defaults to fp32, which for this model is 90 MB rather than 23.
+     *
+     * THERE IS NO NETWORK HERE, and that is the whole point of vendoring the weights. The first version
+     * downloaded the model on first use, which put a 23 MB fetch behind a host the machine may not be
+     * able to reach, on the first search, for every person who installed the package. Shipping the
+     * weights turns a failure mode into a file, and makes the feature work on a machine that has never
+     * been online since it was installed.
+     */
+    private load;
+    private embed;
+    /** Vectors already stored for one workspace, keyed by document then chunk index. */
+    private read;
+    count(workspaceId: string): Promise<number>;
+    /** Drops a document's vectors. Called whenever its content changes or it is deleted. */
+    forget(workspaceId: string, documentId: string): Promise<void>;
+    /**
+     * Embeds anything not already stored, WITHOUT waiting for it.
+     *
+     * WHY IT IS NOT AWAITED. This runs after an import or on the first search of a session, and the
+     * first run of it downloads a model. Neither should make a person wait: the import returns as soon
+     * as the document is stored and the search returns lexical hits, and a later search is simply better
+     * because by then the vectors exist.
+     *
+     * WHY REQUESTS QUEUE RATHER THAN DROP. One job runs at a time - two would load the same model twice
+     * and race each other's writes - but a request arriving mid-job has to be remembered. Dropping it
+     * would mean a document imported while a background index was in flight stayed unindexed until the
+     * next restart, which is the kind of bug that only shows up on a busy machine weeks later.
+     */
+    schedule(workspaceId: string, documents: Array<{
+        id: string;
+        digest: string;
+        chunks: Array<{
+            index: number;
+            text: string;
+        }>;
+    }>): void;
+    /**
+     * Cosine of every stored chunk against the query, best first.
+     *
+     * WHY THE RAW COSINE IS NOT RE-NORMALISED BY THE BEST HIT. Every lexical channel is divided by its
+     * own maximum, and that is right for them because BM25 scores are unbounded and have no absolute
+     * meaning. Cosine is the opposite: it is already a bounded, interpretable quantity, and dividing it
+     * by the best hit of the query would turn "nothing here is close" into "the best one is 1.0". The
+     * knowledge base's most useful property is that it can say it does not know, and rescaling is exactly
+     * how that gets spent.
+     */
+    search(workspaceId: string, query: string, keys: Array<[string, string]>): Promise<Map<string, number> | null>;
+}