@evandu/super-pi 0.1.84 → 0.1.86

package/dist/server/knowledge-vectors.js

@@ -0,0 +1,302 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+/**
+ * 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 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 const EMBED_PIECE_CHARS = 300;
+const EMBED_PIECE_OVERLAP = 40;
+/** Per query. Cosine similarity of unit vectors; beyond this the passage is noise. */
+const MIN_COSINE = 0.15;
+/**
+ * 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 function embedPieces(text) {
+    const pieces = [];
+    for (let offset = 0; offset < text.length; offset += EMBED_PIECE_CHARS - EMBED_PIECE_OVERLAP) {
+        const piece = text.slice(offset, offset + EMBED_PIECE_CHARS).trim();
+        if (piece)
+            pieces.push(piece);
+        if (offset + EMBED_PIECE_CHARS >= text.length)
+            break;
+    }
+    return pieces.length ? pieces : [text.slice(0, EMBED_PIECE_CHARS)];
+}
+/** Element-wise max over the pieces, then unit length. See `pool` for why max and not mean. */
+export function pool(vectors) {
+    if (!vectors.length)
+        return [];
+    const pooled = new Array(vectors[0].length).fill(Number.NEGATIVE_INFINITY);
+    for (const vector of vectors) {
+        for (let i = 0; i < vector.length; i++)
+            if (vector[i] > pooled[i])
+                pooled[i] = vector[i];
+    }
+    let norm = 0;
+    for (const value of pooled)
+        norm += value * value;
+    norm = Math.sqrt(norm) || 1;
+    return pooled.map(value => value / norm);
+}
+export function cosine(a, b) {
+    let dot = 0;
+    for (let i = 0; i < a.length && i < b.length; i++)
+        dot += a[i] * b[i];
+    return dot;
+}
+/**
+ * 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 class VectorIndex {
+    directory;
+    extractor;
+    loading;
+    failure;
+    cache = new Map();
+    pending = new Set();
+    queue = [];
+    background;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    /**
+     * 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() { return resolve(import.meta.dirname, "../../assets/knowledge-model"); }
+    enabled() { return process.env.SUPER_PI_KNOWLEDGE_EMBEDDINGS !== "0"; }
+    status(indexed) {
+        return {
+            enabled: this.enabled(), ready: Boolean(this.extractor), indexed, error: this.failure,
+            // Whether the shipped weights are on disk, reported before the model is ever loaded: "the
+            // package was built without its assets" and "the model failed to load" are different problems.
+            bundled: existsSync(this.bundledModel()),
+        };
+    }
+    workspace(workspaceId) { return join(this.directory, Buffer.from(workspaceId).toString("hex")); }
+    folder(workspaceId) { return join(this.workspace(workspaceId), "vectors"); }
+    file(workspaceId, documentId) { return join(this.folder(workspaceId), `${documentId}.vec.json`); }
+    /**
+     * 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.
+     */
+    load() {
+        if (this.extractor)
+            return Promise.resolve(this.extractor);
+        if (this.failure)
+            return Promise.resolve(undefined);
+        this.loading ??= (async () => {
+            try {
+                if (!existsSync(this.bundledModel()))
+                    throw new Error(`随包分发的模型缺失：${this.bundledModel()}`);
+                // THE SPECIFIER GOES THROUGH A VARIABLE, and that is deliberate. Written as a literal,
+                // `tsc` resolves it while compiling - so a machine whose optional install skipped this package
+                // could not build the server at all, which makes an "optional" dependency mandatory in the
+                // only sense that matters to a person who installed it. Node resolves the variable at RUN time
+                // instead, where its absence is already handled: the throw below is the same branch that
+                // handles a missing model.
+                const specifier = "@huggingface/transformers";
+                const { pipeline, env } = await import(specifier);
+                // The library resolves `<localModelPath>/<model id>/onnx/...`, which is why the vendored tree
+                // keeps the `Xenova/bge-small-zh-v1.5` directory rather than being flattened.
+                env.localModelPath = this.bundledModel();
+                env.allowRemoteModels = false;
+                this.extractor = await pipeline("feature-extraction", KNOWLEDGE_MODEL, { dtype: "q8" });
+                return this.extractor;
+            }
+            catch (error) {
+                this.failure = error instanceof Error ? error.message : String(error);
+                console.warn(`Super Pi: 语义检索不可用，将只用关键词检索：${this.failure}`);
+                return undefined;
+            }
+            finally {
+                this.loading = undefined;
+            }
+        })();
+        return this.loading;
+    }
+    async embed(texts) {
+        if (!texts.length || !this.enabled())
+            return null;
+        const extractor = await this.load();
+        if (!extractor)
+            return null;
+        try {
+            const output = await extractor(texts, { pooling: "cls", normalize: true });
+            const dimension = output.dims[output.dims.length - 1];
+            return Array.from({ length: output.dims[0] }, (_, row) => Array.from(output.data.slice(row * dimension, (row + 1) * dimension)));
+        }
+        catch (error) {
+            this.failure = error instanceof Error ? error.message : String(error);
+            console.warn(`Super Pi: 生成向量失败，将只用关键词检索：${this.failure}`);
+            return null;
+        }
+    }
+    /** Vectors already stored for one workspace, keyed by document then chunk index. */
+    async read(workspaceId, documentId) {
+        try {
+            const document = JSON.parse(await readFile(this.file(workspaceId, documentId), "utf8"));
+            return Array.isArray(document?.records) ? document : null;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            return null;
+        }
+    }
+    async count(workspaceId) {
+        try {
+            const names = (await readdir(this.folder(workspaceId))).filter(name => name.endsWith(".vec.json"));
+            let total = 0;
+            for (const name of names) {
+                const document = await this.read(workspaceId, name.slice(0, -".vec.json".length));
+                total += document?.records.length ?? 0;
+            }
+            return total;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** Drops a document's vectors. Called whenever its content changes or it is deleted. */
+    async forget(workspaceId, documentId) {
+        this.cache.delete(`${workspaceId}/${documentId}`);
+        await unlink(this.file(workspaceId, documentId)).catch(() => { });
+    }
+    /**
+     * 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, documents) {
+        if (!this.enabled() || !documents.length)
+            return;
+        this.queue.push({ workspaceId, documents });
+        if (this.background)
+            return;
+        this.background = (async () => {
+            while (this.queue.length) {
+                const next = this.queue.shift();
+                try {
+                    for (const document of next.documents) {
+                        const key = `${next.workspaceId}/${document.id}`;
+                        if (this.pending.has(key))
+                            continue;
+                        this.pending.add(key);
+                        const stored = await this.read(next.workspaceId, document.id);
+                        if (stored?.digest === document.digest && stored.records.length === document.chunks.length) {
+                            this.pending.delete(key);
+                            continue;
+                        }
+                        const vectors = [];
+                        for (const chunk of document.chunks) {
+                            const embedded = await this.embed(embedPieces(chunk.text));
+                            if (!embedded) {
+                                this.pending.delete(key);
+                                return;
+                            }
+                            vectors.push({ chunk: chunk.index, values: pool(embedded) });
+                        }
+                        const folder = this.folder(next.workspaceId);
+                        await mkdir(folder, { recursive: true });
+                        const file = this.file(next.workspaceId, document.id), temporary = `${file}.${randomUUID()}.tmp`;
+                        await writeFile(temporary, JSON.stringify({ digest: document.digest, records: vectors }), { encoding: "utf8", mode: 0o600 });
+                        await rename(temporary, file);
+                        this.cache.set(key, new Map(vectors.map(record => [record.chunk, record])));
+                        this.pending.delete(key);
+                    }
+                }
+                catch (error) {
+                    console.warn(`Super Pi: 语义索引失败，将只用关键词检索：${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        })().finally(() => { this.background = undefined; });
+    }
+    /**
+     * 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.
+     */
+    async search(workspaceId, query, keys) {
+        if (!this.enabled() || !keys.length)
+            return null;
+        const documentIds = new Set(keys.map(([, documentId]) => documentId));
+        // First query of the session: read what was indexed last time rather than assuming nothing is.
+        for (const documentId of documentIds) {
+            if (this.cache.has(`${workspaceId}/${documentId}`))
+                continue;
+            const document = await this.read(workspaceId, documentId);
+            if (document)
+                this.cache.set(`${workspaceId}/${documentId}`, new Map(document.records.map(record => [record.chunk, record])));
+        }
+        const available = keys.filter(([, documentId]) => this.cache.get(`${workspaceId}/${documentId}`)?.size);
+        if (!available.length)
+            return null;
+        const vector = await this.embed([query]);
+        if (!vector?.[0])
+            return null;
+        const scores = new Map();
+        for (const [key, documentId] of available) {
+            const chunk = Number(key.split("#")[1]);
+            const record = this.cache.get(`${workspaceId}/${documentId}`)?.get(chunk);
+            if (!record)
+                continue;
+            const similarity = cosine(vector[0], record.values);
+            if (similarity >= MIN_COSINE)
+                scores.set(key, similarity);
+        }
+        return scores;
+    }
+}

package/dist/server/knowledge.d.ts

@@ -0,0 +1,263 @@
+import { VectorIndex } from "./knowledge-vectors.js";
+import type { Store } from "./store.js";
+import type { Conversation } from "./types.js";
+/** One document as it lives on disk: the ORIGINAL text, never the chunks. */
+export type KnowledgeDocument = {
+    id: string;
+    workspaceId: string;
+    title: string;
+    /** Where it came from - a workspace-relative path, or `pasted` for hand-entered text. */
+    source: string;
+    format: string;
+    characters: number;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Content fingerprint, used to recognise an import the user already made.
+     *
+     * WHY IT IS STORED RATHER THAN COMPUTED ON COMPARISON. Deduplication runs inside `add`, which already
+     * reads every document in the workspace; hashing each one's full text there would be O(corpus) on
+     * every import. Storing it turns the check into one string comparison, and a document written by an
+     * older build simply hashes on read (`digestOf`) instead.
+     */
+    digest: string;
+    text: string;
+};
+/** A retrievable slice. `heading` is the nearest preceding markdown heading, so a hit can be cited. */
+export type KnowledgeChunk = {
+    index: number;
+    heading: string;
+    text: string;
+};
+export type KnowledgeHit = {
+    documentId: string;
+    title: string;
+    source: string;
+    heading: string;
+    chunk: number;
+    score: number;
+    text: string;
+};
+/** 1 MB. Big enough for a design doc or a spec, small enough that chunking stays instant. */
+export declare const MAX_DOCUMENT_BYTES: number;
+/** A pasted document rides inside a JSON body, so the request cap leaves room for escaping overhead. */
+export declare const MAX_KNOWLEDGE_REQUEST_BYTES: number;
+/** Per workspace, across every document. A knowledge base is a curated asset, not a file server. */
+export declare const MAX_WORKSPACE_BYTES: number;
+export declare const DEFAULT_RESULT_LIMIT = 6;
+export declare const MAX_RESULT_LIMIT = 20;
+/** What one search may be asked for. `rerank` and `conversation` exist only for the agent's own calls. */
+export type KnowledgeSearch = {
+    limit?: number;
+    /** Re-order with the session's model. Off for the settings preview, which must stay instant. */
+    rerank?: boolean;
+    /** Required by `rerank`: it answers with this conversation's model and workspace. */
+    conversation?: Conversation;
+    signal?: AbortSignal;
+};
+/**
+ * The slice of the runtime the reranker needs, declared structurally.
+ *
+ * Declared here rather than imported so this file does not depend on the spawn machinery that depends
+ * on it - `runtime.ts` imports `KNOWLEDGE_TOOL_NAME` from here, and a type-only back edge into that
+ * module would make the cycle visible in every import graph.
+ */
+export type KnowledgeRuntime = {
+    answer(input: {
+        conversation: Conversation;
+        prompt: string;
+        cwd: string;
+        signal: AbortSignal;
+        knowledgeRerank?: boolean;
+    }): AsyncIterable<string>;
+};
+/**
+ * The first integer array in the model's answer, or null.
+ *
+ * WHY TOLERANT PARSING. The prompt asks for a bare JSON array, and a model that mostly complies will
+ * still sometimes wrap it in a sentence or a code fence. Recovering the array from that is worth doing;
+ * guessing when there is no array at all is not, so anything unparseable is null and the caller keeps
+ * the lexical order.
+ */
+export declare function parseRanking(output: string): number[] | null;
+/** Duplicated as a literal in `agents/super-pi-knowledge/index.ts`, the way `TASK_TOOL_NAME` is. */
+export declare const KNOWLEDGE_TOOL_NAME = "knowledge_search";
+/**
+ * Index terms for one string: CJK bigrams plus Latin words.
+ *
+ * WHY BIGRAMS AND NOT WORDS. Chinese has no spaces, so the word-list tokenizer the rest of this
+ * server uses (`ActiveMemory.search`) returns one enormous "word" for a whole sentence and matches
+ * nothing usefully. Character bigrams need no dictionary and no dependency, and they carry enough
+ * precision that 知识库 and 记忆库 share 识库 but not the whole run - which is what makes a two-term
+ * overlap meaningful rather than accidental.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * The longer-range channel: character TRIGRAMS, for the passage that repeats a phrase verbatim.
+ *
+ * WHY A SECOND GRANULARITY AND NOT JUST BIGRAMS. Bigrams answer "do these share any two-character
+ * run", which is high recall but low precision - two unrelated Chinese sentences collide constantly on
+ * a shared pair. Trigrams only fire on a real three-character overlap, so when the user's question
+ * quotes the document's own wording this channel separates it sharply from the rest of the corpus.
+ * It is scored on its own and fused with the bigram channel rather than merged into it, because the
+ * two answer different questions and a term that is strong for one is usually weak for the other.
+ */
+export declare function tokenizePhrases(text: string): string[];
+/** The identity of a document's CONTENT, independent of its name, its path and when it arrived. */
+export declare function digestOf(text: string): string;
+/**
+ * Splits a document into overlapping chunks, remembering the heading each one sits under.
+ *
+ * WHY OVERLAP. A passage that spans a boundary is the passage most likely to be the answer - the
+ * sentence that defines a term usually starts in one chunk and ends in the next - and a retrieval
+ * system that cut there would return a fragment ending mid-thought. The 150-character tail is
+ * repeated at the head of the next chunk to keep that sentence whole in at least one hit.
+ */
+export declare function chunkDocument(text: string): KnowledgeChunk[];
+export declare class KnowledgeBase {
+    readonly directory: string;
+    private store;
+    private runtime?;
+    private vectors?;
+    private capabilities;
+    private indexes;
+    private serial;
+    constructor(directory: string, store: Store, runtime?: KnowledgeRuntime | undefined, vectors?: VectorIndex | undefined);
+    /** `SUPER_PI_KNOWLEDGE_ENABLED=0` turns the whole feature off, the same way memory turns off. */
+    enabled(): boolean;
+    /** The opaque workspace identity on disk, encoded. Paths never come from the model or the request. */
+    private folder;
+    private file;
+    private requireWorkspace;
+    private locked;
+    /** Metadata only - the caller listing documents must never receive the full text of a workspace. */
+    private summarise;
+    private readAll;
+    private save;
+    private index;
+    /**
+     * Loads (or rebuilds) one workspace's index. Cache miss is the only thing that reads the disk.
+     *
+     * WHY REBUILT PER WORKSPACE AND NOT ONE GLOBAL INDEX. Isolation is a security property here, not a
+     * performance one: a hit may only ever come from the workspace the turn's capability names. A
+     * single shared index would need every search to filter by workspace after scoring, which is one
+     * forgotten filter away from a cross-tenant leak. Separate caches cannot express that mistake.
+     *
+     * WHY THERE IS NO ON-DISK INDEX. Measured, not assumed: rebuilding the index of a 16 MB workspace -
+     * the feature's own capacity cap - costs about 180 ms, once per process. A serialised index would be
+     * larger than the corpus it describes and JSON.parse of it is not reliably cheaper than the
+     * tokenisation, so it would trade a correctness-neutral optimisation for a second on-disk artefact
+     * that can drift from the documents.
+     */
+    private load;
+    private invalidate;
+    list(workspaceId: string): Promise<Array<Omit<KnowledgeDocument, "text">>>;
+    /**
+     * Whether this workspace has any document at all, which is what decides whether the turn mounts the
+     * extension.
+     *
+     * WHY A DIRECTORY LISTING AND NOT `list()`. This runs once per turn, before every spawn. `list()`
+     * would read and parse every document's full text to answer a yes/no question, so a workspace with
+     * a dozen real documents would pay for parsing all of them on every message - including the
+     * catalogue fetch the extension makes the moment it loads. `readdir` answers the same question for
+     * the price of one directory entry, and a name is all this needs.
+     */
+    hasDocuments(workspaceId: string): Promise<boolean>;
+    /**
+     * Adds a document, either from a workspace file or from pasted text.
+     *
+     * WHY THE FILE IS READ HERE AND NOT UPLOADED. A knowledge base is made of documents the person
+     * ALREADY has in their workspace - re-uploading a copy of the file would give the agent a second,
+     * newer version that diverges from the one the workspace serves. The path therefore goes through
+     * the same `resolveInsideRoot` guard the file editor uses, so symlink and `..` escapes are refused
+     * by construction instead of by a check someone has to remember.
+     */
+    add(workspaceId: string, body: {
+        path?: string;
+        title?: string;
+        text?: string;
+    }): Promise<Omit<KnowledgeDocument, "text">>;
+    remove(workspaceId: string, documentId: string): Promise<void>;
+    /**
+     * Scores this workspace's chunks on four independent lexical channels and fuses them.
+     *
+     * WHY LEXICAL AND NOT ONLY EMBEDDINGS. See docs/KNOWLEDGE_BASE.md: the vector channel is fused in
+     * here rather than replacing this one, because each is wrong in a way the other catches. BM25
+     * misses a paraphrase completely; a vector search will happily return the nearest thing at a
+     * confident-looking 0.58 when the answer is not in the knowledge base at all. Summing a normalised
+     * lexical score with a normalised cosine score keeps both signals - and keeps "no hit" reachable.
+     *
+     * WHY NORMALISE PER CHANNEL AND SUM, RATHER THAN RRF. Reciprocal rank fusion is the usual way to
+     * combine ranked lists, and it would be a regression here: it discards score magnitude, so a
+     * passage that matches decisively and one that matches barely would arrive at the same rank and
+     * finish within a couple of percent of each other. The gap between a clear winner and a near miss is
+     * exactly what BM25 was measuring. Each channel is therefore divided by its own best score for this
+     * query, which preserves the shape of that channel's confidence while making the weights comparable.
+     */
+    search(workspaceId: string, query: string, options?: KnowledgeSearch): Promise<KnowledgeHit[]>;
+    /**
+     * Re-orders the candidate pool with the session's own model.
+     *
+     * WHY THIS EXISTS AND WHAT IT IS WORTH. Lexical retrieval ranks on shared characters, so a passage
+     * that answers in different words sits below passages that merely repeat the question's wording -
+     * often below the fold, where the character budget has already cut it off. Reading the candidates
+     * is something the model can already do, so it is asked to pick.
+     *
+     * ITS CEILING, STATED PLAINLY. Reranking can only reorder what the first stage returned. A query
+     * with NO lexical overlap at all never reaches this function, which is why the vector channel and
+     * not this one is what closes the paraphrase gap - see docs/KNOWLEDGE_BASE.md.
+     *
+     * WHY IT FAILS OPEN. Every outcome that is not a clean parse returns the lexical order. A reranker
+     * that made things worse, hung, or answered with prose would degrade the feature invisibly, and a
+     * retrieval layer that is allowed to get worse by being clever is worse than one that is not.
+     */
+    private rerank;
+    /**
+     * Mints a read-only token for one turn. The agent can retrieve, never write: everything a person
+     * puts in a knowledge base is theirs to curate from the settings window.
+     */
+    issue(conversationId: string): string;
+    release(token: string): void;
+    private identity;
+    /** The agent-facing endpoint: a title catalogue and a search. Nothing that writes. */
+    tool(token: string, body: {
+        kind?: string;
+        query?: string;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<{
+        documents: {
+            title: string;
+            source: string;
+            characters: number;
+        }[];
+        hits?: undefined;
+        reranked?: undefined;
+    } | {
+        documents?: undefined;
+        hits: KnowledgeHit[];
+        reranked: boolean;
+    }>;
+    /** The browser-facing endpoint, behind the ordinary access token and same-origin check. */
+    manage(workspaceId: string, body: {
+        action?: string;
+        path?: string;
+        title?: string;
+        text?: string;
+        documentId?: string;
+        query?: string;
+        limit?: number;
+    }): Promise<{
+        hits: KnowledgeHit[];
+        documents: Omit<KnowledgeDocument, "text">[];
+        semantic: import("./knowledge-vectors.js").VectorStatus | null;
+    }>;
+    /**
+     * What the panel shows, including whether semantic retrieval is actually working.
+     *
+     * WHY THE STATE IS WORTH SHOWING. The vector half depends on an optional package and a download from
+     * a host the machine may not reach, and both fail quietly by design. Without this on screen, "the
+     * feature is off" is indistinguishable from "the feature is broken here" - which is the difference
+     * between not wanting a feature and not being able to have it.
+     */
+    private overview;
+}