@zhin.js/host-http 1.0.6 → 1.0.9

package/README.md

@@ -7,6 +7,11 @@ Console can register path-scoped WebSocket / HTTP routes without importing Koa o
 Root installs the host via `installResources` (see `basic/cli/src/plugin-runtime/http-host-installer.ts`
 and `console-host-installer.ts`).
 
+The composition root owns the process listener through `ProcessHttpHost`. Generation scopes receive
+only the `HttpHost` routing port: they may register HTTP/WS routes but cannot listen or close the
+shared server. Registrations are bound to generation admission, so candidate routes stay invisible
+until snapshot commit and retired routes stop matching immediately while their leases drain.
+
 ## Capabilities (this slice)
 
 - Path-scoped WebSocket upgrades (`ws(path)`)

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

@@ -11,8 +11,8 @@
  * - inbox：`ctx.databaseHost.models`（unified_inbox_message/request/notice 三张表，
  *   表不存在或查询失败 → 空数组 + inboxEnabled:false；requestConsumed/noticeConsumed
  *   按行 id update consumed=1，表/model 缺失时报"未接线"）。
- * - 社交/群管：`ctx.resolveEndpoint` 拿 live endpoint 实例，只消费其
- *   `management` 语义端口；平台 SDK 兼容与字段归一化由 Adapter 负责。
+ * - 社交/群管：`ctx.withEndpointManagement` 在固定 generation lease 内
+ *   消费 `management` 语义端口；平台 SDK 字段归一化由 Adapter 负责。
  */
 export interface ConsoleRpcExtendedCtx {
     /** full scope 才允许写操作；demo scope 只放行只读 RPC。 */
@@ -20,10 +20,8 @@ export interface ConsoleRpcExtendedCtx {
     projectRoot: string;
     /** Plugin Runtime ScheduleHost（basic/cli schedule-host-installer 提供）。 */
     scheduleHost?: unknown;
-    /** 经 ImRuntime / AdapterEndpointIndex 解析管理语义端口。 */
-    resolveEndpointManagement?: (adapter: string, endpointId: string) => EndpointManagementPort | null | undefined;
-    /** @deprecated Use `resolveEndpointManagement`; accepted for one compatibility cycle. */
-    resolveEndpoint?: (adapter: string, endpointId: string) => unknown;
+    /** 在固定 generation lease 内执行一次 Endpoint 管理操作。 */
+    withEndpointManagement?: <T>(adapter: string, endpointKey: string, run: (management: EndpointManagementPort) => T | Promise<T>) => Promise<T | null>;
     /** Plugin Runtime DatabaseHost 的 models 视图。 */
     databaseHost?: {
         models: {

package/lib/console-rpc-extended.js

@@ -11,8 +11,8 @@
  * - inbox：`ctx.databaseHost.models`（unified_inbox_message/request/notice 三张表，
  *   表不存在或查询失败 → 空数组 + inboxEnabled:false；requestConsumed/noticeConsumed
  *   按行 id update consumed=1，表/model 缺失时报"未接线"）。
- * - 社交/群管：`ctx.resolveEndpoint` 拿 live endpoint 实例，只消费其
- *   `management` 语义端口；平台 SDK 兼容与字段归一化由 Adapter 负责。
+ * - 社交/群管：`ctx.withEndpointManagement` 在固定 generation lease 内
+ *   消费 `management` 语义端口；平台 SDK 字段归一化由 Adapter 负责。
  */
 /** 新 Runtime 统一收件箱表名（SSOT：@zhin.js/plugin-runtime inbox.js）。 */
 import { assertDemoConsoleRpcAllowed, normalizeConsoleRpcType, } from '@zhin.js/console-protocol';
@@ -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,126 +393,96 @@ 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);
-    if ('error' in resolved)
-        return resolved;
-    const management = resolved.management;
-    const approve = type === 'request.approve';
-    const method = approve ? management.approveRequest : management.rejectRequest;
-    if (!method) {
-        return {
-            error: `请求审批未接线：当前平台（${adapter}）endpoint 不支持 ${approve ? 'approveRequest' : 'rejectRequest'}，` +
-                '且新 Runtime 尚未挂载 pending request 注册表',
-        };
-    }
-    try {
+    return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+        const approve = type === 'request.approve';
+        const method = approve ? management.approveRequest : management.rejectRequest;
+        if (!method) {
+            return {
+                error: `请求审批未接线：当前平台（${adapter}）endpoint 不支持 ${approve ? 'approveRequest' : 'rejectRequest'}，` +
+                    '且新 Runtime 尚未挂载 pending request 注册表',
+            };
+        }
         const extra = approve
             ? strField(d, '$remark', 'remark')
             : strField(d, '$reason', 'reason');
         await method.call(management, requestId, extra || undefined);
         return { data: { success: true } };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+    });
 }
 // ---------------------------------------------------------------- 社交读取
 async function listFriends(d, ctx) {
-    const resolved = requireEndpoint(d, ctx);
-    if ('error' in resolved)
-        return resolved;
-    const { management, adapter } = resolved;
-    try {
+    const endpoint = requireEndpointAddress(d);
+    if ('error' in endpoint)
+        return endpoint;
+    return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
         if (management.listFriends) {
             const friends = [...await management.listFriends()];
             return { data: { friends, count: friends.length } };
         }
-        return { error: `当前适配器（${adapter}）不支持好友列表` };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+        return { error: `当前适配器（${endpoint.adapter}）不支持好友列表` };
+    });
 }
 async function listGroups(d, ctx) {
-    const resolved = requireEndpoint(d, ctx);
-    if ('error' in resolved)
-        return resolved;
-    const { management, adapter } = resolved;
-    try {
+    const endpoint = requireEndpointAddress(d);
+    if ('error' in endpoint)
+        return endpoint;
+    return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
         if (management.listGroups) {
             const groups = [...await management.listGroups()];
             return { data: { groups, count: groups.length } };
         }
-        return { error: `当前适配器（${adapter}）不支持群列表` };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+        return { error: `当前适配器（${endpoint.adapter}）不支持群列表` };
+    });
 }
 async function listChannels(d, ctx) {
-    const resolved = requireEndpoint(d, ctx);
-    if ('error' in resolved)
-        return resolved;
-    const { management, adapter } = resolved;
-    try {
+    const endpoint = requireEndpointAddress(d);
+    if ('error' in endpoint)
+        return endpoint;
+    return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
         if (management.listChannels) {
             const channels = [...await management.listChannels()];
             return { data: { channels, count: channels.length } };
         }
-        return { error: `当前适配器（${adapter}）不支持频道列表` };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+        return { error: `当前适配器（${endpoint.adapter}）不支持频道列表` };
+    });
 }
 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);
