@code-yeongyu/senpi 2026.10.11 → 2026.10.12

package/dist/modes/rpc/host-lifecycle-ticker.js

@@ -0,0 +1,27 @@
+/** Idle and lifetime-owner checks share one ticker and never overlap owner probes. */
+export function startSupervisorTicker(options) {
+    const { activity, owner, draining, shuttingDown, shutdown } = options;
+    const tickIntervalMs = Math.max(20, Math.min(1_000, options.idleExitMs / 4));
+    let ownerCheck = false;
+    const ticker = setInterval(() => {
+        if (!draining() && activity.refresh() === "exit" && activity.clients.unclassifiedCount === 0)
+            void shutdown("idle", 0);
+        if (!ownerCheck && !shuttingDown() && !draining()) {
+            ownerCheck = true;
+            void owner
+                .shouldExit(activity)
+                .then((exit) => {
+                if (exit && !shuttingDown() && !draining())
+                    void shutdown("owner_gone", 0);
+            })
+                .finally(() => {
+                ownerCheck = false;
+            });
+        }
+    }, tickIntervalMs);
+    return () => {
+        clearInterval(ticker);
+        owner.stop();
+    };
+}
+//# sourceMappingURL=host-lifecycle-ticker.js.map

package/dist/modes/rpc/host-lifecycle.js

@@ -3,7 +3,8 @@ import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getAgentDir, isBundledNode } from "../../config.js";
+import { getAgentDir, isBundledNode, VERSION } from "../../config.js";
+import { HostAdmission } from "./host-admission.js";
 import { classifyChildExit, noteChildExit } from "./host-child-exit.js";
 import { hostCrashCleanupPaths } from "./host-cleanup-paths.js";
 import { createHostDaemonPaths, generationPaths } from "./host-daemon-paths.js";
@@ -15,6 +16,7 @@ import { resolveHostPolicy } from "./host-lifecycle-policy.js";
 import { adoptPublicSocket, createPublicProxy, ensurePublicSocketSecret, listen, prepareSocketPath, waitForListener, } from "./host-lifecycle-proxy.js";
 import { createInternalSocketPath, readSettingsFile, recordChildPid } from "./host-lifecycle-scratch.js";
 import { performShutdown, registerSupervisorSignals, supervisorSender, } from "./host-lifecycle-shutdown.js";
+import { startSupervisorTicker } from "./host-lifecycle-ticker.js";
 import { errorMessage, writeStderrLine } from "./host-supervisor-log.js";
 import { PUBLIC_SOCKET_IDENTITY_FILE, statSocketIdentity, writeSocketIdentityFile } from "./socket-ownership.js";
 import { createSocketSecret, socketSecretPath } from "./socket-transport.js";
@@ -110,13 +112,14 @@ export async function runHostSupervisor(launch) {
         const verdict = classifyChildExit(code, signal);
         void state.childExitRecorded.then(() => shutdown(verdict.reason, verdict.exitCode));
     });
-    const drain = new SupervisorDrain(child, () => state.shuttingDown);
+    const admission = new HostAdmission({ protocolVersion: 1, serverVersion: VERSION, capabilities: [], instanceId });
+    const drain = new SupervisorDrain(child, () => state.shuttingDown, () => admission.stop());
     const server = createPublicProxy({
         internalSocket,
         ...(internalSecret ? { internalSecret } : {}),
         ...(publicSecret ? { publicSecret } : {}),
         clients: activity.clients,
-        refusing: () => state.shuttingDown || drain.active,
+        admission,
         onDetach: () => activity.refresh(),
         onAdmit: () => owner.activity(),
     });
@@ -124,26 +127,14 @@ export async function runHostSupervisor(launch) {
         if (!state.shuttingDown)
             void shutdown(`public socket listener failed: ${errorMessage(cause)}`, 1);
     });
