@zhin.js/host-http 1.0.6 → 1.0.8

package/lib/console-rest-pages.d.ts

@@ -14,7 +14,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;
@@ -49,7 +52,7 @@ export interface ConsoleAgentSessionTree {
         message: string;
     }>;
 }
-/** `ctx.getAgentRuntime()` 返回值的最小结构约定（全部可选，逐项降级）。 */
+/** `ctx.acquireAgentRuntime()` 返回值的最小结构约定（全部可选，逐项降级）。 */
 export interface ConsoleAgentRuntime {
     readonly introspection?: ConsoleAgentIntrospection;
     readonly sessionTree?: ConsoleAgentSessionTree;

package/lib/console-rest-pages.js

@@ -448,7 +448,7 @@ function registerIntrospectionRoutes(route, base, ctx) {
                 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,
@@ -466,27 +466,34 @@ function registerIntrospectionRoutes(route, base, ctx) {
     }
 }
 function agentIntrospection(ctx) {
-    const runtime = ctx.getAgentRuntime?.();
-    return runtime && typeof runtime === 'object' ? runtime.introspection : undefined;
+    const lease = ctx.acquireAgentRuntime?.();
+    if (!lease)
+        return undefined;
+    try {
+        return lease.value.introspection;
+    }
+    finally {
+        lease.release();
+    }
 }
 // ---------------------------------------------------------------------------
 // agent sessions（legacy agent-sessions-rest-api.ts；ADR 0010 D3）
 // ---------------------------------------------------------------------------
 function registerAgentSessionRoutes(route, base, ctx) {
     const prefix = `${base}/agent/sessions/`;
-    const getSessionTree = () => {
-        const runtime = ctx.getAgentRuntime?.();
-        const tree = runtime && typeof runtime === 'object' ? runtime.sessionTree : undefined;
-        if (!tree)
+    const acquireSessionTree = () => {
+        const lease = ctx.acquireAgentRuntime?.();
+        const tree = lease?.value.sessionTree;
+        if (!lease || !tree || typeof tree.resolveActiveSessionId !== 'function') {
+            lease?.release();
             return null;
-        if (typeof tree.resolveActiveSessionId !== 'function')
-            return null;
-        return tree;
+        }
+        return { tree, release: () => lease.release() };
     };
     const unavailable = (response) => {
         writeJson(response, 503, {
             success: false,
-            error: 'Agent session tree runtime 未就绪（新 Runtime 需经 getAgentRuntime 装配 sessionTree）',
+            error: 'Agent session tree runtime 未就绪（新 Runtime 需经 acquireAgentRuntime 装配 sessionTree）',
         });
     };
     // HttpHost 无 `:param` 路由，用前缀路由匹配 `<sessionKey>/tree|leaf`。
@@ -496,30 +503,36 @@ function registerAgentSessionRoutes(route, base, ctx) {
             writeJson(response, 404, { success: false, error: 'Not found' });
             return;
         }
-        const runtime = getSessionTree();
-        if (!runtime) {
+        const lease = acquireSessionTree();
+        if (!lease) {
             unavailable(response);
             return;
         }
-        const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
-        if (!sessionId) {
-            writeJson(response, 404, {
-                success: false,
-                error: `未找到活跃会话：${parsed.sessionKey}`,
+        const runtime = lease.tree;
+        try {
+            const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
+            if (!sessionId) {
+                writeJson(response, 404, {
+                    success: false,
+                    error: `未找到活跃会话：${parsed.sessionKey}`,
+                });
+                return;
+            }
+            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;
         }
-        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,
-            },
-        });
+        finally {
+            lease.release();
+        }
     }, { summary: 'Get agent session tree', tags: ['console', 'agent'] });
     route('POST', `${base}/agent/sessions/*`, async (request, response, url, authScope) => {
         const parsed = parseSessionAction(url.pathname, prefix, 'leaf');
@@ -529,19 +542,6 @@ function registerAgentSessionRoutes(route, base, ctx) {
         }
         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;
         try {
             body = (await readJsonBody(request) ?? {});
@@ -556,48 +556,71 @@ function registerAgentSessionRoutes(route, base, ctx) {
         const messageIdRaw = body.messageId;
         const indexRaw = body.index;
         let messageId;
+        let branchIndex;
         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'] });
 }
 function parseSessionAction(pathname, prefix, action) {

package/lib/console-rpc-extended.d.ts

@@ -21,9 +21,9 @@ export interface ConsoleRpcExtendedCtx {
     /** Plugin Runtime ScheduleHost（basic/cli schedule-host-installer 提供）。 */
     scheduleHost?: unknown;
     /** 经 ImRuntime / AdapterEndpointIndex 解析管理语义端口。 */
-    resolveEndpointManagement?: (adapter: string, endpointId: string) => EndpointManagementPort | null | undefined;
+    resolveEndpointManagement?: (adapter: string, endpointKey: string) => EndpointManagementPort | null | undefined;
     /** @deprecated Use `resolveEndpointManagement`; accepted for one compatibility cycle. */
-    resolveEndpoint?: (adapter: string, endpointId: string) => unknown;
+    resolveEndpoint?: (adapter: string, endpointKey: string) => unknown;
     /** Plugin Runtime DatabaseHost 的 models 视图。 */
     databaseHost?: {
         models: {

package/lib/console-rpc-extended.js

@@ -225,14 +225,14 @@ async function readInboxRows(ctx, table, where, options) {
 }
 async function listInbox(d, ctx, table, key, mapRow) {
     const adapter = strField(d, '$adapter', 'adapter');
-    const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
-    if (!adapter || !endpointId)
+    const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
+    if (!adapter || !endpointKey)
         return { error: '$adapter and $endpoint required' };
     const limit = Math.min(numField(d, 30, '$limit', 'limit'), 100);
     const offset = Math.max(0, numField(d, 0, '$offset', 'offset'));
     const { rows, enabled } = await readInboxRows(ctx, table, {
         adapter,
-        endpoint_id: endpointId,
+        endpoint_id: endpointKey,
     }, {
         // sort/limit 下推到 DB 侧（内存 sort/slice 保留，作为无下推能力模型的兜底）
         orderBy: { field: 'created_at', direction: 'DESC' },
@@ -248,12 +248,12 @@ async function listInbox(d, ctx, table, key, mapRow) {
 /** request.list —— 未处理的好友/群请求（unified_inbox_request 中 resolved=0）。 */
 async function listPendingRequests(d, ctx) {
     const adapter = strField(d, '$adapter', 'adapter');
-    const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
-    if (!adapter || !endpointId)
+    const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
+    if (!adapter || !endpointKey)
         return { error: '$adapter and $endpoint required' };
     const { rows, enabled } = await readInboxRows(ctx, TABLE_REQUEST, {
         adapter,
-        endpoint_id: endpointId,
+        endpoint_id: endpointKey,
     }, {
         orderBy: { field: 'created_at', direction: 'ASC' },
     });
@@ -265,10 +265,10 @@ async function listPendingRequests(d, ctx) {
 }
 async function listInboxMessages(d, ctx) {
     const adapter = strField(d, '$adapter', 'adapter');
-    const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+    const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
     const channelId = strField(d, '$channel_id', 'channelId', 'channel_id');
     const channelType = strField(d, '$channel_type', 'channelType', 'channel_type');
-    if (!adapter || !endpointId || !channelId || !channelType) {
+    if (!adapter || !endpointKey || !channelId || !channelType) {
         return { error: '$adapter, $endpoint, $channel_id, $channel_type required' };
     }
     const limit = Math.min(numField(d, 50, '$limit', 'limit'), 100);
@@ -277,7 +277,7 @@ async function listInboxMessages(d, ctx) {
     const parent = normalizeParent(d.$parent ?? d.parent);
     const where = {
         adapter,
-        endpoint_id: endpointId,
+        endpoint_id: endpointKey,
         channel_id: channelId,
         channel_type: channelType,
     };
@@ -393,12 +393,12 @@ async function markInboxConsumed(d, ctx, table) {
 // ---------------------------------------------------------------- 请求审批
 async function actOnRequest(type, d, ctx) {
     const adapter = strField(d, '$adapter', 'adapter');
-    const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+    const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
     const requestId = strField(d, '$id', 'id', 'platformRequestId', 'platform_request_id', 'requestId');
-    if (!adapter || !endpointId || !requestId) {
+    if (!adapter || !endpointKey || !requestId) {
         return { error: '$adapter, $endpoint, $id required' };
     }
-    const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
+    const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
     if ('error' in resolved)
         return resolved;
     const management = resolved.management;
@@ -472,12 +472,12 @@ async function listChannels(d, ctx) {
 }
 async function listGroupMembers(d, ctx) {
     const adapter = strField(d, '$adapter', 'adapter');
-    const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+    const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
     const groupId = strField(d, '$group_id', 'groupId', 'group_id');
-    if (!adapter || !endpointId || !groupId) {
+    if (!adapter || !endpointKey || !groupId) {
         return { error: '$adapter, $endpoint, $group_id required' };
     }
-    const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
+    const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
     if ('error' in resolved)
         return resolved;
     const { management } = resolved;
@@ -495,16 +495,16 @@ async function listGroupMembers(d, ctx) {
 }
 async function groupWriteOp(d, ctx, spec) {
     const adapter = strField(d, '$adapter', 'adapter');
-    const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+    const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
     const groupId = strField(d, '$group_id', 'groupId', 'group_id');
     const userId = strField(d, '$user_id', 'userId', 'user_id');
-    if (!adapter || !endpointId || !groupId) {
+    if (!adapter || !endpointKey || !groupId) {
         return { error: '$adapter, $endpoint, $group_id required' };
     }
     if (spec.requireUser && !userId) {
         return { error: '$user_id required' };
     }
-    const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
+    const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
     if ('error' in resolved)
         return resolved;
     const { management } = resolved;
@@ -530,12 +530,12 @@ async function groupWriteOp(d, ctx, spec) {
 }
 async function deleteFriend(d, ctx) {
     const adapter = strField(d, '$adapter', 'adapter');
-    const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+    const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
     const userId = strField(d, '$user_id', 'userId', 'user_id');
-    if (!adapter || !endpointId || !userId) {
+    if (!adapter || !endpointKey || !userId) {
         return { error: '$adapter, $endpoint, $user_id required' };
     }
-    const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
+    const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
     if ('error' in resolved)
         return resolved;
     const { management } = resolved;
@@ -592,17 +592,17 @@ function numArrayField(d, ...keys) {
     }
     return [];
 }
-function resolveLiveEndpoint(ctx, adapter, endpointId) {
+function resolveLiveEndpoint(ctx, adapter, endpointKey) {
     if (ctx.resolveEndpointManagement) {
-        const management = ctx.resolveEndpointManagement(adapter, endpointId);
+        const management = ctx.resolveEndpointManagement(adapter, endpointKey);
         if (!management)
             return { error: 'endpoint not found' };
-        return { management, adapter, endpointId };
+        return { management, adapter, endpointKey };
     }
     if (!ctx.resolveEndpoint) {
         return { error: 'Endpoint registry is not configured' };
     }
-    const endpoint = ctx.resolveEndpoint(adapter, endpointId);
+    const endpoint = ctx.resolveEndpoint(adapter, endpointKey);
     if (!endpoint || typeof endpoint !== 'object') {
         return { error: 'endpoint not found' };
     }
@@ -612,15 +612,15 @@ function resolveLiveEndpoint(ctx, adapter, endpointId) {
             ? management
             : {},
         adapter,
-        endpointId,
+        endpointKey,
     };
 }
 function requireEndpoint(d, ctx) {
     const adapter = strField(d, '$adapter', 'adapter');
-    const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
-    if (!adapter || !endpointId)
+    const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
+    if (!adapter || !endpointKey)
         return { error: '$adapter and $endpoint required' };
-    return resolveLiveEndpoint(ctx, adapter, endpointId);
+    return resolveLiveEndpoint(ctx, adapter, endpointKey);
 }
 function normalizeParent(raw) {
     if (!raw || typeof raw !== 'object')

package/lib/console-rpc.d.ts

@@ -68,7 +68,7 @@ export type RuntimeConsoleRpcContext = {
     getAllSchemas?(): Promise<Record<string, unknown>>;
     /** Optional Adapter endpoint Console surface (Sandbox / Remote Console). */
     listEndpoints?(): Promise<readonly RuntimeEndpointSummary[]>;
-    getEndpoint?(adapter: string, endpointId: string): Promise<RuntimeEndpointSummary | null>;
+    getEndpoint?(adapter: string, endpointKey: string): Promise<RuntimeEndpointSummary | null>;
     sendEndpointMessage?(input: RuntimeEndpointSendInput): Promise<{
         messageId: string;
     }>;
@@ -96,7 +96,7 @@ export type RuntimeDatabaseInfo = {
 };
 export type RuntimeEndpointSendInput = {
     readonly adapter: string;
-    readonly endpointId: string;
+    readonly endpointKey: string;
     readonly conversation: ConversationAddress;
     readonly content: unknown;
 };

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.js

@@ -6,7 +6,7 @@ import { TokenRegistry, extractBearerToken, isDemoWebSocketPath, } from './token
 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');
@@ -290,15 +290,13 @@ 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);
                 });
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "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.5"
   },
   "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'] });
 }
 

package/src/console-rpc-extended.ts

@@ -34,10 +34,10 @@ export interface ConsoleRpcExtendedCtx {
   /** 经 ImRuntime / AdapterEndpointIndex 解析管理语义端口。 */
   resolveEndpointManagement?: (
     adapter: string,
-    endpointId: string,
+    endpointKey: string,
   ) => EndpointManagementPort | null | undefined;
   /** @deprecated Use `resolveEndpointManagement`; accepted for one compatibility cycle. */
-  resolveEndpoint?: (adapter: string, endpointId: string) => unknown;
+  resolveEndpoint?: (adapter: string, endpointKey: string) => unknown;
   /** Plugin Runtime DatabaseHost 的 models 视图。 */
   databaseHost?: { models: { get(name: string): unknown } };
   /** Agent Host 持久化调度引擎（@zhin.js/agent getAssistantRuntime().engine），未 init 时返回 null。 */
@@ -340,13 +340,13 @@ async function listInbox(
   mapRow: (row: Record<string, unknown>) => Record<string, unknown>,
 ): Promise<ExtendedRpcResult> {
   const adapter = strField(d, '$adapter', 'adapter');
-  const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
-  if (!adapter || !endpointId) return { error: '$adapter and $endpoint required' };
+  const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
+  if (!adapter || !endpointKey) return { error: '$adapter and $endpoint required' };
   const limit = Math.min(numField(d, 30, '$limit', 'limit'), 100);
   const offset = Math.max(0, numField(d, 0, '$offset', 'offset'));
   const { rows, enabled } = await readInboxRows(ctx, table, {
     adapter,
-    endpoint_id: endpointId,
+    endpoint_id: endpointKey,
   }, {
     // sort/limit 下推到 DB 侧（内存 sort/slice 保留，作为无下推能力模型的兜底）
     orderBy: { field: 'created_at', direction: 'DESC' },
@@ -366,11 +366,11 @@ async function listPendingRequests(
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
   const adapter = strField(d, '$adapter', 'adapter');
-  const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
-  if (!adapter || !endpointId) return { error: '$adapter and $endpoint required' };
+  const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
+  if (!adapter || !endpointKey) return { error: '$adapter and $endpoint required' };
   const { rows, enabled } = await readInboxRows(ctx, TABLE_REQUEST, {
     adapter,
-    endpoint_id: endpointId,
+    endpoint_id: endpointKey,
   }, {
     orderBy: { field: 'created_at', direction: 'ASC' },
   });
@@ -386,10 +386,10 @@ async function listInboxMessages(
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
   const adapter = strField(d, '$adapter', 'adapter');
-  const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+  const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
   const channelId = strField(d, '$channel_id', 'channelId', 'channel_id');
   const channelType = strField(d, '$channel_type', 'channelType', 'channel_type');
-  if (!adapter || !endpointId || !channelId || !channelType) {
+  if (!adapter || !endpointKey || !channelId || !channelType) {
     return { error: '$adapter, $endpoint, $channel_id, $channel_type required' };
   }
   const limit = Math.min(numField(d, 50, '$limit', 'limit'), 100);
@@ -399,7 +399,7 @@ async function listInboxMessages(
 
   const where: Record<string, unknown> = {
     adapter,
-    endpoint_id: endpointId,
+    endpoint_id: endpointKey,
     channel_id: channelId,
     channel_type: channelType,
   };
@@ -525,12 +525,12 @@ async function actOnRequest(
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
   const adapter = strField(d, '$adapter', 'adapter');
-  const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+  const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
   const requestId = strField(d, '$id', 'id', 'platformRequestId', 'platform_request_id', 'requestId');
-  if (!adapter || !endpointId || !requestId) {
+  if (!adapter || !endpointKey || !requestId) {
     return { error: '$adapter, $endpoint, $id required' };
   }
-  const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
+  const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
   if ('error' in resolved) return resolved;
   const management = resolved.management;
   const approve = type === 'request.approve';
@@ -613,12 +613,12 @@ async function listGroupMembers(
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
   const adapter = strField(d, '$adapter', 'adapter');
-  const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+  const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
   const groupId = strField(d, '$group_id', 'groupId', 'group_id');
-  if (!adapter || !endpointId || !groupId) {
+  if (!adapter || !endpointKey || !groupId) {
     return { error: '$adapter, $endpoint, $group_id required' };
   }
-  const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
+  const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
   if ('error' in resolved) return resolved;
   const { management } = resolved;
   try {
@@ -649,16 +649,16 @@ async function groupWriteOp(
   spec: GroupWriteSpec,
 ): Promise<ExtendedRpcResult> {
   const adapter = strField(d, '$adapter', 'adapter');
-  const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+  const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
   const groupId = strField(d, '$group_id', 'groupId', 'group_id');
   const userId = strField(d, '$user_id', 'userId', 'user_id');
-  if (!adapter || !endpointId || !groupId) {
+  if (!adapter || !endpointKey || !groupId) {
     return { error: '$adapter, $endpoint, $group_id required' };
   }
   if (spec.requireUser && !userId) {
     return { error: '$user_id required' };
   }
-  const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
+  const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
   if ('error' in resolved) return resolved;
   const { management } = resolved;
   const method = management[spec.method];
@@ -686,12 +686,12 @@ async function deleteFriend(
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
   const adapter = strField(d, '$adapter', 'adapter');
-  const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
+  const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
   const userId = strField(d, '$user_id', 'userId', 'user_id');
-  if (!adapter || !endpointId || !userId) {
+  if (!adapter || !endpointKey || !userId) {
     return { error: '$adapter, $endpoint, $user_id required' };
   }
-  const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
+  const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
   if ('error' in resolved) return resolved;
   const { management } = resolved;
   const method = management.deleteFriend;
@@ -749,23 +749,23 @@ function numArrayField(d: Record<string, unknown>, ...keys: string[]): number[]
 type ResolveOk = {
   management: EndpointManagementPort;
   adapter: string;
-  endpointId: string;
+  endpointKey: string;
 };
 
 function resolveLiveEndpoint(
   ctx: ConsoleRpcExtendedCtx,
   adapter: string,
-  endpointId: string,
+  endpointKey: string,
 ): ResolveOk | { error: string } {
   if (ctx.resolveEndpointManagement) {
-    const management = ctx.resolveEndpointManagement(adapter, endpointId);
+    const management = ctx.resolveEndpointManagement(adapter, endpointKey);
     if (!management) return { error: 'endpoint not found' };
-    return { management, adapter, endpointId };
+    return { management, adapter, endpointKey };
   }
   if (!ctx.resolveEndpoint) {
     return { error: 'Endpoint registry is not configured' };
   }
-  const endpoint = ctx.resolveEndpoint(adapter, endpointId);
+  const endpoint = ctx.resolveEndpoint(adapter, endpointKey);
   if (!endpoint || typeof endpoint !== 'object') {
     return { error: 'endpoint not found' };
   }
@@ -775,7 +775,7 @@ function resolveLiveEndpoint(
       ? management as EndpointManagementPort
       : {},
     adapter,
-    endpointId,
+    endpointKey,
   };
 }
 
@@ -784,9 +784,9 @@ function requireEndpoint(
   ctx: ConsoleRpcExtendedCtx,
 ): ResolveOk | { error: string } {
   const adapter = strField(d, '$adapter', 'adapter');
-  const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
-  if (!adapter || !endpointId) return { error: '$adapter and $endpoint required' };
-  return resolveLiveEndpoint(ctx, adapter, endpointId);
+  const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
+  if (!adapter || !endpointKey) return { error: '$adapter and $endpoint required' };
+  return resolveLiveEndpoint(ctx, adapter, endpointKey);
 }
 
 function normalizeParent(raw: unknown): { type: 'group' | 'guild'; id: string; name?: string } | undefined {

package/src/console-rpc.ts

@@ -93,7 +93,7 @@ export type RuntimeConsoleRpcContext = {
   getAllSchemas?(): Promise<Record<string, unknown>>;
   /** Optional Adapter endpoint Console surface (Sandbox / Remote Console). */
   listEndpoints?(): Promise<readonly RuntimeEndpointSummary[]>;
-  getEndpoint?(adapter: string, endpointId: string): Promise<RuntimeEndpointSummary | null>;
+  getEndpoint?(adapter: string, endpointKey: string): Promise<RuntimeEndpointSummary | null>;
   sendEndpointMessage?(input: RuntimeEndpointSendInput): Promise<{ messageId: string }>;
   /** Optional Database host surface (CLI wires DatabaseHost from plugin-runtime). */
   dbInfo?(): Promise<RuntimeDatabaseInfo> | RuntimeDatabaseInfo;
@@ -123,7 +123,7 @@ export type RuntimeDatabaseInfo = {
 
 export type RuntimeEndpointSendInput = {
   readonly adapter: string;
-  readonly endpointId: string;
+  readonly endpointKey: string;
   readonly conversation: ConversationAddress;
   readonly content: unknown;
 };
@@ -630,8 +630,8 @@ export async function dispatchRuntimeConsoleRpc(
       try {
         const data = message as Record<string, unknown>;
         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;
         }
@@ -639,7 +639,7 @@ export async function dispatchRuntimeConsoleRpc(
           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;
@@ -657,12 +657,12 @@ export async function dispatchRuntimeConsoleRpc(
       try {
         const data = message as Record<string, unknown>;
         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',
@@ -675,7 +675,7 @@ export async function dispatchRuntimeConsoleRpc(
         }
         const result = await ctx.sendEndpointMessage({
           adapter,
-          endpointId,
+          endpointKey,
           conversation: wireConversation(channelType, channelId, data.$parent),
           content,
         });

package/src/http-host.ts

@@ -24,7 +24,7 @@ import {
 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]);
@@ -401,15 +401,17 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
           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);
         });
       });