@evandu/super-pi 0.1.83 → 0.1.85

package/dist/server/application/run-service.js

@@ -377,34 +377,55 @@ export class RunService {
     }
     /**
      * Handles queue snapshot updates from Pi RPC.
+     *
+     * NOW PURELY OBSERVATIONAL, and that is the fix rather than a simplification. It used to INFER a
+     * delivery from a drop in `steering.length` and act on it by deleting the oldest `sending` row - which is
+     * how a steered message could reach the model, be answered at length, and leave no trace in the
+     * transcript the user was reading. A count also cannot say WHICH row, so a snapshot arriving out of
+     * order could delete a message that had not been delivered at all.
+     *
+     * Delivery is now announced by Pi itself, through `onSteerDelivered`, and applied by `streamTurn`. What
+     * is left here is the one thing this event is genuinely good for: telling the browser what Pi holds, at
+     * the moment Pi holds it.
      */
     onPiQueue(conversationId, snapshot) {
         this.broadcaster.broadcast({ type: "pi.queue", conversationId, ...snapshot });
-        const held = this.store.listQueuedMessages(conversationId).filter((message) => message.state === "sending").length;
-        const delivered = held - snapshot.steering.length;
-        if (delivered > 0) {
-            void this.store.dropSendingMessages(conversationId, delivered).then(() => this.broadcaster.broadcastState());
-        }
     }
     /**
-     * Opens a turn by creating user and assistant messages in store.
+     * Opens a turn on a message that is ALREADY IN THE TRANSCRIPT.
+     *
+     * It creates no user message. The words were written when the user pressed send - that is the whole
+     * promise the client is making - so opening a turn can only mark that message as no longer waiting and
+     * put the answer beneath it. `store.openTurnOnMessage` does both in one write, and splices the assistant
+     * message in directly AFTER rather than appending it, which is what keeps a second waiting message below
+     * the reply to the first.
      */