-    const tickIntervalMs = Math.max(20, Math.min(1_000, policy.idleExitMs / 4));
-    let ownerCheck = false;
-    const ticker = setInterval(() => {
-        if (!drain.active && activity.refresh() === "exit" && activity.clients.unclassifiedCount === 0)
-            void shutdown("idle", 0);
-        if (!ownerCheck && !state.shuttingDown && !drain.active) {
-            ownerCheck = true;
-            void owner
-                .shouldExit(activity)
-                .then((exit) => {
-                if (exit && !state.shuttingDown && !drain.active)
-                    void shutdown("owner_gone", 0);
-            })
-                .finally(() => {
-                ownerCheck = false;
-            });
-        }
-    }, tickIntervalMs);
-    watchers.push(() => clearInterval(ticker));
-    watchers.push(() => owner.stop());
+    watchers.push(startSupervisorTicker({
+        idleExitMs: policy.idleExitMs,
+        activity,
+        owner,
+        draining: () => drain.active,
+        shuttingDown: () => state.shuttingDown,
+        shutdown,
+    }));
     const teardown = {
         paths,
         generation,
@@ -154,6 +145,7 @@ export async function runHostSupervisor(launch) {
         child,
         activity,
         drain,
+        admission,
         state,
         stopWatchers: () => {
             for (const stop of watchers.splice(0))

package/dist/modes/rpc/host-outcome.js

@@ -17,6 +17,7 @@ export function identityPayload(socket, pid, host) {
     return {
         socket,
         pid,
+        lifecycle: host?.lifecycle ?? null,
         instanceId: host?.instanceId ?? null,
         generation: host?.generation ?? null,
         engineVersion: host?.engineVersion ?? null,

package/dist/modes/rpc/host-protocol-info.d.ts

@@ -16,6 +16,8 @@ import type { RpcLaunchProfile } from "./rpc-types.ts";
  * host from an older release answers without them; absence is read as "uncomparable", never as zero.
  */
 export interface HostProtocolInfo {
+    /** Absent on older hosts. A stopping generation never admits a new session. */
+    readonly lifecycle?: "ready" | "stopping";
     readonly protocolVersion: number;
     /** Informational only. Nothing in this module compares it. */
     readonly serverVersion: string;

package/dist/modes/rpc/host-protocol-info.js

@@ -14,6 +14,7 @@ export function parseHostProtocolInfo(data) {
         protocolVersion: typeof data.protocolVersion === "number" ? data.protocolVersion : 0,
         serverVersion: data.serverVersion,
         capabilities: data.capabilities,
+        ...((data.lifecycle === "ready" || data.lifecycle === "stopping") && { lifecycle: data.lifecycle }),
         ...(typeof data.instanceId === "string" && { instanceId: data.instanceId }),
         ...(typeof data.generation === "number" &&
             Number.isSafeInteger(data.generation) && { generation: data.generation }),

package/dist/modes/rpc/host-session-runner.js

@@ -4,13 +4,30 @@ import { createHostDaemonPaths } from "./host-daemon-paths.js";
 import { HostEnsureRefusedError } from "./host-decision.js";
 import { endpointKindOfSocket } from "./host-endpoints.js";
 import { ensureHost } from "./host-ensure.js";
+import { STOP_WAIT_BUDGET_MS } from "./host-ensure-stop.js";
 import { HOST_EXIT_OK, refusal } from "./host-outcome.js";
 import { mapError } from "./host-session-errors.js";
 import { openHostSession } from "./host-session-open.js";
 import { resolveSessionRef } from "./host-session-ref.js";
 import { waitForHostSession } from "./host-session-wait.js";
-import { RpcClient } from "./rpc-client.js";
+import { RpcClient, RpcCommandError } from "./rpc-client.js";
 export async function runHostSessionRequest(request) {
+    const deadline = Date.now() + STOP_WAIT_BUDGET_MS;
+    for (;;) {
+        try {
+            return await runHostSessionRequestOnce(request, Math.max(0, deadline - Date.now()));
+        }
+        catch (error) {
+            if (request.action === "open" &&
+                error instanceof RpcCommandError &&
+                error.errorCode === "host_stopping" &&
+                Date.now() < deadline)
+                continue;
+            return mapError(error, request.target.socket);
+        }
+    }
+}
+async function runHostSessionRequestOnce(request, stoppingTimeoutMs) {
     const { socket, agentDir } = request.target;
     let client;
     let ensured;
@@ -27,6 +44,7 @@ export async function runHostSessionRequest(request) {
                 env: daemonEnvOverrides(process.env, request.spec.env),
                 policy: request.spec.policy,
                 upgrade: "never",
+                stoppingTimeoutMs,
             });
             if (!ensured.reused) {
                 await writeDaemonEnvKeys(createHostDaemonPaths({ socket, agentDir }), daemonEnvKeys(process.env, request.spec.env));
@@ -160,6 +178,9 @@ export async function runHostSessionRequest(request) {
         }
     }
     catch (error) {
+        // Only an explicit open owns a launch spec. No other operation may invent one.
+        if (request.action === "open" && error instanceof RpcCommandError && error.errorCode === "host_stopping")
+            throw error;
         if (error instanceof HostEnsureRefusedError) {
             return refusal("refuse", undefined, { reason: error.reason, socket, detail: error.detail });
         }

package/dist/modes/rpc/host-status-all.js

@@ -83,6 +83,7 @@ async function unaddressableStatus(dir) {
     const claims = await readClaimRows(paths, generations);
     return {
         reachable: false,
+        lifecycle: null,
         pid: null,
         instanceId: null,
         generation: null,

package/dist/modes/rpc/host-status.d.ts

@@ -21,6 +21,7 @@ export type { HostGenerationRow } from "./host-generations.ts";
 export type { HostPathClaimRow, HostSessionRow } from "./host-status-rows.ts";
 export interface HostStatusReport {
     readonly reachable: boolean;
+    readonly lifecycle: "ready" | "stopping" | null;
     readonly socket: string;
     readonly pid: number | null;
     readonly instanceId: string | null;

package/dist/modes/rpc/host-status.js

@@ -47,10 +47,13 @@ export async function probeHostStatus(options, read = {}) {
     const metrics = current ? await readHostProcessMetrics(current.pid) : UNOBSERVED_METRICS;
     // A socket that did not answer who it is will not answer what it holds: asking again would only
     // spend a second budget on a hung endpoint.
-    const listing = host === undefined ? [] : await readSessionListing(options.socket, includeWorkers, timeoutMs);
+    const listing = host === undefined || host.lifecycle === "stopping"
+        ? []
+        : await readSessionListing(options.socket, includeWorkers, timeoutMs);
     const claims = await readClaimRows(paths, generations);
     const report = {
         reachable: host !== undefined,
+        lifecycle: host?.lifecycle ?? null,
         socket: options.socket,
         pid: current?.pid ?? null,
         instanceId: host?.instanceId ?? current?.instanceId ?? null,
@@ -106,6 +109,7 @@ export function hostSummary(host) {
     return {
         protocolVersion: host.protocolVersion,
         serverVersion: host.serverVersion,
+        lifecycle: host.lifecycle ?? null,
         capabilities: host.capabilities,
         instanceId: host.instanceId ?? null,
         generation: host.generation ?? null,

package/dist/modes/rpc/rpc-client.d.ts

@@ -21,7 +21,7 @@ export declare class RpcCommandError extends Error {
 }
 import type { SessionEntry, SessionTreeNode } from "../../core/session-manager.ts";
 import type { JsonAgentSessionEvent } from "../json-event.ts";
-import type { EditAssistantMessageResult, EditUserMessageResult, RpcAccountFailoverEvent, RpcAuthAccountsChangedEvent, RpcExtensionEvent, RpcExtensionUIProgress, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcOpenQueuedEvent, RpcProviderAccount, RpcSessionModelEntry, RpcSessionParkedEvent, RpcSessionReplacedEvent, RpcSessionState, RpcSlashCommand } from "./rpc-types.ts";
+import type { EditAssistantMessageResult, EditUserMessageResult, RpcAccountFailoverEvent, RpcAuthAccountsChangedEvent, RpcEvalCell, RpcEvalCellSnapshot, RpcExtensionEvent, RpcExtensionUIProgress, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcOpenQueuedEvent, RpcProviderAccount, RpcSessionModelEntry, RpcSessionParkedEvent, RpcSessionReplacedEvent, RpcSessionState, RpcSlashCommand } from "./rpc-types.ts";
 export interface RpcClientOptions {
     /** Connect to an existing multi-session Unix socket instead of spawning a child. */
     socketPath?: string;
@@ -476,6 +476,12 @@ export declare class RpcClient {
     getCommands(): Promise<RpcSlashCommand[]>;
     /** Invoke one extension-owned RPC request handler and return its structured result. */
     requestExtension<T = unknown>(name: string, data?: unknown): Promise<T>;
+    /** Read live and recently settled eval cells without a model tool call. */
+    listEvalCells(): Promise<RpcEvalCell[]>;
+    /** Read a bounded UTF-8 output tail; the host caps tailBytes at 64 KiB. */
+    peekEvalCell(cellId: string, tailBytes?: number): Promise<RpcEvalCellSnapshot>;
+    /** Stop a session-owned cell and return its confirmed terminal snapshot. */
+    stopEvalCell(cellId: string): Promise<RpcEvalCellSnapshot>;
     /** List safe metadata for the named provider's configured account slots. */
     getProviderAccounts(provider: string): Promise<RpcProviderAccount[]>;
     /** Pin a provider account for future session-affine requests, or clear the pin. */

package/dist/modes/rpc/rpc-client.js

@@ -782,6 +782,18 @@ export class RpcClient {
         });
         return this.getData(response);
     }
+    /** Read live and recently settled eval cells without a model tool call. */
+    async listEvalCells() {
+        return this.getData(await this.send({ type: "eval_cells.list" }));
+    }
+    /** Read a bounded UTF-8 output tail; the host caps tailBytes at 64 KiB. */
+    async peekEvalCell(cellId, tailBytes) {
+        return this.getData(await this.send({ type: "eval_cells.peek", cellId, ...(tailBytes === undefined ? {} : { tailBytes }) }));
+    }
+    /** Stop a session-owned cell and return its confirmed terminal snapshot. */
+    async stopEvalCell(cellId) {
+        return this.getData(await this.send({ type: "eval_cells.stop", cellId }));
+    }
     /** List safe metadata for the named provider's configured account slots. */
     async getProviderAccounts(provider) {
         const response = await this.send({ type: "get_provider_accounts", provider });

package/dist/modes/rpc/rpc-types.d.ts

@@ -331,6 +331,18 @@ type RpcSessionCommand = {
     type: "extension_request";
     name: string;
     data?: unknown;
+} | {
+    id?: string;
+    type: "eval_cells.list";
+} | {
+    id?: string;
+    type: "eval_cells.peek";
+    cellId: string;
+    tailBytes?: number;
+} | {
+    id?: string;
+    type: "eval_cells.stop";
+    cellId: string;
 } | {
     id?: string;
     type: "get_auth_providers";
@@ -409,6 +421,9 @@ export declare const RPC_ERROR_STREAMING = "streaming";
 export declare const RPC_ERROR_ENTRY_NOT_FOUND = "not_found";
 /** `set_model` named a provider/model pair the session's registry does not offer. */
 export declare const RPC_ERROR_MODEL_NOT_FOUND = "model_not_found";
+export declare const RPC_ERROR_EVAL_CELL_NOT_FOUND = "eval_cell_not_found";
+export declare const RPC_ERROR_INVALID_EVAL_CELL_REQUEST = "invalid_eval_cell_request";
+export declare const RPC_ERROR_EVAL_CELLS_UNAVAILABLE = "eval_cells_unavailable";
 export declare const RPC_ERROR_NOT_ASSISTANT = "not_assistant";
 export declare const RPC_ERROR_NOT_USER = "not_user";
 export declare const RPC_ERROR_EMPTY_TEXT = "empty";
@@ -437,7 +452,9 @@ export declare const RPC_ERROR_RELEASE_UNSUPPORTED = "release_unsupported";
 export declare const RPC_ERROR_RELEASE_FAILED = "release_failed";
 /** A draining host parks every session itself; `release_session` and `open_session` are refused meanwhile. */
 export declare const RPC_ERROR_HOST_DRAINING = "host_draining";
-export type RpcErrorCode = typeof RPC_ERROR_UNKNOWN_SESSION | typeof RPC_ERROR_SESSION_CLOSING | typeof RPC_ERROR_SESSION_PATH_IN_USE | typeof RPC_ERROR_SESSION_HELD | typeof RPC_ERROR_SESSION_RESERVATION_LIMIT | typeof RPC_ERROR_MISSING_SESSION_ID | typeof RPC_ERROR_MULTI_SESSION_DISABLED | typeof RPC_ERROR_INVALID_PATH | typeof RPC_ERROR_OPEN_FAILED | typeof RPC_ERROR_MEDIA_NOT_FOUND | typeof RPC_ERROR_INVALID_SESSION_CONTEXT | typeof RPC_ERROR_INVALID_SESSION_KIND | typeof RPC_ERROR_INVALID_LAUNCH_PROFILE | typeof RPC_ERROR_INVALID_SESSION_ID | typeof RPC_ERROR_SESSION_ID_IN_USE | typeof RPC_ERROR_HOST_MEMORY_PRESSURE | typeof RPC_ERROR_WARM_FAILED | typeof RPC_ERROR_STREAMING | typeof RPC_ERROR_ENTRY_NOT_FOUND | typeof RPC_ERROR_MODEL_NOT_FOUND | typeof RPC_ERROR_NOT_ASSISTANT | typeof RPC_ERROR_NOT_USER | typeof RPC_ERROR_EMPTY_TEXT | typeof RPC_ERROR_UNKNOWN_COMMAND | typeof RPC_ERROR_STALE_LEAF | typeof RPC_ERROR_TURN_ACTIVE | typeof RPC_ERROR_SESSION_BUSY | typeof RPC_ERROR_ATTACHED | typeof RPC_ERROR_INVALID_RELEASE_REASON | typeof RPC_ERROR_RELEASE_UNSUPPORTED | typeof RPC_ERROR_RELEASE_FAILED | typeof RPC_ERROR_HOST_DRAINING;
+/** The supervisor has closed admission; a launch-owning caller may ensure a successor. */
+export declare const RPC_ERROR_HOST_STOPPING = "host_stopping";
+export type RpcErrorCode = typeof RPC_ERROR_HOST_STOPPING | typeof RPC_ERROR_UNKNOWN_SESSION | typeof RPC_ERROR_SESSION_CLOSING | typeof RPC_ERROR_SESSION_PATH_IN_USE | typeof RPC_ERROR_SESSION_HELD | typeof RPC_ERROR_SESSION_RESERVATION_LIMIT | typeof RPC_ERROR_MISSING_SESSION_ID | typeof RPC_ERROR_MULTI_SESSION_DISABLED | typeof RPC_ERROR_INVALID_PATH | typeof RPC_ERROR_OPEN_FAILED | typeof RPC_ERROR_MEDIA_NOT_FOUND | typeof RPC_ERROR_INVALID_SESSION_CONTEXT | typeof RPC_ERROR_INVALID_SESSION_KIND | typeof RPC_ERROR_INVALID_LAUNCH_PROFILE | typeof RPC_ERROR_INVALID_SESSION_ID | typeof RPC_ERROR_SESSION_ID_IN_USE | typeof RPC_ERROR_HOST_MEMORY_PRESSURE | typeof RPC_ERROR_WARM_FAILED | typeof RPC_ERROR_STREAMING | typeof RPC_ERROR_ENTRY_NOT_FOUND | typeof RPC_ERROR_MODEL_NOT_FOUND | typeof RPC_ERROR_EVAL_CELL_NOT_FOUND | typeof RPC_ERROR_INVALID_EVAL_CELL_REQUEST | typeof RPC_ERROR_EVAL_CELLS_UNAVAILABLE | typeof RPC_ERROR_NOT_ASSISTANT | typeof RPC_ERROR_NOT_USER | typeof RPC_ERROR_EMPTY_TEXT | typeof RPC_ERROR_UNKNOWN_COMMAND | typeof RPC_ERROR_STALE_LEAF | typeof RPC_ERROR_TURN_ACTIVE | typeof RPC_ERROR_SESSION_BUSY | typeof RPC_ERROR_ATTACHED | typeof RPC_ERROR_INVALID_RELEASE_REASON | typeof RPC_ERROR_RELEASE_UNSUPPORTED | typeof RPC_ERROR_RELEASE_FAILED | typeof RPC_ERROR_HOST_DRAINING;
 /** Every established command accepts an additive routing envelope. */
 export type RpcCommand = (RpcSessionCommand & {
     sessionId?: string;
@@ -707,6 +724,8 @@ export interface RpcProtocolIdentity {
     readonly launch_profile: RpcLaunchProfile;
 }
 export interface RpcProtocolInfo extends RpcProtocolIdentity {
+    /** Supervised socket hosts expose admission state independently of child responsiveness. */
+    readonly lifecycle?: "ready" | "stopping";
     readonly protocolVersion: 1;
     /** Informational engine version. Never compare it for compatibility - use the fields above. */
     readonly serverVersion: string;
@@ -1204,6 +1223,18 @@ export type RpcResponse = {
     command: "extension_request";
     success: true;
     data: unknown;
+} | {
+    id?: string;
+    type: "response";
+    command: "eval_cells.list";
+    success: true;
+    data: RpcEvalCell[];
+} | {
+    id?: string;
+    type: "response";
+    command: "eval_cells.peek" | "eval_cells.stop";
+    success: true;
+    data: RpcEvalCellSnapshot;
 } | {
     id?: string;
     type: "response";
@@ -1259,6 +1290,23 @@ export type RpcResponse = {
     errorCode?: string;
     errorData?: unknown;
 };
+/** Session-owned cell metadata; live and recently settled cells share the same list shape. */
+export interface RpcEvalCell {
+    readonly cellId: string;
+    readonly language: "js" | "py" | "rb" | "jl";
+    readonly state: "queued" | "running" | "detached" | "completed" | "failed" | "cancelled";
+    readonly startedAtMs: number;
+    readonly summary?: string;
+    readonly queuedBehind?: readonly string[];
+}
+/** Bounded text-only snapshot: no duplicated result body, code, or inline images. */
+export interface RpcEvalCellSnapshot extends RpcEvalCell {
+    readonly outputTail: string;
+    readonly stateRetained?: boolean;
+    readonly interruptNote?: string;
+    readonly hardLimitSeconds?: number;
+    readonly runBudgetSeconds?: number;
+}
 /** Success payload of `edit_assistant_message`. `leafId` is the session leaf after the call. */
 export type EditAssistantMessageResult = {
     outcome: "edited";

package/dist/modes/rpc/rpc-types.js

@@ -46,6 +46,9 @@ export const RPC_ERROR_STREAMING = "streaming";
 export const RPC_ERROR_ENTRY_NOT_FOUND = "not_found";
 /** `set_model` named a provider/model pair the session's registry does not offer. */
 export const RPC_ERROR_MODEL_NOT_FOUND = "model_not_found";
+export const RPC_ERROR_EVAL_CELL_NOT_FOUND = "eval_cell_not_found";
+export const RPC_ERROR_INVALID_EVAL_CELL_REQUEST = "invalid_eval_cell_request";
+export const RPC_ERROR_EVAL_CELLS_UNAVAILABLE = "eval_cells_unavailable";
 export const RPC_ERROR_NOT_ASSISTANT = "not_assistant";
 export const RPC_ERROR_NOT_USER = "not_user";
 export const RPC_ERROR_EMPTY_TEXT = "empty";
@@ -74,4 +77,6 @@ export const RPC_ERROR_RELEASE_UNSUPPORTED = "release_unsupported";
 export const RPC_ERROR_RELEASE_FAILED = "release_failed";
 /** A draining host parks every session itself; `release_session` and `open_session` are refused meanwhile. */
 export const RPC_ERROR_HOST_DRAINING = "host_draining";
+/** The supervisor has closed admission; a launch-owning caller may ensure a successor. */
+export const RPC_ERROR_HOST_STOPPING = "host_stopping";
 //# sourceMappingURL=rpc-types.js.map

package/dist/modes/rpc/session-command-activity.js

@@ -18,6 +18,8 @@ const observations = new Set([
     "get_auth_providers",
     "get_provider_accounts",
     "memory_report",
+    "eval_cells.list",
+    "eval_cells.peek",
 ]);
 export function refreshesSessionActivity(command) {
     return !observations.has(command);

package/dist/modes/rpc/session-held.js

@@ -25,6 +25,9 @@ const READ_ONLY_OR_CONTROL = new Set([
     "get_auth_providers",
     "get_provider_accounts",
     "memory_report",
+    "eval_cells.list",
+    "eval_cells.peek",
+    "eval_cells.stop",
     "export_html",
     "export_jsonl",
     "abort",

package/docs/extensions.md

@@ -709,7 +709,7 @@ The `systemPromptOptions` field gives extensions access to the same structured d
 
 Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
 
-`event.preview` is `true` when senpi composes the next turn's system prompt before any user prompt exists: the session-start prompt-cache prewarm sends the first turn's prefix ahead of time, and `ctx.getPromptCachePrefixRequest()` returns that prefix to extensions. In a preview `event.prompt` is empty and no turn follows.
+`event.preview` is `true` when senpi composes the next turn's system prompt before any user prompt exists. Prompt-cache prewarm sends that prefix only after the first real composer activity and only when `promptCache.keepAlive.enabled` is `true` (default `false`, so prewarm is off by default). Session start, resume, fork, reload, and extension-injected text never trigger prewarm. `ctx.getPromptCachePrefixRequest()` also returns this prefix to extensions. In a preview `event.prompt` is empty and no turn follows.
 
 A preview only reaches handlers that opt in with `{ previewSafe: true }`:
 
@@ -870,6 +870,8 @@ Fired before each LLM call. Modify messages non-destructively. See [Session Form
 
 `event.source` is `"agent"` for the live agent request and `"projection"` for `prepareProviderRequest` calls, including summarizer inputs. Projections must not advance state belonging to the live request, even when their messages match the branch. The session journal can lag a live request, so transcript equality is not a reliable substitute for this marker.
 
+`ctx.prepareProviderRequest(messages, excludeExtensionPath?, options?)` returns the projected context and its payload transform. In this release the transform excludes server-search tools by default, while retaining client function tools such as `web_search`. Call `ctx.prepareProviderRequest(messages, undefined, { allowServerSearch: true })` when a request must mirror the main turn's native tools and include fields, as keepalive does. Cache-friendly compaction retains the original main-turn payload hook separately; standalone summaries and session titles exclude server search.
+
 ```typescript
 pi.on("context", async (event, ctx) => {
   // event.messages - deep copy, safe to modify
@@ -1259,6 +1261,12 @@ Optional read-only getter for the absolute path to the current session's authori
 
 Shell tools and eval kernels expose this value as `PI_GOAL_STORE_FILE` and `ctx.cwd` as `PI_SESSION_CWD`. Hand-built contexts and older hosts may omit the getter, in which case `PI_GOAL_STORE_FILE` is unset.
 
+### ctx.onUserActivity()
+
+Optional subscription-only hook for host-authenticated activity. `ctx.onUserActivity(listener)` calls a synchronous listener with `"draft"` for actual terminal composer edits or `"prompt"` for user-originated prompt, steer, or follow-up admission, including RPC. It returns an unsubscribe function and is also removed when the extension generation retires. The host owns the emitter; `pi.events.emit("user_activity", ...)` cannot invoke this hook. Extension `pasteToEditor`, programmatic draft restoration, and lifecycle events do not publish activity.
+
+Cache prewarm consumes the first activity per session generation. It is opt-in via `promptCache.keepAlive.enabled` (default `false`): a first draft edit may prewarm, while prompt admission uses the real request instead of issuing an extra warm call. This one-shot policy does not gate the existing idle keep-alive loop after completed turns.
+
 ### ctx.modelRegistry / ctx.model / ctx.thinkingLevel / ctx.scopedModels
 
 Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective pi-ai provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.model` is the active model, and `ctx.thinkingLevel` is its current effective thinking level.
@@ -1329,6 +1337,10 @@ if (usage && usage.tokens > 100_000) {
 }
 ```
 
+### ctx.getCompactionModel()
+
+Optional on hosts that expose session-owned summarization routing. Returns the current session model while its account is usable, preserving builtin compaction behavior even when core compaction has a model override. For a spent account, it tries the held switch target, the configured summary override, then an authenticated alternate with enough context capacity for the active transcript and reserved output. It does not change the active session selection and throws an account-limit error when no usable summary model is available.
+
 ### ctx.compact()
 
 Trigger compaction without awaiting completion. Use `onComplete` and `onError` for follow-up actions.

package/docs/providers.md

@@ -4,6 +4,7 @@ Senpi supports subscription-based providers via OAuth and API key providers via
 
 ## Table of Contents
 
+- [In-Turn Web Search](#in-turn-web-search)
 - [Subscriptions](#subscriptions)
 - [API Keys](#api-keys)
 - [Auth File](#auth-file)
@@ -13,6 +14,93 @@ Senpi supports subscription-based providers via OAuth and API key providers via
 - [Custom Providers](#custom-providers)
 - [Resolution Order](#resolution-order)
 
+## In-Turn Web Search
+
+The session model uses its provider's server search before the standalone
+`web_search` tool. A successful native search does not issue an auxiliary
+request on another model. A search-specific request error or native result
+error records one `websearch-native-fallback` entry and enables the standalone
+tool for that session/model, including later prompts and switches back to it.
+Starting a new session clears the failed-model set. Existing core retries own their retry
+when one is already pending; otherwise the extension continues once after
+the agent settles. User cancellation never schedules that continuation.
+A provider that recovers from a failed search and completes its answer does
+not receive a duplicate continuation. Sonar's inherent retrieval has no
+independent server-tool error contract; its model errors remain with core
+retry rather than receiving unsupported function-tool definitions.
+Standalone summaries, session titles and default projections exclude only server-search tools, not client function declarations. Tool-less requests do not gain empty tool arrays. Cache-friendly compaction and keepalive retain the exact main-turn payload transform, tools and include fields.
+
+Anthropic Messages supports `web_search_20250305`. The direct Anthropic API and
+Claude OAuth retain main's default-on behavior. Anthropic-compatible gateways
+must explicitly declare search and replay support. For example, merge this override into your existing provider entry,
+keeping its current credential configuration:
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "baseUrl": "https://your-proxy.example/anthropic",
+      "modelOverrides": {
+        "claude-opus-5-5": {
+          "compat": { "supportsWebSearch": true }
+        }
+      }
+    }
+  }
+}
+```
+
+This opt-in was verified with a real ccapi search and exact encrypted-result
+replay. Senpi does not infer support from a proxy hostname. Anthropic requires
+the assistant blocks and their `encrypted_content` to be replayed unchanged.
+
+| Route | In-turn tool / API | Capability and replay contract |
+| --- | --- | --- |
+| Direct Anthropic API / Claude OAuth | `web_search_20250305`, Messages | Default-on (unchanged from main); `compat.supportsWebSearch: false` opts out. No new direct-endpoint probe is claimed here. |
+| Anthropic-compatible gateways, including ccapi | `web_search_20250305`, Messages | Opt-in `compat.supportsWebSearch: true`. ccapi search and encrypted-result replay verified live. |
+| OpenAI API / Azure | `web_search_preview`, Responses | Default-on (unchanged from main). Custom Responses endpoints remain opt-in `compat.supportsWebSearchPreview: true`. The current `web_search` name is also supported. |
+| ChatGPT/Codex subscription | `web_search`, Codex Responses | First-party subscription default, except Spark; custom endpoints require opt-in. Real search and output-item replay verified. |
+| xAI | `web_search`, Responses | Opt-in `compat.supportsWebSearchPreview: true`. Catalogs select the tool shape but do not enable it. Held OAuth probe: HTTP 403, not live-verified. |
+| Google Gemini / Vertex | `googleSearch`, GenerateContent | Opt-in `compat.supportsWebSearch: true` on Gemini 2/3. Held probe: HTTP 400 `API_KEY_INVALID`, not live-verified. Explicit mixed-tool rejection enables the session/model fallback. |
+| OpenRouter | `openrouter:web_search`, Chat Completions or Responses | Opt-in `compat.supportsWebSearch: true`; doc only, not live-verified. Uses OpenRouter's own tool shape. |
+| Moonshot PAYG | `$web_search` / `builtin_function`, Chat Completions | Opt-in `compat.supportsWebSearch: true`; doc only, not live-verified. Echoes server-generated arguments without another search request. Retires October 20, 2026. Cannot be discovered or lazily activated through tool_search, or declared on another route. |
+| Kimi for Coding | Anthropic-compatible Messages | Not live-verified (no personal credential). Coding-plan integration docs do not specify a server-search name/shape or replay contract. Not default-on; generic Messages opt-in is not verification. Follow-up [#3134](https://github.com/code-yeongyu/senpi/issues/3134). |
+| DeepSeek | Claude Code search on its Anthropic-compatible endpoint | Not live-verified (no personal credential). Claude Code docs claim API search but do not publish its raw shape/replay contract; a manually configured Messages route remains opt-in, not default-on. Built-in Chat Completions remains unsupported, and Responses docs list `web_search` as ignored. Follow-up [#3134](https://github.com/code-yeongyu/senpi/issues/3134). |
+| Z.AI PAYG chat | `web_search`, Chat Completions | Explicit `compat.supportsWebSearch: true` on that route; never enabled automatically on the coding-plan endpoint. |
+| GLM coding plan, z.ai Anthropic endpoint | `web_search_20250305`, Messages | Supported, opt-in `compat.supportsWebSearch: true`. Live response `msg_202610120132474ee314e9947c4ea2` returned server search with a `tool_result` block, which now remains visible and replays with its same-model server-tool pair even when the search usage counter is zero. OpenAI-compatible coding probe: not verified (length limit, no search payload); bigmodel.cn: not verified (HTTP 401, expired key). Remote MCP `webSearchPrime` remains a separate option. |
+| Perplexity Sonar | Search inherent in its main completion | No extra tool injection. Native-bypass routing is opt-in `compat.supportsWebSearch: true`; doc only, not live-verified. |
+| Exa, Tavily, Brave, Kagi, Serper, Serpdive, Keenable, Google CSE, SearXNG and result-page engines | Dedicated retrieval APIs/MCP | Standalone search fallbacks, not session-model server tools. |
+
+Official references:
+
+Custom xAI-compatible Responses entries declare both
+`supportsWebSearchPreview: true` and `webSearchToolType: "web_search"`.
+The type selection belongs to the model compatibility entry, not a provider-id
+or hostname guess. OpenAI-compatible endpoints that only support the legacy
+preview type can retain `webSearchToolType: "web_search_preview"`.
+
+- [Anthropic tool and replay](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)
+- [OpenAI Responses search](https://developers.openai.com/api/docs/guides/tools-web-search)
+- [Codex cached/live search](https://developers.openai.com/codex/config-basic/)
+- [xAI Responses search](https://docs.x.ai/developers/tools/web-search)
+- [Google grounding](https://ai.google.dev/gemini-api/docs/google-search)
+- [Google SDK examples](https://github.com/googleapis/js-genai/blob/main/codegen_instructions.md)
+- [OpenRouter server search](https://openrouter.ai/docs/guides/features/server-tools/web-search)
+- [Moonshot built-in flow](https://platform.kimi.ai/docs/guide/use-web-search)
+- [Kimi coding endpoint](https://www.kimi.com/code/docs/en/third-party-tools/claude-code)
+- [DeepSeek Claude Code integration](https://api-docs.deepseek.com/quick_start/agent_integrations/claude_code)
+- [DeepSeek Responses compatibility: built-in search ignored](https://api-docs.deepseek.com/guides/responses_api#tools)
+- [Z.AI PAYG chat search](https://docs.z.ai/guides/tools/web-search)
+- [GLM coding-plan search MCP](https://docs.z.ai/devpack/mcp/search-mcp-server)
+- [GLM Claude Code / Anthropic integration](https://docs.z.ai/devpack/tool/claude)
+- [Perplexity migration and conversation contract](https://docs.perplexity.ai/docs/sonar/quickstart)
+
+The `nativeModel` setting and cheaper same-provider defaults apply only to
+auxiliary search on routes without an in-turn server tool. They cannot
+preempt server search: a different `nativeModel` setting is ignored on an enabled
+server-search route. If an eligible route needs the standalone fallback,
+that retry uses the session model rather than swapping to a cheaper model.
+
 ## Subscriptions
 
 Use `/login` in interactive mode, then select a provider: