@code-yeongyu/senpi 2026.10.11 → 2026.10.12

package/dist/core/extensions/builtin/cache-keepalive/startup-activity-gate.js

@@ -0,0 +1,25 @@
+/** Restored history is not admission; real activity or a completed turn is. */
+export function createStartupActivityGate() {
+    let waiting = false;
+    let unsubscribe;
+    function release() {
+        waiting = false;
+        unsubscribe?.();
+        unsubscribe = undefined;
+    }
+    return {
+        get waiting() {
+            return waiting;
+        },
+        start(ctx, onActivity) {
+            release();
+            waiting = true;
+            unsubscribe = ctx.onUserActivity?.(() => {
+                release();
+                onActivity();
+            });
+        },
+        release,
+    };
+}
+//# sourceMappingURL=startup-activity-gate.js.map

package/dist/core/extensions/builtin/compaction/index.js

@@ -1,4 +1,5 @@
 import { createWarmAnchorSnapshot, isWarmSummaryAnchorValid } from "../../../compaction/warm-anchor.js";
+import { AccountUsageLimitError } from "../../../retry-fallback/usage-limit.js";
 import * as checkpointState from "./checkpoint-state.js";
 import * as breaker from "./circuit-breaker.js";
 import { registerContextReductionLifecycle } from "./context-reduction-lifecycle.js";