-    async openTurn(conversationId, prompt, images, attachments) {
+    async openTurn(conversationId, messageId) {
         const conversation = this.store.snapshot().conversations.find(item => item.id === conversationId);
         if (!conversation)
             throw new Error("Conversation not found");
         const agent = await this.runtime.agentFor?.(conversation);
         const identity = agent ? { id: agent.id, name: agent.name } : { name: "Pi" };
-        const user = await this.store.addUserMessage(conversationId, prompt ?? "", images, attachments);
-        const assistant = await this.store.beginAssistantMessage(conversationId, identity);
+        const opened = await this.store.openTurnOnMessage(conversationId, messageId, identity);
         this.broadcaster.broadcastState();
-        return { user, assistant };
+        return opened;
     }
     /**
      * Streams a turn via AgentRuntime.
+     *
+     * A TURN CAN CONTAIN MORE THAN ONE ANSWER. When Pi delivers a steered message it announces the
+     * boundary (`message_start`), and everything streamed after it is the answer to THAT message rather than
+     * more of the same one. So this function can be handed a different `assistant` mid-flight: `assistant`
+     * is a parameter rather than a const precisely so one assignment redirects every handler below, each of
+     * which closes over the binding rather than over the value it saw when it was made.
+     *
+     * Before this, a delivered steer's answer was appended to the message that was already streaming. The
+     * model was answering words that existed in no message at all, and the transcript showed a reply with
+     * nothing above it - the user could not find what they had typed, while the agent quoted it back.
      */
-    async streamTurn(conversation, workspace, prompt, assistant, controller, userMessageId, images) {
+    async streamTurn(conversation, workspace, prompt, assistantMessage, controller, userMessageId, images, agentIdentity) {
         this.extensionUiService.cancelPendingUi(conversation.id, "expired");
+        let assistant = assistantMessage;
         let toolCalls = [];
         let pendingTools = Promise.resolve();
         // Live events are independent from durable checkpoints. Persisting every token made the stdout
@@ -615,6 +636,51 @@ export class RunService {
                 return;
             enqueueTools("a tool call outcome", () => this.store.settleToolCall(conversation.id, assistant.id, index, { status: call.status, durationMs: call.durationMs, ...(call.result ? { result: call.result } : {}) }));
         };
+        /**
+         * PI DELIVERED A STEERED MESSAGE. Everything it streams from here belongs to that message, not to the
+         * one this turn opened with.
+         *
+         * The work goes on the SAME lane as tool writes, which is what makes it safe: the delta handler above
+         * awaits that lane before its first line, so by the time another token is handled the reassignment
+         * below has already happened. Running it inline instead would put a `store` round trip in the middle
+         * of the stdout drain, which is precisely the latency the streaming lane exists to avoid.
+         *
+         * EVERY PER-MESSAGE COUNTER IS RESET, and each for its own reason. `spoken` and `thought` are OFFSETS
+         * WITHIN ONE MESSAGE - the `at` a tool call anchors at, and where a thinking block begins - so
+         * carrying them across would anchor this message's first tool call halfway down the previous answer.
+         * `rows` numbers tool blocks within a message, so it must restart at zero or the new message's first
+         * block is numbered after the old one's. The two maps bind rows and call ids to those numbers and are
+         * cleared rather than reassigned for the same reason. `thinkingBlock` continues numbering on purpose:
+         * it is a global fold sequence, and restarting it would make the browser render two folds numbered 0.
+         */
+        const onSteerDelivered = () => {
+            enqueueTools("a steer being delivered", async () => {
+                const previous = assistant;
+                // Checkpoint first: the message being left behind is complete - Pi drains steering at a turn
+                // boundary - and this is the last chance to write it durably with the lane it belongs to.
+                await this.store.checkpointMessage(conversation.id, previous.id);
+                const delivered = await this.store.deliverWaitingMessage(conversation.id, agentIdentity);
+                // NOTHING TO DELIVER MEANS NOTHING TO SPLIT. Pi may announce a user `message_start` that this
+                // server never handed it - the prompt that opened the turn is the obvious case - and inventing an
+                // assistant message for one of those would open an empty bubble before every single turn. The
+                // question "was anything `sending`?" is the server's own state, not something the event decides,
+                // which is the same reason the delivery is matched by position rather than by text.
+                if (!delivered)
+                    return [];
+                const next = delivered.assistant;
+                this.broadcaster.broadcastState();
+                assistant = next;
+                spoken = 0;
+                thought = 0;
+                thinkingActive = false;
+                thinkingInterrupted = true;
+                rows = 0;
+                rowByToolCallId.clear();
+                preparingRows.clear();
+                toolCalls = [];
+                return [];
+            });
+        };
         try {
             for await (const delta of this.runtime.answer({
                 conversation,
@@ -623,6 +689,7 @@ export class RunService {
                 cwd: workspace.path,
                 host: this.extensionUiService.createHost(conversation.id),
                 onPiQueue: (snapshot) => this.onPiQueue(conversation.id, snapshot),
+                onSteerDelivered,
                 onUserEntry: (entryId) => this.store.setMessagePiEntryId(conversation.id, userMessageId, entryId),
                 onSessionFile: (path) => this.store.setConversationPiSessionFile(conversation.id, path),
                 onToolCall,
@@ -664,12 +731,19 @@ export class RunService {
                 },
                 images,
             })) {
+                // AWAITED FIRST, BEFORE THE LIVE WRITE, because `assistant` may be reassigned by a steer
+                // delivery that is still in flight on this same lane. It used to be awaited after
+                // `appendAssistantDeltaLive`, which is harmless for tool writes - a tool write never changes
+                // which message text belongs to - and is NOT harmless for a split: a token would land in the
+                // message that just stopped being answered, in front of the reader, and then the split would
+                // publish a new message underneath it. One `await` at the top covers both, and costs nothing:
+                // the lane is empty most of the time.
+                await pendingTools;
                 this.store.appendAssistantDeltaLive(conversation.id, assistant.id, delta);
                 spoken += delta.length;
                 // Tool events are structural transcript boundaries. Publish any boundary Pi announced before
                 // this text before publishing the text itself; this is a handful of writes per call, never one
                 // write per token, and preserves the event order a reconnecting client reconstructs.
-                await pendingTools;
                 this.broadcaster.broadcast({ type: "message.delta", conversationId: conversation.id, messageId: assistant.id, delta });
                 scheduleCheckpoint();
             }
@@ -710,29 +784,33 @@ export class RunService {
         }
     }
     /**
-     * Loops running turns for as long as queued follow-ups exist.
+     * Loops running turns for as long as waiting messages exist.
+     *
+     * The FIRST message is passed in rather than opened here, because it was written into the transcript
+     * before this method was called: the user pressed send, and their words were on screen in that frame. The
+     * loop then does the same thing for each message after it - take the next waiting one, open its turn,
+     * stream it - which is why the two cases are expressed identically and cannot drift apart.
      */
-    async runConversationTurns(conversation, workspace, prompt, controller, initialImages, initialAttachments) {
+    async runConversationTurns(conversation, workspace, prompt, controller, firstMessageId, initialImages) {
         try {
-            const opened = await this.openTurn(conversation.id, prompt, initialImages, initialAttachments);
-            await this.streamTurn(conversation, workspace, prompt, opened.assistant, controller, opened.user.id, initialImages);
+            const agent = await this.runtime.agentFor?.(conversation);
+            const identity = agent ? { id: agent.id, name: agent.name } : { name: "Pi" };
+            const opened = await this.openTurn(conversation.id, firstMessageId);
+            await this.streamTurn(conversation, workspace, prompt, opened.assistant, controller, opened.user.id, initialImages, identity);
             for (;;) {
                 if (controller.signal.aborted)
                     break;
-                const next = await this.store.takeNextQueuedMessage(conversation.id);
+                // Taken AND opened, in that order, by two separate writes. The take is what bounds this loop -
+                // every pass strictly shrinks the waiting set - and it is what makes a crash honest, because a
+                // server that dies between the two has a message that is neither waiting nor answered, and the
+                // next boot leaves it alone rather than re-sending words Pi may already have seen.
+                const next = await this.store.takeNextWaitingMessage(conversation.id);
                 if (!next)
                     break;
+                const followUp = await this.store.openTurnOnMessage(conversation.id, next.id, identity);
                 this.broadcaster.broadcastState();
-                let followUp;
-                try {
-                    followUp = await this.openTurn(conversation.id, next.content, next.images, next.attachments);
-                }
-                catch (error) {
-                    await this.store.enqueueMessage(conversation.id, next.content, next.images, next.attachments);
-                    throw error;
-                }
                 const current = this.turnContext(conversation.id).conversation;
-                await this.streamTurn(current, workspace, next.content, followUp.assistant, controller, followUp.user.id, next.images);
+                await this.streamTurn(current, workspace, next.content, followUp.assistant, controller, followUp.user.id, next.images, identity);
             }
         }
         finally {
@@ -742,22 +820,30 @@ export class RunService {
     /**
      * Enqueues or starts execution for a user message.
      */
-    async enqueueAndRun(conversationId, content, images, attachments) {
-        // The run itself must not occupy the mutation lane: a second send needs to observe the active run
-        // and enqueue immediately while the first model turn is still streaming.
+    async enqueueAndRun(conversationId, content, images, attachments, clientId) {
         this.memory?.cancel(conversationId);
         const trimmed = content.trim();
         const validImages = Array.isArray(images) && images.length > 0 ? images : undefined;
         if (!trimmed && !validImages?.length)
             return;
         const { conversation, workspace } = this.turnContext(conversationId);
+        // THE MESSAGE IS WRITTEN FIRST, ALWAYS, AND THE RUN GUARD IS ASKED SECOND.
+        //
+        // This ordering is the fix for a bug that was not a slip but a consequence: the words used to be
+        // written by `openTurn`, at the moment the turn started, so a send into a running turn had nowhere to
+        // put them until a turn began. The browser was therefore told to draw nothing on a send-while-busy,
+        // and the composer emptied into silence for as long as the round trip took - a state the reader reads
+        // as "it did not send", not as "it is queued".
+        //
+        // Written first, the message is in the transcript in the same frame, whether it starts a turn or
+        // waits for one, and the guard below only decides WHICH. It also means the client-supplied `clientId`
+        // is attached to a real message either way, so there is nothing to reconcile afterwards.
+        const message = await this.store.addUserMessage(conversationId, trimmed, validImages, attachments, { clientId, delivery: "waiting" });
+        this.broadcaster.broadcastState();
         // Claim the run slot synchronously (no await between has() and set()) so two
         // rapid sends can never both pass the guard and start concurrent turns.
-        if (this.activeRuns.has(conversation.id)) {
-            await this.store.enqueueMessage(conversation.id, trimmed, validImages, attachments);
-            this.broadcaster.broadcastState();
+        if (this.activeRuns.has(conversation.id))
             return;
-        }
         const controller = new AbortController();
         this.activeRuns.set(conversation.id, controller);
         try {
@@ -770,7 +856,7 @@ export class RunService {
                 }
             }
             const expanded = await expandAtReferences(this.store, workspace, trimmed);
-            await this.runConversationTurns(conversation, workspace, expanded, controller, validImages, attachments);
+            await this.runConversationTurns(conversation, workspace, expanded, controller, message.id, validImages);
             await this.store.setStatus(conversation.id, controller.signal.aborted ? "stopped" : "completed");
         }
         catch (error) {
@@ -786,11 +872,11 @@ export class RunService {
     /**
      * Steers a queued message into the in-flight turn.
      */
-    async steer(conversationId, queueId) {
-        return this.serializeConversation(conversationId, () => this.steerUnsafe(conversationId, queueId));
+    async steer(conversationId, messageId) {
+        return this.serializeConversation(conversationId, () => this.steerUnsafe(conversationId, messageId));
     }
-    /** Starts a chosen saved message only when the conversation is idle. */
-    async sendQueued(conversationId, queueId) {
+    /** Starts a chosen waiting message as the next turn, only when the conversation is idle. */
+    async sendQueued(conversationId, messageId) {
         const waitForStop = async () => {
             // A stop broadcasts `stopped` before the previous run has finished its finally block. Allow that
             // short cleanup window; a click on the newly visible button must not race the old run slot.
@@ -803,64 +889,107 @@ export class RunService {
         return this.serializeConversation(conversationId, async () => {
             if (this.activeRuns.has(conversationId))
                 throw new Error("当前轮仍在运行；停止或等待它结束后再发送这条消息");
-            const queued = await this.store.takeQueuedMessage(conversationId, queueId);
-            const userMessageCount = this.store.snapshot().conversations.find((item) => item.id === conversationId)?.messages.filter((item) => item.role === "user").length ?? 0;
-            // Claim the run immediately, then release the command lane. Waiting for the whole model turn here
-            // would block every later queue action from this socket until the answer completes.
-            void this.enqueueAndRun(conversationId, queued.content, queued.images).catch(async (error) => {
-                // Once the turn has a user message it is already in the transcript. Requeue only a preflight
-                // failure, or the same prompt would be shown as both sent and waiting to be sent again.
-                const sent = (this.store.snapshot().conversations.find((item) => item.id === conversationId)?.messages.filter((item) => item.role === "user").length ?? 0) > userMessageCount;
-                if (!sent)
-                    await this.store.enqueueMessage(conversationId, queued.content, queued.images);
+            // Claim the run slot BEFORE releasing the command lane, then start the turn from the message that
+            // is already in the transcript. It is not re-sent through `enqueueAndRun`, which would write a
+            // SECOND copy of these words: the whole point of this action is that the user is sending a message
+            // they can already see sitting in their conversation.
+            const controller = new AbortController();
+            this.activeRuns.set(conversationId, controller);
+            try {
+                const { conversation, workspace } = this.turnContext(conversationId);
+                const agent = await this.runtime.agentFor?.(conversation);
+                const identity = agent ? { id: agent.id, name: agent.name } : { name: "Pi" };
+                const opened = await this.store.openTurnOnSpecificMessage(conversationId, messageId, identity);
                 this.broadcaster.broadcastState();
-                console.warn(`Super Pi: explicit queued send failed: ${error instanceof Error ? error.message : String(error)}`);
-            });
-            this.broadcaster.broadcastState();
+                await this.runConversationTurns(conversation, workspace, opened.user.content, controller, opened.user.id, opened.user.images);
+                await this.store.setStatus(conversationId, controller.signal.aborted ? "stopped" : "completed");
+            }
+            catch (error) {
+                await this.store.setStatus(conversationId, "failed");
+                // A preflight failure must put the words BACK where the user can see them. Re-adding them would
+                // duplicate the message that is still in the transcript, so this only re-marks the one that is
+                // there - which is what makes "the send failed, your message is still waiting" a true statement.
+                await this.store.releaseWaitingMessage(conversationId, messageId).catch(() => undefined);
+                throw error;
+            }
+            finally {
+                this.activeRuns.delete(conversationId);
+                this.extensionUiService.cancelPendingUi(conversationId, "expired");
+                this.broadcaster.broadcastState();
+            }
         });
     }
-    async steerUnsafe(conversationId, queueId) {
-        if (!this.runtime.steer) {
-            throw new Error("当前运行时没有插队能力，无法把排队消息插到正在运行的这轮里");
+    async steerUnsafe(conversationId, messageId) {
+        // MOVED TO THE FRONT FIRST, ALWAYS - AND THE MOVE IS BEST-EFFORT.
+        //
+        // The move is what makes "插到最前" mean what it says rather than leaving a flag nobody can explain.
+        // But the move CAN fail, and the case where it fails is a real one a person causes on purpose: two
+        // steers in a row. The first message is already in Pi's stdin, nothing can be placed in front of it,
+        // and the second click means "and this one too". Refusing it would break a capability the old
+        // implementation had and would leave the person with a message that cannot be sent at all until the
+        // turn ends - which is the thing they were trying to avoid by clicking twice.
+        //
+        // So the refusal is swallowed HERE and only here: being second in Pi's own FIFO queue is still a jump
+        // past everything else that is merely waiting, which is what the second click was asking for. The
+        // `message.reorder` command does not swallow it, because a button that says 「插到最前」 and silently
+        // did not move anything is the promise this refactor exists to stop making.
+        try {
+            await this.store.reorderWaitingMessage(conversationId, messageId, 0);
         }
+        catch {
+            // Nothing to do: the claim below is what actually delivers it, and Pi takes steers in order.
+        }
+        this.broadcaster.broadcastState();
+        if (!this.runtime.steer)
+            return;
         // A running conversation may be in the tiny hand-off window after Pi ended but before this service
-        // opens the next queued turn. Priority delivery has the same user meaning in both cases, so reserve
-        // the message for the next turn instead of turning a successful click into an implementation error.
-        if (this.runtime.canSteer && !this.runtime.canSteer(conversationId)) {
-            await this.store.prioritizeQueuedMessage(conversationId, queueId);
-            this.broadcaster.broadcastState();
+        // opens the next waiting message. The message is at the front of the waiting set, so there is nothing
+        // left to promise and nothing to report as an error - the click did what it was for either way.
+        if (this.runtime.canSteer && !this.runtime.canSteer(conversationId))
             return;
-        }
-        const claimed = await this.store.claimQueuedMessage(conversationId, queueId);
+        const claimed = await this.store.claimWaitingMessage(conversationId, messageId);
         this.broadcaster.broadcastState();
         try {
-            const disposition = await this.runtime.steer(conversationId, claimed.content, claimed.images);
-            if (disposition === "handled") {
-                await this.store.dropSendingMessages(conversationId, 1);
-            }
+            await this.runtime.steer(conversationId, claimed.content, claimed.images);
         }
         catch (error) {
-            if (error instanceof SteerUnavailableError) {
-                await this.store.releaseQueuedMessage(claimed.id);
-                await this.store.prioritizeQueuedMessage(conversationId, claimed.id);
-                this.broadcaster.broadcastState();
+            // Back to waiting in every failure case, including the "Pi is gone" one. It is still at the front of
+            // whatever is waiting, which is the most this could promise once the transport has refused.
+            await this.store.releaseWaitingMessage(conversationId, claimed.id);
+            this.broadcaster.broadcastState();
+            if (error instanceof SteerUnavailableError)
                 return;
-            }
-            await this.store.releaseQueuedMessage(claimed.id);
             throw error;
         }
-        this.broadcaster.broadcastState();
     }
     /**
-     * Cancels a queued message.
+     * Withdraws a waiting message.
      */
-    async cancelQueued(conversationId, queueId) {
-        return this.serializeConversation(conversationId, () => this.cancelQueuedUnsafe(conversationId, queueId));
+    async cancelQueued(conversationId, messageId) {
+        return this.serializeConversation(conversationId, () => this.cancelQueuedUnsafe(conversationId, messageId));
     }
-    async cancelQueuedUnsafe(conversationId, queueId) {
-        await this.store.cancelQueuedMessage(conversationId, queueId);
+    async cancelQueuedUnsafe(conversationId, messageId) {
+        await this.store.cancelWaitingMessage(conversationId, messageId);
         this.broadcaster.broadcastState();
     }
+    /**
+     * Rewrites a waiting message, in place, where the user can see it change.
+     */
+    async editQueued(conversationId, messageId, content) {
+        return this.serializeConversation(conversationId, async () => {
+            await this.store.editWaitingMessage(conversationId, messageId, content);
+            this.broadcaster.broadcastState();
+        });
+    }
+    /**
+     * Moves a waiting message within the waiting set.
+     */
+    async reorderQueued(conversationId, messageId, toIndex) {
+        return this.serializeConversation(conversationId, async () => {
+            await this.store.reorderWaitingMessage(conversationId, messageId, toIndex);
+            this.broadcaster.broadcastState();
+        });
+    }
     /**
      * Dispatches a subagent from client command (human dispatch).
      */

package/dist/server/command-handler.js

@@ -158,19 +158,31 @@ export class CommandHandler {
             if (this.conversationService.isReverting(command.conversationId)) {
                 throw new Error("正在撤回上一条消息，Pi 的历史还没截断完成，请等撤回结束后再发送。");
             }
-            await this.runService.enqueueAndRun(command.conversationId, command.content, command.images);
+            // `attachments` was dropped here while the send path grew it, so a message carrying a skill
+            // attachment lost it on arrival - the browser drew the attachment, the transcript never had it, and
+            // the model was handed the bare prompt. Forwarded now because this is the one line that carries
+            // every field of the send.
+            await this.runService.enqueueAndRun(command.conversationId, command.content, command.images, command.attachments, command.clientId);
             return;
         }
         if (command.type === "message.steer") {
-            await this.runService.steer(command.conversationId, command.queueId);
+            await this.runService.steer(command.conversationId, command.messageId);
             return;
         }
         if (command.type === "message.sendQueued") {
-            await this.runService.sendQueued(command.conversationId, command.queueId);
+            await this.runService.sendQueued(command.conversationId, command.messageId);
             return;
         }
         if (command.type === "message.cancel") {
-            await this.runService.cancelQueued(command.conversationId, command.queueId);
+            await this.runService.cancelQueued(command.conversationId, command.messageId);
+            return;
+        }
+        if (command.type === "message.edit") {
+            await this.runService.editQueued(command.conversationId, command.messageId, command.content);
+            return;
+        }
+        if (command.type === "message.reorder") {
+            await this.runService.reorderQueued(command.conversationId, command.messageId, command.toIndex);
             return;
         }
         if (command.type === "message.revert") {

package/dist/server/http-server.js

@@ -9,6 +9,7 @@ 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 { packageUpdateArgs } from "./update.js";
 const MIME_TYPES = {
     ".css": "text/css; charset=utf-8",
@@ -164,6 +165,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,7 +194,12 @@ 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;
         }
@@ -409,6 +429,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";
@@ -75,6 +77,10 @@ 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);
+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 +154,7 @@ const execService = new ExecService((event) => broadcaster.broadcast(event), (se
 runService.setExecService(execService);
 const serverContext = {
     memory,
+    knowledge,
     paths,
     store,
     runtime,