@zhin.js/host-http 1.0.6 → 1.0.9

package/lib/console-rpc.js

@@ -542,8 +542,8 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
             try {
                 const data = message;
                 const adapter = String(data.$adapter ?? '');
-                const endpointId = String(data.$endpoint ?? '');
-                if (!adapter || !endpointId) {
+                const endpointKey = String(data.$endpoint ?? '');
+                if (!adapter || !endpointKey) {
                     emit({ requestId, error: '$adapter and $endpoint required' });
                     return payloads;
                 }
@@ -551,7 +551,7 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                     emit({ requestId, error: 'Endpoint registry is not configured' });
                     return payloads;
                 }
-                const endpoint = await ctx.getEndpoint(adapter, endpointId);
+                const endpoint = await ctx.getEndpoint(adapter, endpointKey);
                 if (!endpoint) {
                     emit({ requestId, error: 'endpoint not found' });
                     return payloads;
@@ -570,12 +570,12 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
             try {
                 const data = message;
                 const adapter = String(data.$adapter ?? '');
-                const endpointId = String(data.$endpoint ?? '');
+                const endpointKey = String(data.$endpoint ?? '');
                 const channelId = String(data.$channel_id ?? '');
                 const channelType = String(data.$channel_type ?? '');
                 const content = data.$content;
                 // channelType 可省：wireConversation 归一为 private（与旧 RPC 行为对齐）。
-                if (!adapter || !endpointId || !channelId || content === undefined) {
+                if (!adapter || !endpointKey || !channelId || content === undefined) {
                     emit({
                         requestId,
                         error: '$adapter, $endpoint, $channel_id, $content required',
@@ -588,7 +588,7 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                 }
                 const result = await ctx.sendEndpointMessage({
                     adapter,
-                    endpointId,
+                    endpointKey,
                     conversation: wireConversation(channelType, channelId, data.$parent),
                     content,
                 });

package/lib/http-host.d.ts

@@ -1,5 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { type WebSocket } from 'ws';
+import { WebSocket } from 'ws';
+import { type GenerationAdmissionBindable } from '@zhin.js/plugin-runtime';
 import { TokenRegistry, type AuthScope, type ScopedTokenConfig } from './token-registry.js';
 import { type ListedRoute, type RouteMeta } from './openapi.js';
 export declare const REMOTE_CONSOLE_ORIGIN = "https://console.zhin.dev";
@@ -37,14 +38,16 @@ export type HttpHandler = (request: IncomingMessage, response: ServerResponse, u
 export interface HttpRouteRegistration {
     (): void;
 }
-export interface HttpHost {
+export interface HttpHost extends GenerationAdmissionBindable<HttpHost> {
     ws(path: string): WsHandle;
     route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
     listRoutes(): readonly ListedRoute[];
-    listen(): Promise<HttpHostAddress>;
-    close(): Promise<void>;
     get address(): HttpHostAddress | undefined;
     get tokenRegistry(): TokenRegistry;
 }
+export interface ProcessHttpHost extends HttpHost {
+    listen(): Promise<HttpHostAddress>;
+    close(): Promise<void>;
+}
 export declare const httpHostToken: import("@zhin.js/plugin-runtime").Token<HttpHost>;
-export declare function createHttpHost(options?: HttpHostOptions): HttpHost;
+export declare function createHttpHost(options?: HttpHostOptions): ProcessHttpHost;

package/lib/http-host.js

@@ -1,12 +1,12 @@
 import { createServer, } from 'node:http';
-import { WebSocketServer } from 'ws';
+import { WebSocket, WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { createToken } from '@zhin.js/plugin-runtime';
+import { createToken, generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
 import { TokenRegistry, extractBearerToken, isDemoWebSocketPath, } from './token-registry.js';
 import { buildOpenApiDocument, } from './openapi.js';
 import { isDemoHttpAllowed } from './console-rpc.js';
 import { HttpBodyError } from './json-body.js';
-const logger = getLogger('HttpHost');
+const logger = getLogger('http');
 export const REMOTE_CONSOLE_ORIGIN = 'https://console.zhin.dev';
 const DEFAULT_CORS_ORIGINS = Object.freeze([REMOTE_CONSOLE_ORIGIN]);
 export const httpHostToken = createToken('zhin.host.http');
@@ -26,6 +26,7 @@ export function createHttpHost(options = {}) {
     const httpRoutes = [];
     let address;
     let closed = false;
+    let closeResult;
     const server = createServer((request, response) => {
         void dispatchHttp(request, response);
     });
@@ -78,7 +79,13 @@ export function createHttpHost(options = {}) {
         }
         const pathname = upgradePath(request.url);
         const listeners = wsRoutes.get(pathname);
-        if (!listeners || listeners.size === 0) {
+        const admitted = listeners ? [...listeners].flatMap((entry) => {
+            const release = entry.admission?.acquire();
+            if (entry.admission && !release)
+                return [];
+            return [{ entry, release }];
+        }) : [];
+        if (admitted.length === 0) {
             logger.debug(formatCompact({ op: 'ws_upgrade_unmatched', path: pathname }));
             socket.destroy();
             return;
@@ -87,20 +94,46 @@ export function createHttpHost(options = {}) {
         if (!auth.ok) {
             socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
             socket.destroy();
+            for (const item of admitted)
+                item.release?.();
             return;
         }
         try {
             wss.handleUpgrade(request, socket, head, (ws) => {
+                let settled = false;
+                const retireSubscriptions = [];
+                const releaseAdmissions = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    for (const dispose of retireSubscriptions)
+                        dispose();
+                    for (const item of admitted)
+                        item.release?.();
+                };
+                ws.once('close', releaseAdmissions);
+                ws.once('error', releaseAdmissions);
+                for (const item of admitted) {
+                    if (item.entry.admission) {
+                        retireSubscriptions.push(item.entry.admission.onDeactivate(() => {
+                            if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                                ws.close(1012, 'Generation retired');
+                            }
+                        }));
+                    }
+                }
                 const connection = Object.freeze({
                     socket: ws,
                     request,
                     authScope: auth.scope,
                 });
-                for (const listener of listeners)
-                    listener(connection);
+                for (const item of admitted)
+                    item.entry.listener(connection);
             });
         }
         catch (err) {
+            for (const item of admitted)
+                item.release?.();
             logger.warn(formatCompact({
                 op: 'ws_upgrade_failed',
                 path: pathname,
@@ -178,7 +211,30 @@ export function createHttpHost(options = {}) {
                 applyCors(response, origin, corsOrigins);
             response.setHeader('X-Content-Type-Options', 'nosniff');
             response.setHeader('X-Frame-Options', 'SAMEORIGIN');
+            const release = route.admission?.acquire();
+            if (route.admission && !release) {
+                response.writeHead(503);
+                response.end();
+                return;
+            }
+            if (!release) {
+                await route.handler(request, response, url, auth.scope);
+                return;
+            }
+            let released = false;
+            const releaseResponse = () => {
+                if (released)
+                    return;
+                released = true;
+                response.off('finish', releaseResponse);
+                response.off('close', releaseResponse);
+                release();
+            };
+            response.once('finish', releaseResponse);
+            response.once('close', releaseResponse);
             await route.handler(request, response, url, auth.scope);
+            if (response.writableFinished || response.destroyed)
+                releaseResponse();
         }
         catch (err) {
             // 统一把请求体错误（400/413）映射回对应状态码，
@@ -219,57 +275,75 @@ export function createHttpHost(options = {}) {
         return { ok: true, scope };
     }
     function listListedRoutes() {
-        return Object.freeze(httpRoutes.map((route) => Object.freeze({
+        return Object.freeze(httpRoutes
+            .filter((route) => !route.admission || route.admission.active)
+            .map((route) => Object.freeze({
             method: route.method,
             pattern: route.pattern,
             meta: route.meta,
         })));
     }
-    return {
-        ws(pathname) {
-            const normalized = normalizePath(pathname);
-            let listeners = wsRoutes.get(normalized);
-            if (!listeners) {
-                listeners = new Set();
-                wsRoutes.set(normalized, listeners);
-            }
-            const owned = new Set();
-            return {
-                onConnection(listener) {
-                    listeners.add(listener);
-                    owned.add(listener);
-                    return () => {
-                        listeners.delete(listener);
-                        owned.delete(listener);
-                    };
-                },
-                close() {
-                    for (const listener of owned)
-                        listeners.delete(listener);
-                    owned.clear();
-                },
-            };
-        },
-        route(method, path, handler, meta) {
-            const normalizedMethod = method.toUpperCase();
-            const prefix = path.endsWith('/*');
-            const normalizedPath = normalizePath(prefix ? path.slice(0, -2) : path);
-            const pattern = prefix ? `${normalizedPath}/*` : normalizedPath;
-            const entry = Object.freeze({
-                method: normalizedMethod,
-                path: normalizedPath,
-                pattern,
-                prefix,
-                handler,
-                meta,
-            });
-            httpRoutes.push(entry);
-            return () => {
-                const index = httpRoutes.indexOf(entry);
-                if (index >= 0)
-                    httpRoutes.splice(index, 1);
-            };
-        },
+    function registerWs(pathname, admission) {
+        const normalized = normalizePath(pathname);
+        let listeners = wsRoutes.get(normalized);
+        if (!listeners) {
+            listeners = new Set();
+            wsRoutes.set(normalized, listeners);
+        }
+        const owned = new Set();
+        return {
+            onConnection(listener) {
+                const entry = Object.freeze({ listener, admission });
+                listeners.add(entry);
+                owned.add(entry);
+                return () => {
+                    listeners.delete(entry);
+                    owned.delete(entry);
+                };
+            },
+            close() {
+                for (const entry of owned)
+                    listeners.delete(entry);
+                owned.clear();
+            },
+        };
+    }
+    function registerRoute(method, path, handler, meta, admission) {
+        const normalizedMethod = method.toUpperCase();
+        const prefix = path.endsWith('/*');
+        const normalizedPath = normalizePath(prefix ? path.slice(0, -2) : path);
+        const pattern = prefix ? `${normalizedPath}/*` : normalizedPath;
+        const entry = Object.freeze({
+            method: normalizedMethod,
+            path: normalizedPath,
+            pattern,
+            prefix,
+            handler,
+            meta,
+            admission,
+        });
+        httpRoutes.push(entry);
+        return () => {
+            const index = httpRoutes.indexOf(entry);
+            if (index >= 0)
+                httpRoutes.splice(index, 1);
+        };
+    }
+    function createBoundHost(admission) {
+        const bound = {
+            [generationAdmissionBinder]: (next) => createBoundHost(next),
+            ws: (path) => registerWs(path, admission),
+            route: (method, path, handler, meta) => registerRoute(method, path, handler, meta, admission),
+            listRoutes: () => listListedRoutes(),
+            get address() { return runtime.address; },
+            get tokenRegistry() { return tokenRegistry; },
+        };
+        return Object.freeze(bound);
+    }
+    const runtime = {
+        [generationAdmissionBinder]: (admission) => createBoundHost(admission),
+        ws: (pathname) => registerWs(pathname),
+        route: (method, path, handler, meta) => registerRoute(method, path, handler, meta),
         listRoutes() {
             return listListedRoutes();
         },
@@ -290,31 +364,30 @@ export function createHttpHost(options = {}) {
                     const listenPort = typeof bound === 'object' && bound ? bound.port : port;
                     const publicHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
                     address = Object.freeze({ host: publicHost, port: listenPort });
-                    logger.info(formatCompact({
-                        http: `http://${publicHost}:${listenPort}`,
-                        token: tokenRegistry.hasAnyToken()
+                    logger.info(`listening http://${publicHost}:${listenPort}`
+                        + ` | routes: ${httpRoutes.length}`
+                        + ` | token: ${tokenRegistry.hasAnyToken()
                             ? `${tokenRegistry.primaryTokenPrefixForLog()}…`
-                            : '(none)',
-                        cors: corsOrigins.join(','),
-                        ws_routes: [...wsRoutes.keys()].join(',') || '(none)',
-                        http_routes: httpRoutes.length,
-                    }));
+                            : '(none)'}`);
+                    logger.debug(`listen detail | cors: ${corsOrigins.join(',')}`
+                        + ` | ws: ${[...wsRoutes.keys()].join(',') || '(none)'}`);
                     resolve(address);
                 });
             });
         },
         close() {
-            if (closed)
-                return Promise.resolve();
+            if (closeResult)
+                return closeResult;
             closed = true;
             wsRoutes.clear();
             httpRoutes.length = 0;
             // Rollback paths dispose a host whose generation never reached listen().
             if (!server.listening) {
                 address = undefined;
-                return Promise.resolve();
+                closeResult = Promise.resolve();
+                return closeResult;
             }
-            return new Promise((resolve, reject) => {
+            closeResult = new Promise((resolve, reject) => {
                 // Long-lived connections (SSE, keep-alive, WS) never end on their own:
                 // destroy tracked sockets and terminate WS clients before close(),
                 // otherwise the close callbacks would never fire.
@@ -339,8 +412,10 @@ export function createHttpHost(options = {}) {
                     });
                 });
             });
+            return closeResult;
         },
     };
+    return runtime;
 }
 function requiresHttpAuth(pathname, apiBase, authExempt) {
     if (pathname === '/pub' || pathname.startsWith('/pub/'))
@@ -380,6 +455,8 @@ function matchHttpRoute(routes, method, pathname) {
     let best;
     let bestLength = -1;
     for (const route of routes) {
+        if (route.admission && !route.admission.active)
+            continue;
         if (route.method !== method && route.method !== 'ALL')
             continue;
         if (route.prefix) {

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type HttpHostAddress, type HttpHostOptions, type HttpRouteRegistration, type WsConnection, type WsHandle, } from './http-host.js';
+export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type ProcessHttpHost, type HttpHostAddress, type HttpHostOptions, type HttpRouteRegistration, type WsConnection, type WsHandle, } from './http-host.js';
 export { TokenRegistry, extractBearerToken, isDemoWebSocketPath, type AuthScope, type ScopedTokenConfig, type TokenRegistryConfig, } from './token-registry.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export { createConsoleEventHub, type ConsoleEventHub, } from './console-events.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,10 +18,10 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.1.0",
-    "@zhin.js/host-http-contract": "1.0.0",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.3"
+    "@zhin.js/console-protocol": "1.1.1",
+    "@zhin.js/host-http-contract": "1.0.1",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/plugin-runtime": "1.1.6"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/console-rest-pages.ts

@@ -32,7 +32,10 @@ export interface ConsoleRestCtx {
    * 可选：返回新 Runtime 的 agent 门面（见 {@link ConsoleAgentRuntime}）。
    * 未接线时 introspection 降级为空列表 + note，session tree 返回 503。
    */
-  readonly getAgentRuntime?: () => unknown;
+  readonly acquireAgentRuntime?: () => {
+    readonly value: ConsoleAgentRuntime;
+    release(): void;
+  } | null;
   /** Database host（logs 页数据源：SystemLog 模型）。 */
   readonly databaseHost?: {
     readonly dialect: string;
@@ -65,7 +68,7 @@ export interface ConsoleAgentSessionTree {
   ): Promise<{ ok: boolean; message: string }>;
 }
 
-/** `ctx.getAgentRuntime()` 返回值的最小结构约定（全部可选，逐项降级）。 */
+/** `ctx.acquireAgentRuntime()` 返回值的最小结构约定（全部可选，逐项降级）。 */
 export interface ConsoleAgentRuntime {
   readonly introspection?: ConsoleAgentIntrospection;
   readonly sessionTree?: ConsoleAgentSessionTree;
@@ -626,7 +629,7 @@ function registerIntrospectionRoutes(
         const degradedNote = note ?? (missing
           ? kind === 'endpoints'
             ? 'Endpoints 数据源未接线（ctx.getEndpoints 缺失）'
-            : 'Agent runtime 未装配（basic/cli 未接线 getAgentRuntime）'
+            : 'Agent runtime 未装配（basic/cli 未接线 acquireAgentRuntime）'
           : undefined);
         writeJson(response, 200, {
           success: true,
@@ -644,8 +647,13 @@ function registerIntrospectionRoutes(
 }
 
 function agentIntrospection(ctx: ConsoleRestCtx): ConsoleAgentIntrospection | undefined {
-  const runtime = ctx.getAgentRuntime?.() as ConsoleAgentRuntime | null | undefined;
-  return runtime && typeof runtime === 'object' ? runtime.introspection : undefined;
+  const lease = ctx.acquireAgentRuntime?.();
+  if (!lease) return undefined;
+  try {
+    return lease.value.introspection;
+  } finally {
+    lease.release();
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -658,17 +666,22 @@ function registerAgentSessionRoutes(
   ctx: ConsoleRestCtx,
 ): void {
   const prefix = `${base}/agent/sessions/`;
-  const getSessionTree = (): ConsoleAgentSessionTree | null => {
-    const runtime = ctx.getAgentRuntime?.() as ConsoleAgentRuntime | null | undefined;
-    const tree = runtime && typeof runtime === 'object' ? runtime.sessionTree : undefined;
-    if (!tree) return null;
-    if (typeof tree.resolveActiveSessionId !== 'function') return null;
-    return tree;
+  const acquireSessionTree = (): {
+    readonly tree: ConsoleAgentSessionTree;
+    release(): void;
+  } | null => {
+    const lease = ctx.acquireAgentRuntime?.();
+    const tree = lease?.value.sessionTree;
+    if (!lease || !tree || typeof tree.resolveActiveSessionId !== 'function') {
+      lease?.release();
+      return null;
+    }
+    return { tree, release: () => lease.release() };
   };
   const unavailable = (response: ServerResponse) => {
     writeJson(response, 503, {
       success: false,
-      error: 'Agent session tree runtime 未就绪（新 Runtime 需经 getAgentRuntime 装配 sessionTree）',
+      error: 'Agent session tree runtime 未就绪（新 Runtime 需经 acquireAgentRuntime 装配 sessionTree）',
     });
   };
 
@@ -679,32 +692,36 @@ function registerAgentSessionRoutes(
       writeJson(response, 404, { success: false, error: 'Not found' });
       return;
     }
-    const runtime = getSessionTree();
-    if (!runtime) {
+    const lease = acquireSessionTree();
+    if (!lease) {
       unavailable(response);
       return;
     }
+    const runtime = lease.tree;
+    try {
+      const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
+      if (!sessionId) {
+        writeJson(response, 404, {
+          success: false,
+          error: `未找到活跃会话：${parsed.sessionKey}`,
+        });
+        return;
+      }
 
-    const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
-    if (!sessionId) {
-      writeJson(response, 404, {
-        success: false,
-        error: `未找到活跃会话：${parsed.sessionKey}`,
+      const session = await runtime.agentSessionStore.getBySessionId(sessionId);
+      const points = await runtime.listBranchPoints(sessionId);
+      writeJson(response, 200, {
+        success: true,
+        data: {
+          sessionKey: parsed.sessionKey,
+          sessionId,
+          activeLeafMessageId: session?.active_leaf_message_id ?? null,
+          points,
+        },
       });
-      return;
+    } finally {
+      lease.release();
     }
-
-    const session = await runtime.agentSessionStore.getBySessionId(sessionId);
-    const points = await runtime.listBranchPoints(sessionId);
-    writeJson(response, 200, {
-      success: true,
-      data: {
-        sessionKey: parsed.sessionKey,
-        sessionId,
-        activeLeafMessageId: session?.active_leaf_message_id ?? null,
-        points,
-      },
-    });
   }, { summary: 'Get agent session tree', tags: ['console', 'agent'] });
 
   route('POST', `${base}/agent/sessions/*`, async (request, response, url, authScope) => {
@@ -714,21 +731,6 @@ function registerAgentSessionRoutes(
       return;
     }
     if (!requireWriteScope(response, ctx, authScope)) return;
-    const runtime = getSessionTree();
-    if (!runtime) {
-      unavailable(response);
-      return;
-    }
-
-    const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
-    if (!sessionId) {
-      writeJson(response, 404, {
-        success: false,
-        error: `未找到活跃会话：${parsed.sessionKey}`,
-      });
-      return;
-    }
-
     let body: Record<string, unknown>;
     try {
       body = (await readJsonBody(request) ?? {}) as Record<string, unknown>;
@@ -741,49 +743,72 @@ function registerAgentSessionRoutes(
     }
     const messageIdRaw = body.messageId;
     const indexRaw = body.index;
-
     let messageId: number | undefined;
+    let branchIndex: number | undefined;
     if (messageIdRaw != null && messageIdRaw !== '') {
-      const n = Number(messageIdRaw);
-      if (!Number.isFinite(n) || n < 1) {
+      const value = Number(messageIdRaw);
+      if (!Number.isFinite(value) || value < 1) {
         writeJson(response, 400, { success: false, error: 'messageId 须为正整数' });
         return;
       }
-      messageId = n;
+      messageId = value;
     } else if (indexRaw != null && indexRaw !== '') {
-      const index = Number(indexRaw);
-      if (!Number.isFinite(index) || index < 1) {
+      const value = Number(indexRaw);
+      if (!Number.isFinite(value) || value < 1) {
         writeJson(response, 400, { success: false, error: 'index 须为正整数' });
         return;
       }
-      const result = await runtime.jumpToBranchIndex(sessionId, index);
+      branchIndex = value;
+    } else {
+      writeJson(response, 400, { success: false, error: '需要 messageId 或 index 之一' });
+      return;
+    }
+
+    const lease = acquireSessionTree();
+    if (!lease) {
+      unavailable(response);
+      return;
+    }
+    const runtime = lease.tree;
+    try {
+      const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
+      if (!sessionId) {
+        writeJson(response, 404, {
+          success: false,
+          error: `未找到活跃会话：${parsed.sessionKey}`,
+        });
+        return;
+      }
+
+      if (branchIndex !== undefined) {
+        const result = await runtime.jumpToBranchIndex(sessionId, branchIndex);
+        const session = await runtime.agentSessionStore.getBySessionId(sessionId);
+        writeJson(response, result.ok ? 200 : 400, {
+          success: result.ok,
+          message: result.message,
+          data: {
+            sessionKey: parsed.sessionKey,
+            sessionId,
+            activeLeafMessageId: session?.active_leaf_message_id ?? null,
+          },
+        });
+        return;
+      }
+
+      const ok = await runtime.switchActiveLeaf(sessionId, messageId!);
       const session = await runtime.agentSessionStore.getBySessionId(sessionId);
-      writeJson(response, result.ok ? 200 : 400, {
-        success: result.ok,
-        message: result.message,
+      writeJson(response, ok ? 200 : 400, {
+        success: ok,
+        message: ok ? `已切换 active leaf 至消息 #${messageId}` : '切换失败',
         data: {
           sessionKey: parsed.sessionKey,
           sessionId,
           activeLeafMessageId: session?.active_leaf_message_id ?? null,
         },
       });
-      return;
-    } else {
-      writeJson(response, 400, { success: false, error: '需要 messageId 或 index 之一' });
-      return;
+    } finally {
+      lease.release();
     }
-
-    const ok = await runtime.switchActiveLeaf(sessionId, messageId);
-    const session = await runtime.agentSessionStore.getBySessionId(sessionId);
-    writeJson(response, ok ? 200 : 400, {
-      success: ok,
-      message: ok ? `已切换 active leaf 至消息 #${messageId}` : '切换失败',
-      data: {
-        sessionKey: parsed.sessionKey,
-        sessionId,
-        activeLeafMessageId: session?.active_leaf_message_id ?? null,
-      },
-    });
   }, { summary: 'Switch agent session active leaf', tags: ['console', 'agent'] });
 }