@evandu/super-pi 0.1.130 → 0.1.131

package/dist/server/runtime.js

@@ -2,7 +2,9 @@ import { spawn } from "node:child_process";
 import { RpcChannel } from "./rpc-channel.js";
 export { RpcChannel } from "./rpc-channel.js";
 import { randomUUID } from "node:crypto";
-import { KNOWLEDGE_TOOL_NAME } from "./knowledge.js";
+import { KNOWLEDGE_IMPORT_TOOL_NAME, KNOWLEDGE_TOOL_NAME } from "./knowledge.js";
+import { DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME } from "./documents.js";
+import { WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME } from "./web.js";
 import { existsSync } from "node:fs";
 import { mkdir, stat } from "node:fs/promises";
 import { forkSessionFile, truncateSessionFile } from "./session-repository.js";
@@ -22,6 +24,7 @@ import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_END
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
 import { describeToolCall, describeToolCallArgs, describeToolCallInProgress, extractPartialResultText, extractToolResultText, readQuestionCall } from "./tool-calls.js";
+import { InlineThinkingSplitter, stripInlineThinking } from "./inline-thinking.js";
 import { toolTargetPath } from "./file-changes.js";
 const traceLatency = (conversationId, phase, startedAt, extra = "") => {
     if (process.env.SUPER_PI_TRACE_LATENCY !== "1")
@@ -238,6 +241,13 @@ export const catalogKey = (selection) => (selection?.provider && selection.model
 export function taskExtensionPath(from = import.meta.dirname) {
     return resolve(from, "../../agents/super-pi-task/index.ts");
 }
+/**
+ * The document extension's file, resolved the same way the task extension's is: two `..` segments
+ * from `import.meta.dirname` reach the repository root both after `tsc -b` and under `tsx watch`.
+ */
+export function documentExtensionPath(from = import.meta.dirname) {
+    return resolve(from, "../../agents/super-pi-documents/index.ts");
+}
 /** Bridges a Pi session to Super Pi through Pi's documented JSONL RPC protocol. */
 /**
  * The tool's name as far as the stream has revealed it so far, or an empty string while the model is
@@ -356,6 +366,8 @@ export class PiRpcRuntime {
     modelEpoch = 0;
     /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
     warnedMissingExtension = false;
+    /** Latches the "the document extension is missing" warning, for the same reason. */
+    warnedMissingDocumentExtension = false;
     /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
     warnedMissingSdk = false;
     /**
@@ -541,6 +553,30 @@ export class PiRpcRuntime {
         }
         return ["--extension", path];
     }
+    /**
+     * The document extension's spawn argument.
+     *
+     * IT IS MOUNTED UNCONDITIONALLY, unlike the knowledge extension. The knowledge extension is only
+     * worth mounting when the workspace HAS documents, because its tool returns nothing otherwise; the
+     * document tools are about the files in the workspace, and a workspace with no PDF in it is exactly
+     * the workspace where an agent might be asked to WRITE one.
+     *
+     * The endpoint is the gate: without it the extension returns without registering anything, so a
+     * runtime with no document endpoint mounts nothing rather than a tool whose every call fails.
+     */
+    documentExtensionArgs() {
+        if (!this.options.documentsEndpoint)
+            return [];
+        const path = documentExtensionPath();
+        if (!existsSync(path)) {
+            if (!this.warnedMissingDocumentExtension) {
+                this.warnedMissingDocumentExtension = true;
+                console.warn(`PiRpcRuntime: ${path} does not exist, so the primary agent cannot read or write PDF, Word and Excel files.`);
+            }
+            return [];
+        }
+        return ["--extension", path];
+    }
     /**
      * The five values the extension reads out of its own environment. See `task-tool.ts` for why they are
      * written out on both sides rather than imported.
@@ -579,6 +615,14 @@ export class PiRpcRuntime {
             [WORKFLOW_ENDPOINT_ENV]: this.options.workflowEndpoint ?? "",
             SUPER_PI_QUESTION_ENDPOINT: this.options.questionEndpoint ?? "",
             SUPER_PI_TOOLS_ENDPOINT: this.options.toolsEndpoint ?? "",
+            // The document tools' endpoint and the conversation they act for. The CREDENTIAL is not here:
+            // it is the session's own capability, which the session pool adds to this environment when the
+            // session is born, and the document extension reads that same value. Minting a second
+            // credential for the same session would be a second thing to rotate and a second thing to
+            // forget to release.
+            SUPER_PI_DOCUMENTS_ENDPOINT: this.options.documentsEndpoint ?? "",
+            SUPER_PI_DOCUMENTS_CONVERSATION: conversationId,
+            SUPER_PI_WEB_ENDPOINT: process.env.SUPER_PI_WEB_ENDPOINT ?? "",
         };
     }
     /**
@@ -590,8 +634,7 @@ export class PiRpcRuntime {
      * here. A session lives for many turns, so its credential is minted when the session is created (see
      * `PiSessionPool.acquire`) and the server separately requires a running turn for it to be usable.
      */
-    async oneShotExtensionEnv(conversationId) {
-        const capability = mintCapability(conversationId);
+    async oneShotExtensionEnv(conversationId, capability) {
         return {
             ...(await this.taskExtensionEnv(conversationId)),
             [TASK_CAPABILITY_ENV]: capability,
@@ -1016,10 +1059,65 @@ export class PiRpcRuntime {
         if (this.memory)
             names.push("memory", "skill_manage", "session_search");
         if (this.knowledge)
-            names.push(KNOWLEDGE_TOOL_NAME);
+            names.push(KNOWLEDGE_TOOL_NAME, KNOWLEDGE_IMPORT_TOOL_NAME);
+        if (process.env.SUPER_PI_WEB_ENDPOINT)
+            names.push(WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME);
+        // The document tools are named whenever the endpoint is configured, because that is what decides
+        // whether the extension registers them. An agent that declares `tools: {"*": false, read: true}`
+        // would otherwise get a loaded-but-undeclared tool - broken with no error to explain it.
+        if (this.options.documentsEndpoint)
+            names.push(DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME);
         return names;
     }
+    /**
+     * A TURN, WITH THE REASONING TAKEN OUT OF THE ANSWER.
+     *
+     * This is the ONE place every turn passes through, whichever path it runs on - the persistent
+     * session or a one-shot process - so it is where the model's own text is read once and read
+     * properly.
+     *
+     * WHAT IT DOES. A model that has no reasoning channel answers in one stream of text and marks its
+     * thinking up inside it with `<think>…</think>`. Pi's adapter passes that through as ordinary
+     * text, because Pi only knows the four reasoning FIELDS a provider can use and a tag is not one
+     * of them. Left alone, the reasoning would be drawn as part of the answer, unlabelled, with the
+     * tags in it.
+     *
+     * WHY IT IS HERE AND NOT IN THE USER'S `models.json`. The alternative is to tell every reader to
+     * go and set a vendor-specific switch in a file Super Pi owns but Pi reads. A user who never
+     * hears of it sees a broken transcript and has no way to find out why. Super Pi reads the tags
+     * itself, for every provider, so the transcript reads the same way whichever endpoint is behind
+     * it - and the reasoning goes where the reasoning goes: into a thinking block, over the same
+     * channel Pi's own reasoning events use, so the fold, the live indicator and the persisted
+     * transcript all work without knowing where the reasoning came from.
+     */
     async *answer(input) {
+        const splitter = new InlineThinkingSplitter();
+        for await (const chunk of this.answerTurn(input)) {
+            for (const segment of splitter.push(chunk)) {
+                if (segment.kind === "text")
+                    yield segment.text;
+                else if (segment.kind === "thinking")
+                    input.onThinking?.(segment.text);
+                else
+                    input.onThinkingEnd?.();
+            }
+        }
+        // THE END OF THE TURN. A model that was still thinking when the turn ended leaves an unclosed
+        // region behind, and it belongs in the block rather than in the answer.
+        for (const segment of splitter.flush()) {
+            if (segment.kind === "text")
+                yield segment.text;
+            else if (segment.kind === "thinking")
+                input.onThinking?.(segment.text);
+            else
+                input.onThinkingEnd?.();
+        }
+    }
+    /**
+     * THE TURN ITSELF, on whichever path it runs. See `answer`, which is the seam the reasoning is
+     * separated at.
+     */
+    async *answerTurn(input) {
         // The one-shot paths keep their own child process, and they are NOT the same thing as a conversation
         // turn: a memory review and a knowledge reranker have their own ids, their own tool sets and their own
         // lifetimes, and folding them into a conversation's session would give them that conversation's
@@ -1111,15 +1209,30 @@ export class PiRpcRuntime {
         const memoryToken = memoryEnabled ? this.memory.issue(validationId, { review: memoryReview }) : undefined;
         const memoryExtension = resolve(import.meta.dirname, "../../agents/super-pi-memory/index.ts");
         const memoryArgs = memoryEnabled ? ["--extension", memoryExtension] : [];
-        // Mounted only when the workspace actually HAS documents. An empty knowledge base would otherwise
-        // cost a catalogue round trip and one declared tool on every turn to tell the model there is
-        // nothing to find. Review turns never mount it: a background reflection has no business
-        // retrieving documents it was not asked about, and its `--tools` line is a closed list. A
-        // reranker never mounts it either - it must not be able to call the search it is ranking.
-        const knowledgeEnabled = !memoryReview && !knowledgeRerank && !!this.knowledge && await this.knowledge.hasDocuments(conversation.workspaceId).catch(() => false);
+        // Mounted on EVERY primary turn, empty base or not. The old condition (hasDocuments) saved a
+        // catalogue round trip and a tool slot when there was nothing to find, but it also made the one
+        // workspace where a user most plausibly says 「把这些文件加入知识库」 the one workspace whose
+        // agent had no import tool. knowledge_search on an empty base answers no hits and costs nothing;
+        // knowledge_import has to exist before the first document does. Review turns never mount it: a
+        // background reflection has no business reading or writing documents, and its `--tools` line is a
+        // closed list. A reranker never mounts it either - it must not be able to call what it ranks.
+        const knowledgeEnabled = !memoryReview && !knowledgeRerank && !!this.knowledge && this.knowledge.enabled();
         const knowledgeToken = knowledgeEnabled ? this.knowledge.issue(conversation.id) : undefined;
         const knowledgeExtension = resolve(import.meta.dirname, "../../agents/super-pi-knowledge/index.ts");
         const knowledgeArgs = knowledgeEnabled ? ["--extension", knowledgeExtension] : [];
+        const webExtension = resolve(import.meta.dirname, "../../agents/super-pi-web/index.ts");
+        const webEnabled = !memoryReview && !knowledgeRerank && existsSync(webExtension) && !!process.env.SUPER_PI_WEB_ENDPOINT;
+        const webArgs = webEnabled ? ["--extension", webExtension] : [];
+        // The document tools are mounted for every ordinary turn, and NOT for a review or a rerank: a
+        // background reflection has no business reading a PDF it was not asked about, and a reranker
+        // must not be able to reach the tools it is ranking.
+        const documentsEnabled = !memoryReview && !knowledgeRerank && this.documentExtensionArgs().length > 0;
+        const documentArgs = documentsEnabled ? this.documentExtensionArgs() : [];
+        // THE ONE-SHOT CHILD'S CREDENTIAL, MINTED ONCE. The server holds ONE capability per
+        // conversation, so minting a second one for the same conversation would replace the first and
+        // leave the task dispatch holding a token the server has already forgotten. Both the task
+        // extension and the document extension therefore share this one value.
+        const oneShotCapability = (extensionArgs.length || documentsEnabled || webEnabled) ? mintCapability(conversation.id) : undefined;
         // BOTH extension tools, or neither. Naming one while the other goes unmentioned would be a lie in a
         // different direction: Pi filters its registry through `--tools`, so an agent that declares
         // `tools: {"*": false, read: true}` gets whichever of the two is on this line and silently not the
@@ -1132,13 +1245,13 @@ export class PiRpcRuntime {
         // allowlist and naming a tool Pi has not registered would change the spawn line for every other
         // mode. The prompt asks for a bare JSON array and nothing else; if the model spends a turn on a
         // tool call anyway the reranker times out and falls back to the lexical order.
-        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, "question", "tool_register"] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME] : [])] });
+        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, "question", "tool_register"] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME, KNOWLEDGE_IMPORT_TOOL_NAME] : []), ...(documentsEnabled ? [DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME] : []), ...(webEnabled ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME] : [])] });
         // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
         // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
         if (!this.pi.found)
             throw new Error(this.pi.reason);
         // npm exposes global CLIs as .cmd shims on Windows; Node requires a shell to launch those shims.
-        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id, ...extensionArgs, ...memoryArgs, ...knowledgeArgs, ...agentArgs], {
+        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id, ...extensionArgs, ...memoryArgs, ...knowledgeArgs, ...documentArgs, ...webArgs, ...agentArgs], {
             cwd: childCwd,
             stdio: ["pipe", "pipe", "pipe"],
             shell: process.platform === "win32",
@@ -1146,13 +1259,26 @@ export class PiRpcRuntime {
             // every turn would silently replace the child's environment with whatever THIS process has at
             // spawn time. Inheriting is what an omitted `env` already does, so the two paths differ in nothing
             // but the four documented additions.
-            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled) ? { env: { ...process.env, ...(extensionArgs.length ? await this.oneShotExtensionEnv(conversation.id) : {}), ...(memoryEnabled ? {
+            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled || documentsEnabled || webEnabled) ? { env: { ...process.env, ...(oneShotCapability ? await this.oneShotExtensionEnv(conversation.id, oneShotCapability) : {}), ...(memoryEnabled ? {
                         SUPER_PI_MEMORY_ENDPOINT: process.env.SUPER_PI_MEMORY_ENDPOINT,
                         SUPER_PI_MEMORY_TOKEN: memoryToken,
                         SUPER_PI_MEMORY_REVIEW: memoryReview ? "1" : "0",
                     } : {}), ...(knowledgeEnabled ? {
                         SUPER_PI_KNOWLEDGE_ENDPOINT: process.env.SUPER_PI_KNOWLEDGE_ENDPOINT,
                         SUPER_PI_KNOWLEDGE_TOKEN: knowledgeToken,
+                    } : {}), ...(documentsEnabled ? {
+                        SUPER_PI_DOCUMENTS_ENDPOINT: this.options.documentsEndpoint ?? "",
+                        // The document tools carry the SESSION's capability, the same credential the task dispatch
+                        // uses: it proves which conversation is asking, and the server checks that the turn is
+                        // running. The conversation id travels with it, because the workspace is derived from the
+                        // conversation and never from the request.
+                        //
+                        // IT IS THE SAME VALUE THE TASK EXTENSION GETS. A one-shot child has no session to borrow a
+                        // credential from, so the token is minted for the turn - and minted ONCE, because the server
+                        // holds one capability per conversation and a second mint would replace the first in the
+                        // map, leaving the task dispatch holding a token the server had already forgotten.
+                        SUPER_PI_DOCUMENTS_TOKEN: oneShotCapability ?? "",
+                        SUPER_PI_DOCUMENTS_CONVERSATION: conversation.id,
                     } : {}) } } : {}),
         });
         const channel = new RpcChannel(child);
@@ -2070,7 +2196,11 @@ export class PiRpcRuntime {
             // A model asked for "only the title" still wraps it now and then. Stripping the wrappers is not
             // cosmetic: without it a leading quote or a `Title:` prefix becomes the first characters of every
             // title in the sidebar.
-            const title = text
+            //
+            // AND THE MODEL'S OWN REASONING IS STRIPPED FIRST, because a model that thinks inside its
+            // answer puts the thinking in front of the title: the title would then start with `<think>`,
+            // and the sidebar would show the markup of a reasoning trace where a label belongs.
+            const title = stripInlineThinking(text)
                 .replace(/^\s*(?:title|标题)\s*[:：]\s*/iu, "")
                 .replace(/^[`"'“”‘’「『]+/u, "")
                 .replace(/[`"'“”‘’」』]+$/u, "")
@@ -2125,9 +2255,13 @@ export class PiRpcRuntime {
             }
             if (!settled)
                 throw new Error(`模型在 ${Math.round(input.timeoutMs / 1000)} 秒内没有返回`);
-            if (!text.trim())
+            // THE MODEL'S OWN REASONING IS NOT THE TOOL'S OUTPUT. A model that thinks inside its answer
+            // would otherwise hand the caller a `<think>`-prefixed string, and the caller - a tool, a
+            // title, a card - would store the reasoning trace as its result.
+            const answer = stripInlineThinking(text);
+            if (!answer.trim())
                 throw new Error("模型没有返回任何内容");
-            return text;
+            return answer;
         }
         finally {
             if (child.exitCode === null && child.pid !== undefined)

package/dist/server/server-context.d.ts

@@ -39,6 +39,9 @@ export interface EventBroadcaster {
 export interface ServerContext {
     memory?: import("./active-memory.js").ActiveMemory;
     knowledge?: import("./knowledge.js").KnowledgeBase;
+    web?: import("./web.js").WebService;
+    /** The agent-facing document tools. Optional so the server can start without them. */
+    documentService?: import("./application/document-service.js").DocumentService;
     paths: ServerPaths;
     store: Store;
     runtime: AgentRuntime;

package/dist/server/subagents.js

@@ -6,6 +6,7 @@ import { agentSpawnArgs, readAgents } from "./agents.js";
 import { resolvePiCommand, shellQuote } from "./pi-command.js";
 import { buildExtensionUiResponse, describeExtensionUiRequest, killTree, } from "./runtime.js";
 import { RpcChannel } from "./rpc-channel.js";
+import { InlineThinkingSplitter, stripInlineThinking } from "./inline-thinking.js";
 import { describeToolCall, TOOL_DETAIL_CAP } from "./tool-calls.js";
 /**
  * The tool-call derivation now lives in `tool-calls.js`, because the primary agent's runtime needs the
@@ -284,6 +285,15 @@ export class SubagentSupervisor {
         let current = "";
         /** The last assistant message's text, which is the run's output. */
         let finalText = "";
+        /**
+         * THE CHILD'S OWN REASONING, taken out of its answer.
+         *
+         * A model that has no reasoning channel writes its thinking into the answer, marked up with
+         * `<think>…</think>`. This supervisor's contract is `finalText` - the child's OUTPUT - and the
+         * reasoning is not part of it, so the tags and what they wrap never reach the card. The splitter
+         * is per child, because what it holds back belongs to one child's stream and to nothing else.
+         */
+        const inlineThinking = new InlineThinkingSplitter();
         const usage = { ...NO_USAGE };
         /** Set rather than thrown so a child's own failure is reported AFTER its output has been drained. */
         let failed;
@@ -420,10 +430,18 @@ export class SubagentSupervisor {
                         // three messages would report all three concatenated as one answer.
                         if (event?.type === "text_delta") {
                             const delta = event.delta ?? "";
-                            streamed += delta;
-                            current += delta;
+                            // THE REASONING COMES OUT FIRST. What the card shows is the child's answer, and a model
+                            // that thinks inside its answer would otherwise hand it a string that opens with
+                            // `<think>` - the markup of a reasoning trace where the child's result belongs.
+                            const answer = inlineThinking.push(delta)
+                                .filter((segment) => segment.kind === "text")
+                                .map((segment) => segment.text)
+                                .join("");
+                            streamed += answer;
+                            current += answer;
                             enter("turn");
-                            onTextDelta?.(delta);
+                            if (answer)
+                                onTextDelta?.(answer);
                         }
                         else if (event?.type === "start") {
                             current = "";
@@ -432,16 +450,18 @@ export class SubagentSupervisor {
                         else if (event?.type === "done") {
                             // `done` carries the AUTHORITATIVE message, so its text wins over what the deltas added up
                             // to; the accumulated text stays as the fallback for a child that streams without a `done`.
-                            current = assistantText(event.message) || current;
+                            // The authoritative text is stripped the same way the deltas were: a child whose answer
+                            // ends in a reasoning region must not turn that region into its result.
+                            current = stripInlineThinking(assistantText(event.message)) || current;
                             finalText = current;
                             addUsage(usage, record.usage);
                             enter("turn");
                             const reason = event.message?.stopReason ?? event.reason;
                             if (reason === "error" || reason === "aborted")
-                                failed ??= `sub-agent ${agentId} (${id}) stopped with reason ${reason}: ${assistantText(event.message) || "no output"}`;
+                                failed ??= `sub-agent ${agentId} (${id}) stopped with reason ${reason}: ${stripInlineThinking(assistantText(event.message)) || "no output"}`;
                         }
                         else if (event?.type === "error") {
-                            failed ??= `sub-agent ${agentId} (${id}) reported ${event.reason ?? "an error"}: ${assistantText(event.message) || "no detail from Pi"}`;
+                            failed ??= `sub-agent ${agentId} (${id}) reported ${event.reason ?? "an error"}: ${stripInlineThinking(assistantText(event.message)) || "no detail from Pi"}`;
                         }
                         else if (event?.type === "thinking_delta") {
                             // CONSUMED, not discarded. A reasoning model spends the first seconds of every turn here,
@@ -524,6 +544,13 @@ export class SubagentSupervisor {
                 throw new Error(failed);
             // No `done` at all is a child that streamed and vanished; the deltas are then the best answer there
             // is, and returning them beats returning "" for work that demonstrably happened.
+            //
+            // THE SPLITTER IS RELEASED FIRST. It may still be holding back the beginning of a tag, and that
+            // text belongs to the child: a run that ended mid-word must not lose the word.
+            for (const segment of inlineThinking.flush()) {
+                if (segment.kind === "text")
+                    streamed += segment.text;
+            }
             return { id, sessionId: id, finalText: finalText || streamed, usage };
         }
         finally {

package/dist/server/web.d.ts

@@ -0,0 +1,24 @@
+export declare const WEB_SEARCH_TOOL_NAME = "web_search";
+export declare const WEB_FETCH_TOOL_NAME = "web_fetch";
+export declare const MAX_WEB_REQUEST_BYTES: number;
+export type WebSearchResult = {
+    title: string;
+    url: string;
+    snippet: string;
+};
+export type WebFetchResult = {
+    title: string;
+    url: string;
+    text: string;
+    truncated: boolean;
+    contentType: string;
+};
+/** Parse Bing's ordinary result page. Kept separate so captured fixtures can guard markup changes. */
+export declare function parseBingResults(html: string, limit?: number): WebSearchResult[];
+export declare class WebService {
+    search(query: string, limit?: number, signal?: AbortSignal): Promise<{
+        query: string;
+        results: WebSearchResult[];
+    }>;
+    fetch(url: string, signal?: AbortSignal): Promise<WebFetchResult>;
+}

package/dist/server/web.js

@@ -0,0 +1,180 @@
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
+export const WEB_SEARCH_TOOL_NAME = "web_search";
+export const WEB_FETCH_TOOL_NAME = "web_fetch";
+export const MAX_WEB_REQUEST_BYTES = 64 * 1024;
+const SEARCH_LIMIT = 10;
+const RESPONSE_LIMIT = 2 * 1024 * 1024;
+const TEXT_LIMIT = 30_000;
+const REDIRECT_LIMIT = 5;
+const TIMEOUT_MS = 15_000;
+const USER_AGENT = "Mozilla/5.0 (compatible; SuperPi/1.0; +https://www.npmjs.com/package/@evandu/super-pi)";
+function decodeEntities(value) {
+    const named = { amp: "&", quot: '"', apos: "'", lt: "<", gt: ">", nbsp: " " };
+    return value.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (_all, entity) => {
+        if (entity[0] === "#") {
+            const code = entity[1]?.toLowerCase() === "x" ? Number.parseInt(entity.slice(2), 16) : Number.parseInt(entity.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : "";
+        }
+        return named[entity.toLowerCase()] ?? `&${entity};`;
+    });
+}
+function plainText(html) {
+    return decodeEntities(html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ").replace(/<[^>]+>/g, " "))
+        .replace(/\s+/g, " ").trim();
+}
+/** Parse Bing's ordinary result page. Kept separate so captured fixtures can guard markup changes. */
+export function parseBingResults(html, limit = 5) {
+    const results = [];
+    const blocks = html.match(/<li\b[^>]*class=["'][^"']*\bb_algo\b[^"']*["'][^>]*>[\s\S]*?<\/li>/gi) ?? [];
+    for (const block of blocks) {
+        const anchor = /<h2\b[^>]*>[\s\S]*?<a\b[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/i.exec(block);
+        if (!anchor)
+            continue;
+        let url;
+        try {
+            url = new URL(decodeEntities(anchor[1]));
+        }
+        catch {
+            continue;
+        }
+        if (!/^https?:$/.test(url.protocol))
+            continue;
+        const caption = /<p\b[^>]*>([\s\S]*?)<\/p>/i.exec(block)?.[1] ?? "";
+        results.push({ title: plainText(anchor[2]), url: url.href, snippet: plainText(caption) });
+        if (results.length >= Math.min(SEARCH_LIMIT, Math.max(1, limit)))
+            break;
+    }
+    return results;
+}
+function blockedAddress(address) {
+    if (address === "::" || address === "::1")
+        return true;
+    const v4 = address.startsWith("::ffff:") ? address.slice(7) : address;
+    if (isIP(v4) === 4) {
+        const [a, b] = v4.split(".").map(Number);
+        return a === 0 || a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || a >= 224;
+    }
+    const normalized = address.toLowerCase();
+    return normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb") || normalized.startsWith("ff");
+}
+async function publicAddress(hostname) {
+    if (hostname.toLowerCase() === "localhost" || hostname.endsWith(".localhost"))
+        throw new Error("不允许访问本机或私网地址");
+    const records = isIP(hostname) ? [{ address: hostname, family: isIP(hostname) }] : await lookup(hostname, { all: true, verbatim: true });
+    const record = records.find(item => !blockedAddress(item.address));
+    if (!record || records.some(item => blockedAddress(item.address)))
+        throw new Error("不允许访问本机或私网地址");
+    return record;
+}
+async function download(input, signal, redirects = 0) {
+    const url = new URL(input);
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password)
+        throw new Error("只允许无凭据的 HTTP/HTTPS URL");
+    if (redirects > REDIRECT_LIMIT)
+        throw new Error("网页重定向次数过多");
+    const resolved = await publicAddress(url.hostname);
+    const requester = url.protocol === "https:" ? httpsRequest : httpRequest;
+    // Node may ask a custom lookup for one address or an array (`all: true`). Honor both overloads;
+    // returning the wrong shape makes net.connect report the misleading "Invalid IP address: undefined".
+    const pinnedLookup = ((_hostname, options, callback) => {
+        if (options?.all)
+            callback(null, [resolved]);
+        else
+            callback(null, resolved.address, resolved.family);
+    });
+    return new Promise((resolve, reject) => {
+        const req = requester(url, {
+            headers: { "user-agent": USER_AGENT, accept: "text/html,text/plain,application/xhtml+xml", "accept-encoding": "gzip, deflate, br" },
+            lookup: pinnedLookup,
+            servername: url.hostname,
+            timeout: TIMEOUT_MS,
+            signal,
+        }, response => {
+            const status = response.statusCode ?? 0;
+            const location = response.headers.location;
+            if (status >= 300 && status < 400 && location) {
+                response.resume();
+                download(new URL(location, url).href, signal, redirects + 1).then(resolve, reject);
+                return;
+            }
+            if (status < 200 || status >= 300) {
+                response.resume();
+                reject(new Error(`网页请求失败（HTTP ${status}）`));
+                return;
+            }
+            const chunks = [];
+            let bytes = 0;
+            response.on("data", chunk => {
+                bytes += chunk.length;
+                if (bytes > RESPONSE_LIMIT) {
+                    req.destroy(new Error("网页响应超过 2 MB 限制"));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on("end", () => {
+                try {
+                    let body = Buffer.concat(chunks);
+                    const encoding = String(response.headers["content-encoding"] ?? "").toLowerCase();
+                    if (encoding === "gzip")
+                        body = gunzipSync(body);
+                    else if (encoding === "deflate")
+                        body = inflateSync(body);
+                    else if (encoding === "br")
+                        body = brotliDecompressSync(body);
+                    resolve({ url: url.href, body, contentType: String(response.headers["content-type"] ?? "application/octet-stream") });
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        req.on("timeout", () => req.destroy(new Error("网页请求超时")));
+        req.on("error", reject);
+        req.end();
+    });
+}
+function extractHtml(html) {
+    const title = plainText(/<title\b[^>]*>([\s\S]*?)<\/title>/i.exec(html)?.[1] ?? "");
+    let body = /<article\b[^>]*>([\s\S]*?)<\/article>/i.exec(html)?.[1]
+        ?? /<main\b[^>]*>([\s\S]*?)<\/main>/i.exec(html)?.[1]
+        ?? /<body\b[^>]*>([\s\S]*?)<\/body>/i.exec(html)?.[1]
+        ?? html;
+    body = body.replace(/<(nav|aside|footer|form|noscript|svg)\b[^>]*>[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<(br|p|div|li|h[1-6]|tr)\b[^>]*>/gi, "\n")
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
+        .replace(/<[^>]+>/g, " ");
+    const text = decodeEntities(body).replace(/[ \t]+/g, " ").replace(/\n\s*/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+    return { title, text };
+}
+export class WebService {
+    async search(query, limit = 5, signal) {
+        const clean = query.trim();
+        if (!clean)
+            throw new Error("搜索词不能为空");
+        if (clean.length > 500)
+            throw new Error("搜索词不能超过 500 个字符");
+        const url = new URL("https://www.bing.com/search");
+        url.searchParams.set("q", clean);
+        url.searchParams.set("count", String(Math.min(SEARCH_LIMIT, Math.max(1, Math.floor(limit)))));
+        url.searchParams.set("setlang", "zh-Hans");
+        const response = await download(url.href, signal);
+        const results = parseBingResults(response.body.toString("utf8"), limit);
+        if (!results.length)
+            throw new Error("搜索引擎没有返回可解析的结果，可能暂时限流或页面格式已变化");
+        return { query: clean, results };
+    }
+    async fetch(url, signal) {
+        const response = await download(url, signal);
+        if (!/^(text\/html|application\/xhtml\+xml|text\/plain)\b/i.test(response.contentType))
+            throw new Error(`不支持的网页类型：${response.contentType}`);
+        const decoded = response.body.toString("utf8");
+        const extracted = /^text\/plain\b/i.test(response.contentType) ? { title: "", text: decoded.trim() } : extractHtml(decoded);
+        const truncated = extracted.text.length > TEXT_LIMIT;
+        return { title: extracted.title, url: response.url, text: extracted.text.slice(0, TEXT_LIMIT), truncated, contentType: response.contentType };
+    }
+}