-    if ('error' in resolved)
-        return resolved;
-    const { management } = resolved;
-    try {
+    return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
         const method = management.listGroupMembers;
         if (!method) {
             return { error: `当前适配器（${adapter}）不支持群成员列表` };
         }
         const members = [...await method(groupId)];
         return { data: { members, count: members.length } };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+    });
 }
 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);
-    if ('error' in resolved)
-        return resolved;
-    const { management } = resolved;
-    const method = management[spec.method];
-    if (!method) {
-        return { error: `当前适配器（${adapter}）不支持${spec.unsupported}` };
-    }
-    try {
+    return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+        const method = management[spec.method];
+        if (!method) {
+            return { error: `当前适配器（${adapter}）不支持${spec.unsupported}` };
+        }
         const durationRaw = d.$duration ?? d.duration;
         const enableRaw = d.$enable ?? d.enable;
         const args = spec.buildArgs(groupId, userId, {
@@ -523,33 +493,23 @@ async function groupWriteOp(d, ctx, spec) {
         });
         await method.call(management, ...args);
         return { data: { success: true } };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+    });
 }
 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);
-    if ('error' in resolved)
-        return resolved;
-    const { management } = resolved;
-    const method = management.deleteFriend;
-    if (!method) {
-        return { error: '当前适配器暂不支持删除好友' };
-    }
-    try {
+    return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+        const method = management.deleteFriend;
+        if (!method) {
+            return { error: '当前适配器暂不支持删除好友' };
+        }
         await method(userId);
         return { data: { success: true } };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+    });
 }
 // ---------------------------------------------------------------- helpers
 function strField(d, ...keys) {
@@ -592,35 +552,24 @@ function numArrayField(d, ...keys) {
     }
     return [];
 }
-function resolveLiveEndpoint(ctx, adapter, endpointId) {
-    if (ctx.resolveEndpointManagement) {
-        const management = ctx.resolveEndpointManagement(adapter, endpointId);
-        if (!management)
-            return { error: 'endpoint not found' };
-        return { management, adapter, endpointId };
-    }
-    if (!ctx.resolveEndpoint) {
+async function withLiveEndpoint(ctx, adapter, endpointKey, run) {
+    if (!ctx.withEndpointManagement) {
         return { error: 'Endpoint registry is not configured' };
     }
-    const endpoint = ctx.resolveEndpoint(adapter, endpointId);
-    if (!endpoint || typeof endpoint !== 'object') {
-        return { error: 'endpoint not found' };
+    try {
+        return await ctx.withEndpointManagement(adapter, endpointKey, run)
+            ?? { error: 'endpoint not found' };
+    }
+    catch (error) {
+        return { error: errorMessage(error) };
     }
-    const management = endpoint.management;
-    return {
-        management: management && typeof management === 'object'
-            ? management
-            : {},
-        adapter,
-        endpointId,
-    };
 }
-function requireEndpoint(d, ctx) {
+function requireEndpointAddress(d) {
     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 { 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;
 };