@@ -368,7 +369,7 @@ export default function compactionExtension(pi, remoteCompactionDependencies = {
         let feedbackSignal = ctx.beginCompaction?.({ reason: "extension" });
         try {
             let remoteFallbackReason;
-            if (isOpenAiRemoteCompactionModel(ctx.model)) {
+            if (isOpenAiRemoteCompactionModel(ctx.model) && (ctx.getCompactionModel?.() ?? ctx.model) === ctx.model) {
                 const remoteGeneration = speculativeGeneration + 1;
                 const remoteSnapshot = createSpeculativeCompactionSnapshot(ctx, {
                     generation: remoteGeneration,
@@ -574,12 +575,19 @@ export default function compactionExtension(pi, remoteCompactionDependencies = {
             }
             let remoteCompaction;
             try {
-                remoteCompaction = await runOpenAiRemoteCompaction(ctx, event, (data) => {
-                    reportRemoteCompactionTimeout(ctx, event.reason, event.signal, data);
-                    pi.events.emit(SENPI_COMPACTION_EVENT, data);
-                }, remoteCompactionDependencies);
+                // Native remote compaction is tied to the active provider's replay origin.
+                // A different summary model must use the bounded local summary route.
+                remoteCompaction =
+                    (ctx.getCompactionModel?.() ?? model) !== model
+                        ? undefined
+                        : await runOpenAiRemoteCompaction(ctx, event, (data) => {
+                            reportRemoteCompactionTimeout(ctx, event.reason, event.signal, data);
+                            pi.events.emit(SENPI_COMPACTION_EVENT, data);
+                        }, remoteCompactionDependencies);
             }
             catch (error) {
+                if (error instanceof AccountUsageLimitError)
+                    return { cancel: true, reason: error.message };
                 // The remote route deliberately rethrows once its signal aborts; the
                 // handler converts that into a silent stand-down so the abort is not
                 // reported as an extension error with a stack (issue #886).

package/dist/core/extensions/builtin/compaction/speculative.d.ts

@@ -14,6 +14,7 @@ export interface SpeculativeCompactionContext {
     modelRegistry?: ModelRegistry;
     getContextUsage(): ContextUsage | undefined;
     getCompactionSettings?(): CompactionPreparation["settings"];
+    getCompactionModel?(): Model<any> | undefined;
     getMessageRevision(): number;
     getSystemPrompt?(): string;
     prepareProviderRequest?(messages: AgentMessage[]): Promise<ProviderRequestPreparation>;

package/dist/core/extensions/builtin/compaction/speculative.js

@@ -140,7 +140,11 @@ export function createSpeculativeCompactionSnapshot(context, options) {
 export async function runExtensionCompaction(context, snapshot, signal, onProgress) {
     if (signal?.aborted)
         return undefined;
-    const auth = await context.modelRegistry?.getApiKeyAndHeaders(snapshot.model);
+    const selectedModel = context.getCompactionModel?.() ?? snapshot.model;
+    const selectedSnapshot = selectedModel === snapshot.model
+        ? snapshot
+        : { ...snapshot, model: selectedModel, contextWindow: selectedModel.contextWindow };
+    const auth = await context.modelRegistry?.getApiKeyAndHeaders(selectedModel);
     if (signal?.aborted)
         return undefined;
     // A provider is authenticated for summarization by a resolved key, a credential
@@ -148,12 +152,12 @@ export async function runExtensionCompaction(context, snapshot, signal, onProgre
     // same provider resolution normal turns use; an unconfigured keyed provider still
     // has none of these and is rejected before a request.
     if (!auth?.ok || !(auth.apiKey || hasCredentialHeaders(auth.headers) || auth.ambient)) {
-        const detail = auth && !auth.ok ? auth.error : `no credentials resolved for provider "${snapshot.model.provider}"`;
+        const detail = auth && !auth.ok ? auth.error : `no credentials resolved for provider "${selectedModel.provider}"`;
         throw new SummaryGenerationError("auth", `summarization credentials unavailable: ${detail}`);
     }
     const requestSnapshot = auth.baseUrl
-        ? { ...snapshot, model: { ...snapshot.model, baseUrl: auth.baseUrl } }
-        : snapshot;
+        ? { ...selectedSnapshot, model: { ...selectedModel, baseUrl: auth.baseUrl } }
+        : selectedSnapshot;
     const prompt = buildPrompt({
         variant: requestSnapshot.promptVariant,
         previousSummary: requestSnapshot.preparation.previousSummary,

package/dist/core/extensions/builtin/moved-path-guard/tool-classes.js

@@ -21,6 +21,7 @@ export const MOVED_PATH_TOOL_CLASSES = {
     ask_user_question: { kind: "none" },
     todo: { kind: "none" },
     web_search: { kind: "none" },
+    $web_search: { kind: "none" },
     tool_search: { kind: "none" },
     webfetch: { kind: "none" },
     create_goal: { kind: "none" },

package/dist/core/extensions/builtin/openai-web-search/index.d.ts

@@ -1,6 +1,9 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "../../types.ts";
-type OpenAiWebSearchModel = Pick<Model<Api>, "api" | "baseUrl" | "compat">;
+type OpenAiWebSearchModel = Pick<Model<Api>, "api" | "baseUrl" | "compat"> & {
+    provider?: string;
+    id?: string;
+};
 type OpenAiWebSearchTarget = Api | OpenAiWebSearchModel | undefined;
 export declare function supportsNativeOpenAiWebSearch(target: OpenAiWebSearchTarget): boolean;
 export declare function addOpenAiWebSearchToPayload(target: OpenAiWebSearchTarget, payload: unknown): unknown;

package/dist/core/extensions/builtin/openai-web-search/index.js

@@ -1,5 +1,12 @@
-const OPENAI_RESPONSES_APIS = new Set(["openai-responses", "azure-openai-responses"]);
+import { hasServerSearchFailed, isServerSearchDisabled, isServerSearchFallback, markServerSearchFallback, } from "../server-search-fallback.js";
+const OPENAI_RESPONSES_APIS = new Set([
+    "openai-responses",
+    "azure-openai-responses",
+    "openai-codex-responses",
+]);
 const ENABLE_ENV = "PI_OPENAI_WEB_SEARCH";
+// OpenAI still supports this legacy server-tool name; Codex and xAI use web_search.
+// https://developers.openai.com/api/docs/guides/tools-web-search
 const NATIVE_OPENAI_WEB_SEARCH_TYPE = "web_search_preview";
 const WEB_SEARCH_SOURCES_INCLUDE = "web_search_call.action.sources";
 const STATUS_KEY = "openai-web-search";
@@ -34,27 +41,42 @@ function resolveTarget(target) {
     }
     return target;
 }
-function isOpenAiResponsesNativeEndpoint(model) {
-    try {
-        return new URL(model.baseUrl || "https://api.openai.com/v1").hostname === "api.openai.com";
-    }
-    catch {
-        return false;
-    }
-}
 export function supportsNativeOpenAiWebSearch(target) {
     const model = resolveTarget(target);
     if (!isOpenAiResponsesApi(model?.api)) {
         return false;
     }
-    if (model.api === "azure-openai-responses") {
+    const compat = model.compat;
+    // Codex/ChatGPT plans support web_search in their main Responses request.
+    // https://developers.openai.com/codex/config-basic/#web-search-mode
+    // Real subscription search and output-item replay were verified for senpi#3122.
+    if (model.api === "openai-codex-responses") {
+        if (model.id?.includes("-spark"))
+            return false;
+        try {
+            return compat?.supportsWebSearchPreview ?? new URL(model.baseUrl).hostname === "chatgpt.com";
+        }
+        catch {
+            return false;
+        }
+    }
+    // xAI documents web_search on Responses, not its Chat Completions endpoint.
+    // Compatible/custom Responses endpoints still need an explicit capability opt-in.
+    // https://docs.x.ai/developers/tools/web-search
+    // Preserve main's shipped Azure and first-party OpenAI defaults.
+    if (model.api === "azure-openai-responses")
         return true;
+    if (compat?.supportsWebSearchPreview !== undefined)
+        return compat.supportsWebSearchPreview;
+    try {
+        return new URL(model.baseUrl || "https://api.openai.com/v1").hostname === "api.openai.com";
+    }
+    catch {
+        return false;
     }
-    const compat = model.compat;
-    return compat?.supportsWebSearchPreview ?? isOpenAiResponsesNativeEndpoint(model);
 }
 function isNativeOpenAiWebSearchType(value) {
-    return value === "web_search_preview" || value === "web_search_preview_2025_03_11";
+    return value === "web_search" || value === "web_search_preview" || value === "web_search_preview_2025_03_11";
 }
 function isUnsupportedWebSearchType(value) {
     return (typeof value === "string" &&
@@ -75,7 +97,10 @@ function stripNativeOpenAiWebSearch(payload) {
         const sanitizedTools = tools.filter((tool) => !(isRecord(tool) && isNativeOpenAiWebSearchType(tool.type)));
         if (sanitizedTools.length !== tools.length) {
             changed = true;
-            sanitized.tools = sanitizedTools;
+            if (sanitizedTools.length)
+                sanitized.tools = sanitizedTools;
+            else
+                delete sanitized.tools;
         }
     }
     const include = payload.include;
@@ -119,6 +144,8 @@ function includeWebSearchSources(payload) {
     return include.includes(WEB_SEARCH_SOURCES_INCLUDE) ? include : [...include, WEB_SEARCH_SOURCES_INCLUDE];
 }
 export function addOpenAiWebSearchToPayload(target, payload) {
+    if (isServerSearchDisabled(payload) || isServerSearchFallback(payload))
+        return stripNativeOpenAiWebSearch(payload);
     const model = resolveTarget(target);
     if (!isOpenAiResponsesApi(model?.api)) {
         // Defense in depth. `web_search_preview` is an OpenAI Responses-only tool
@@ -149,14 +176,20 @@ export function addOpenAiWebSearchToPayload(target, payload) {
         if (!nativeStripped && !passiveSanitized.changed) {
             return strippedPayload;
         }
-        return {
+        const result = {
             ...strippedPayload,
             tools: passiveSanitized.tools,
         };
+        if (!passiveSanitized.tools.length)
+            delete result.tools;
+        return result;
     }
     const hasNativeWebSearch = sanitizedTools.some((tool) => isNativeOpenAiWebSearchType(tool.type));
     if (!hasNativeWebSearch) {
-        sanitizedTools.push({ type: NATIVE_OPENAI_WEB_SEARCH_TYPE });
+        sanitizedTools.push({
+            type: model.compat?.webSearchToolType ??
+                (model.api === "openai-codex-responses" ? "web_search" : NATIVE_OPENAI_WEB_SEARCH_TYPE),
+        });
     }
     return {
         ...payload,
@@ -185,7 +218,11 @@ Prefer web search over guessing when freshness matters.
 `;
 export default function openaiWebSearchExtension(pi) {
     pi.on("before_provider_request", (event, ctx) => {
-        return addOpenAiWebSearchToPayload(ctx.model, event.payload);
+        const model = event.model ?? ctx.model;
+        const payload = hasServerSearchFailed(ctx.sessionManager, model)
+            ? markServerSearchFallback(event.payload)
+            : event.payload;
+        return addOpenAiWebSearchToPayload(model, payload);
     });
     pi.on("session_start", async (_event, ctx) => {
         syncUi(ctx);

package/dist/core/extensions/builtin/server-search-fallback.d.ts

@@ -0,0 +1,12 @@
+import type { Api, Model, SimpleStreamOptions } from "@earendil-works/pi-ai";
+export declare const SERVER_SEARCH_FALLBACK: unique symbol;
+export declare const SERVER_SEARCH_DISABLED: unique symbol;
+export declare function resetServerSearchFailures(session: object): void;
+export declare function rememberServerSearchFailure(session: object, model: Model<Api>): void;
+export declare function hasServerSearchFailed(session: object, model: Model<Api> | undefined): boolean;
+export declare function markServerSearchFallback(payload: unknown): unknown;
+export declare function disableServerSearch(payload: unknown): unknown;
+export declare function withoutServerSearch(onPayload: SimpleStreamOptions["onPayload"], cacheRetention?: SimpleStreamOptions["cacheRetention"]): SimpleStreamOptions["onPayload"];
+export declare function isServerSearchDisabled(payload: unknown): boolean;
+export declare function isServerSearchFallback(payload: unknown): boolean;
+//# sourceMappingURL=server-search-fallback.d.ts.map

package/dist/core/extensions/builtin/server-search-fallback.js

@@ -0,0 +1,50 @@
+// Request-local metadata: Symbols survive hook-to-hook object spreads, but are
+// omitted by JSON.stringify and never reach the provider or stored transcript.
+export const SERVER_SEARCH_FALLBACK = Symbol.for("senpi.serverSearchFallback");
+export const SERVER_SEARCH_DISABLED = Symbol.for("senpi.serverSearchDisabled");
+const failedModels = new WeakMap();
+function modelKey(model) {
+    return JSON.stringify([model.api, model.provider, model.id, model.baseUrl]);
+}
+export function resetServerSearchFailures(session) {
+    failedModels.delete(session);
+}
+export function rememberServerSearchFailure(session, model) {
+    let failures = failedModels.get(session);
+    if (!failures) {
+        failures = new Set();
+        failedModels.set(session, failures);
+    }
+    failures.add(modelKey(model));
+}
+export function hasServerSearchFailed(session, model) {
+    return model !== undefined && failedModels.get(session)?.has(modelKey(model)) === true;
+}
+export function markServerSearchFallback(payload) {
+    return payload !== null && typeof payload === "object" ? { ...payload, [SERVER_SEARCH_FALLBACK]: true } : payload;
+}
+export function disableServerSearch(payload) {
+    return payload !== null && typeof payload === "object" ? { ...payload, [SERVER_SEARCH_DISABLED]: true } : payload;
+}
+export function withoutServerSearch(onPayload, cacheRetention = "none") {
+    // Cache-friendly summaries must keep the main-turn hook and tool prefix verbatim.
+    if (cacheRetention !== "none")
+        return onPayload;
+    return async (payload, model, request) => {
+        const disabled = disableServerSearch(payload);
+        return (await onPayload?.(disabled, model, request)) ?? disabled;
+    };
+}
+export function isServerSearchDisabled(payload) {
+    return (payload !== null &&
+        typeof payload === "object" &&
+        SERVER_SEARCH_DISABLED in payload &&
+        payload[SERVER_SEARCH_DISABLED] === true);
+}
+export function isServerSearchFallback(payload) {
+    return (payload !== null &&
+        typeof payload === "object" &&
+        SERVER_SEARCH_FALLBACK in payload &&
+        payload[SERVER_SEARCH_FALLBACK] === true);
+}
+//# sourceMappingURL=server-search-fallback.js.map

package/dist/core/extensions/builtin/terminal/runtime-session.d.ts

@@ -11,13 +11,19 @@ export interface DeltaRead {
  * A live terminal session: a pi-pty {@link TerminalSession} plus an xterm screen model
  * and a bounded decoded-output buffer with a per-consumer read cursor. Reads are pure
  * non-blocking peeks; watchers subscribe through `onOutput` (the monitor path).
+ *
+ * Once the process exits, the screen model is replaced by its final visible screen: an exited session
+ * stays listed until the registry needs its slot, and a live xterm with its scrollback and replay
+ * history costs tens of MB that nothing reads after exit (senpi#3171).
  */
 export declare class TerminalRuntimeSession {
     readonly session: TerminalSession;
     readonly command: string;
     readonly startedAtMs: number;
     private readonly argv;
-    private readonly screen;
+    private screen;
+    private finalScreen;
+    private readonly screenRelease;
     private readonly decoder;
     private buffer;
     private droppedChars;
@@ -25,6 +31,9 @@ export declare class TerminalRuntimeSession {
     private readonly outputListeners;
     private unsubscribeData;
     constructor(command: string, options: TerminalRuntimeOptions);
+    /** Resolves once an exited session has kept its final visible screen and dropped the screen model. */
+    screenReleased(): Promise<void>;
+    private releaseScreen;
     get backend(): string | null;
     /** The spawned child as a later process can recognise it; undefined when the backend exposes no pid. */
     identity(): ChildProcessIdentity | undefined;

package/dist/core/extensions/builtin/terminal/runtime-session.js

@@ -2,13 +2,25 @@ import { processBootAtMs } from "./process-identity.js";
 import { loadPty } from "./pty.lazy.js";
 import { DEFAULT_SCROLLBACK, MAX_SESSION_OUTPUT_CHARS } from "./shared.js";
 const pty = await loadPty();
+const RELEASED_SCREEN = {
+    cols: 0,
+    rows: 0,
+    visibleGrid: [],
+    scrollback: [],
+    cursor: { x: 0, y: 0 },
+};
 /**
  * A live terminal session: a pi-pty {@link TerminalSession} plus an xterm screen model
  * and a bounded decoded-output buffer with a per-consumer read cursor. Reads are pure
  * non-blocking peeks; watchers subscribe through `onOutput` (the monitor path).
+ *
+ * Once the process exits, the screen model is replaced by its final visible screen: an exited session
+ * stays listed until the registry needs its slot, and a live xterm with its scrollback and replay
+ * history costs tens of MB that nothing reads after exit (senpi#3171).
  */
 export class TerminalRuntimeSession {
     constructor(command, options) {
+        this.finalScreen = null;
         this.decoder = new TextDecoder("utf-8", { fatal: false });
         this.buffer = "";
         this.droppedChars = 0;
@@ -46,9 +58,36 @@ export class TerminalRuntimeSession {
                 }
             }
         });
+        this.screenRelease = new Promise((resolve) => {
+            this.session.onExit(() => {
+                // Best-effort like every screen write (#837): a failed release leaves an empty final screen, never an unhandled rejection.
+                void this.releaseScreen()
+                    .catch(() => { })
+                    .finally(resolve);
+            });
+        });
         this.session.start();
         this.startedAtMs = Date.now();
     }
+    /** Resolves once an exited session has kept its final visible screen and dropped the screen model. */
+    screenReleased() {
+        return this.screenRelease;
+    }
+    async releaseScreen() {
+        const screen = this.screen;
+        if (!screen)
+            return;
+        await screen.flush().catch(() => { });
+        if (this.screen !== screen)
+            return;
+        this.screen = null;
+        try {
+            this.finalScreen = { ...screen.snapshot(), scrollback: [] };
+        }
+        finally {
+            screen.dispose();
+        }
+    }
     get backend() {
         return this.session.backend;
     }
@@ -80,7 +119,8 @@ export class TerminalRuntimeSession {
         const text = this.decoder.decode(chunk, { stream: true });
         if (text.length === 0)
             return text;
-        this.ownScreenWrite(this.screen.feed(text));
+        if (this.screen)
+            this.ownScreenWrite(this.screen.feed(text));
         this.buffer += text;
         if (this.buffer.length > MAX_SESSION_OUTPUT_CHARS) {
             const overflow = this.buffer.length - MAX_SESSION_OUTPUT_CHARS;
@@ -107,10 +147,13 @@ export class TerminalRuntimeSession {
         return this.buffer;
     }
     snapshot() {
-        return this.screen.snapshot();
+        if (this.screen)
+            return this.screen.snapshot();
+        return this.finalScreen ?? RELEASED_SCREEN;
     }
     resizeScreen(cols, rows) {
-        this.ownScreenWrite(this.screen.resize(cols, rows));
+        if (this.screen)
+            this.ownScreenWrite(this.screen.resize(cols, rows));
     }
     ownScreenWrite(written) {
         if (written === this.lastScreenWrite)
@@ -122,7 +165,8 @@ export class TerminalRuntimeSession {
         this.unsubscribeData?.();
         this.unsubscribeData = null;
         this.outputListeners.clear();
-        this.screen.dispose();
+        this.screen?.dispose();
+        this.screen = null;
     }
 }
 //# sourceMappingURL=runtime-session.js.map

package/dist/core/extensions/builtin/websearch/index.d.ts

@@ -1,3 +1,3 @@
-import type { ExtensionAPI } from "../../types.ts";
+import { type ExtensionAPI } from "../../types.ts";
 export default function (pi: ExtensionAPI): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/core/extensions/builtin/websearch/index.js

@@ -1,5 +1,9 @@
-import { isAnthropicWebSearchEnabled, supportsNativeAnthropicWebSearch } from "../anthropic-web-search/index.js";
-import { isOpenaiWebSearchEnabled, supportsNativeOpenAiWebSearch } from "../openai-web-search/index.js";
+import { Type } from "typebox";
+import { defineTool } from "../../types.js";
+import { ANTHROPIC_WEB_SEARCH_SECTION } from "../anthropic-web-search/index.js";
+import { OPENAI_WEB_SEARCH_SECTION } from "../openai-web-search/index.js";
+import { hasServerSearchFailed, rememberServerSearchFailure, resetServerSearchFailures, } from "../server-search-fallback.js";
+import { additionalServerSearch, hasServerSearch, serverSearchFailure, serverSearchPayload, } from "./server-search.js";
 import { loadWebsearchConfig } from "./websearch/config.js";
 import { attemptRouteLabel } from "./websearch/route-attempts.js";
 import { providerEntryLabel } from "./websearch/search.js";
@@ -8,18 +12,6 @@ import { createWebSearchTool } from "./websearch/tool.js";
 const STATUS_KEY = "pi-websearch";
 const WIDGET_KEY = "pi-websearch";
 const NATIVE_BYPASS_MESSAGE = "Native provider web search is handled by the built-in provider extension.";
-// Defer to the provider-native server-side web_search only when the builtin
-// injecting extension will actually add it for this exact model (first-party
-// endpoint or explicit compat opt-in, and not disabled via env). A provider id
-// of "anthropic"/"openai" alone is not enough: proxied baseUrls (ccapi, quotio,
-// …) never receive the native tool, so bypassing there leaves no web search.
-function isProviderNativeBypass(model) {
-    if (supportsNativeAnthropicWebSearch(model))
-        return isAnthropicWebSearchEnabled();
-    if (supportsNativeOpenAiWebSearch(model))
-        return isOpenaiWebSearchEnabled();
-    return false;
-}
 export default function (pi) {
     let state = {
         ok: false,
@@ -50,6 +42,11 @@ export default function (pi) {
         ctx.ui.notify(state.message, "error");
     }
     let lastServedBy;
+    let nativeFailed = false;
+    let fallbackPending = false;
+    let fallbackSent = false;
+    let userAborted = false;
+    let requestModel;
     // senpi#2340: status names the model native search runs on, warns about an ignored nativeModel,
     // and reports which route and model served the last search.
     function nativeModelStatus(config, ctx) {
@@ -72,25 +69,129 @@ export default function (pi) {
         }
         return { text };
     }
-    pi.registerTool(createWebSearchTool(() => state, {
+    const searchTool = createWebSearchTool(() => state, {
         onSearchComplete: (details) => {
             if (!details.error)
                 lastServedBy = attemptRouteLabel(details);
         },
+    });
+    pi.registerTool(searchTool);
+    pi.registerTool(defineTool({
+        name: "$web_search",
+        exposure: "search",
+        allowLazyActivation: false,
+        label: "Moonshot Server Search",
+        description: "Return the Moonshot built-in server search result to the same model.",
+        parameters: Type.Record(Type.String(), Type.Unknown()),
+        async execute(_id, params) {
+            // Official Moonshot flow: echo generated arguments, never make a
+            // separate request or substitute another model.
+            return { content: [{ type: "text", text: JSON.stringify(params) }], details: params };
+        },
     }));
     async function refreshState(model, ctx) {
-        state = isProviderNativeBypass(model)
-            ? { ok: false, reason: "provider_native_bypass", message: NATIVE_BYPASS_MESSAGE }
-            : await loadWebsearchConfig({ cwd: ctx.cwd });
+        state =
+            !nativeFailed && hasServerSearch(model)
+                ? { ok: false, reason: "provider_native_bypass", message: NATIVE_BYPASS_MESSAGE }
+                : await loadWebsearchConfig({ cwd: ctx.cwd });
+        const active = pi.getActiveTools();
+        const withoutMoonshot = active.filter((name) => name !== "$web_search");
+        const moonshotEnabled = !nativeFailed && additionalServerSearch(model) === "moonshot";
+        if (moonshotEnabled !== active.includes("$web_search")) {
+            pi.setActiveTools(moonshotEnabled ? [...withoutMoonshot, "$web_search"] : withoutMoonshot);
+        }
         updateUi(ctx);
     }
     pi.on("session_start", async (_event, ctx) => {
         lastServedBy = undefined;
+        resetServerSearchFailures(ctx.sessionManager);
+        nativeFailed = false;
+        fallbackPending = false;
+        fallbackSent = false;
+        userAborted = false;
         await refreshState(ctx.model, ctx);
     });
     pi.on("model_select", async (event, ctx) => {
+        nativeFailed = hasServerSearchFailed(ctx.sessionManager, event.model);
+        fallbackPending = false;
+        fallbackSent = false;
         await refreshState(event.model, ctx);
     });
+    pi.on("before_agent_start", async (event, ctx) => {
+        if (!event.preview && event.trigger !== "extension") {
+            nativeFailed = hasServerSearchFailed(ctx.sessionManager, ctx.model);
+            fallbackPending = false;
+            fallbackSent = false;
+            userAborted = false;
+            await refreshState(ctx.model, ctx);
+        }
+        if (!hasServerSearch(ctx.model))
+            return undefined;
+        const systemPrompt = event.systemPrompt
+            .replace(ANTHROPIC_WEB_SEARCH_SECTION, "")
+            .replace(OPENAI_WEB_SEARCH_SECTION, "");
+        return {
+            systemPrompt: `${systemPrompt}\n## Web Search\n${hasServerSearchFailed(ctx.sessionManager, ctx.model)
+                ? "Use the standalone web_search tool when current information is needed. Native search failed for this session model."
+                : "Use the provider's in-turn server web search when current information is needed."}`,
+        };
+    }, { previewSafe: true });
+    pi.on("before_provider_request", (event, ctx) => {
+        requestModel = event.model ?? ctx.model;
+        return serverSearchPayload(requestModel, event.payload, hasServerSearchFailed(ctx.sessionManager, requestModel));
+    });
+    pi.on("message_end", async (event, ctx) => {
+        if (event.message.role !== "assistant")
+            return undefined;
+        const message = event.message;
+        const model = requestModel?.api === message.api &&
+            requestModel.provider === message.provider &&
+            requestModel.id === message.model
+            ? requestModel
+            : ctx.model?.api === message.api &&
+                ctx.model.provider === message.provider &&
+                ctx.model.id === message.model
+                ? ctx.model
+                : ctx.modelRegistry.find(message.provider, message.model);
+        if (!model || hasServerSearchFailed(ctx.sessionManager, model) || !hasServerSearch(model))
+            return undefined;
+        const reason = serverSearchFailure(message, model);
+        if (!reason)
+            return undefined;
+        nativeFailed = true;
+        rememberServerSearchFailure(ctx.sessionManager, model);
+        // A provider can recover from a failed search and still finish its answer.
+        // Enable fallback for another request, but never duplicate a completed answer.
+        fallbackPending =
+            event.message.stopReason === "error" ||
+                !event.message.content.some((block) => block.type === "text" && block.text.trim().length > 0);
+        await refreshState(model, ctx);
+        pi.appendEntry("websearch-native-fallback", { reason });
+        if (ctx.hasUI)
+            ctx.ui.notify(`Web search fallback: ${reason}.`, "warning");
+        return undefined;
+    });
+    pi.on("agent_end", (event) => {
+        userAborted = event.abortSource === "user";
+        // The core retry already continues the original request with the restored function tool.
+        if (event.willRetry || userAborted)
+            fallbackPending = false;
+    });
+    pi.on("session_abort", () => {
+        userAborted = true;
+        fallbackPending = false;
+    });
+    pi.on("agent_settled", () => {
+        if (!fallbackPending || fallbackSent || userAborted)
+            return;
+        fallbackPending = false;
+        fallbackSent = true;
+        pi.sendMessage({
+            customType: "websearch-native-fallback",
+            content: "Continue the original request using the standalone web_search tool. Do not retry native server search on this turn.",
+            display: false,
+        }, { triggerTurn: true });
+    });
     pi.on("session_shutdown", async (_event, ctx) => {
         clearUi(ctx);
     });

package/dist/core/extensions/builtin/websearch/server-search.d.ts

@@ -0,0 +1,11 @@
+import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
+export type SearchModel = Pick<Model<Api>, "api" | "provider" | "id" | "baseUrl" | "compat">;
+type AdditionalServerSearch = "google" | "openrouter" | "perplexity" | "moonshot" | "zai";
+export declare function additionalServerSearch(model: SearchModel | undefined): AdditionalServerSearch | undefined;
+export declare function hasServerSearch(model: SearchModel | undefined): boolean;
+/** Preserve adapter-built function search on fallback; never reconstruct its normalized schema. */
+export declare function serverSearchPayload(model: SearchModel | undefined, payload: unknown, failed?: boolean): unknown;
+/** Only search-specific errors trigger fallback; cancellation and unrelated provider failures do not. */
+export declare function serverSearchFailure(message: Pick<AssistantMessage, "stopReason" | "content" | "errorMessage">, model?: SearchModel): string | undefined;
+export {};
+//# sourceMappingURL=server-search.d.ts.map