@zhin.js/host-http 1.0.6 → 1.0.9

package/src/console-rpc-extended.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 负责。
  */
 
 /** 新 Runtime 统一收件箱表名（SSOT：@zhin.js/plugin-runtime inbox.js）。 */
@@ -31,13 +31,12 @@ export interface ConsoleRpcExtendedCtx {
   projectRoot: string;
   /** Plugin Runtime ScheduleHost（basic/cli schedule-host-installer 提供）。 */
   scheduleHost?: unknown;
-  /** 经 ImRuntime / AdapterEndpointIndex 解析管理语义端口。 */
-  resolveEndpointManagement?: (
+  /** 在固定 generation lease 内执行一次 Endpoint 管理操作。 */
+  withEndpointManagement?: <T>(
     adapter: string,
-    endpointId: string,
-  ) => EndpointManagementPort | null | undefined;
-  /** @deprecated Use `resolveEndpointManagement`; accepted for one compatibility cycle. */
-  resolveEndpoint?: (adapter: string, endpointId: string) => unknown;
+    endpointKey: string,
+    run: (management: EndpointManagementPort) => T | Promise<T>,
+  ) => Promise<T | null>;
   /** Plugin Runtime DatabaseHost 的 models 视图。 */
   databaseHost?: { models: { get(name: string): unknown } };
   /** Agent Host 持久化调度引擎（@zhin.js/agent getAssistantRuntime().engine），未 init 时返回 null。 */
@@ -340,13 +339,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 +365,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 +385,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 +398,7 @@ async function listInboxMessages(
 
   const where: Record<string, unknown> = {
     adapter,
-    endpoint_id: endpointId,
+    endpoint_id: endpointKey,
     channel_id: channelId,
     channel_type: channelType,
   };
@@ -525,31 +524,26 @@ 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);
-  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) };
-  }
+  });
 }
 
 // ---------------------------------------------------------------- 社交读取
@@ -558,54 +552,45 @@ async function listFriends(
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
-  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: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
-  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: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
-  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(
@@ -613,24 +598,19 @@ 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);
-  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) };
-  }
+  });
 }
 
 // ---------------------------------------------------------------- 群管/好友写操作
@@ -649,23 +629,20 @@ 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);
-  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, {
@@ -676,9 +653,7 @@ async function groupWriteOp(
     });
     await (method as (...args: unknown[]) => Promise<void>).call(management, ...args);
     return { data: { success: true } };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
+  });
 }
 
 async function deleteFriend(
@@ -686,24 +661,19 @@ 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);
-  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
@@ -746,47 +716,30 @@ function numArrayField(d: Record<string, unknown>, ...keys: string[]): number[]
   return [];
 }
 
-type ResolveOk = {
-  management: EndpointManagementPort;
-  adapter: string;
-  endpointId: string;
-};
-
-function resolveLiveEndpoint(
+async function withLiveEndpoint(
   ctx: ConsoleRpcExtendedCtx,
   adapter: string,
-  endpointId: string,
-): ResolveOk | { error: string } {
-  if (ctx.resolveEndpointManagement) {
-    const management = ctx.resolveEndpointManagement(adapter, endpointId);
-    if (!management) return { error: 'endpoint not found' };
-    return { management, adapter, endpointId };
-  }
-  if (!ctx.resolveEndpoint) {
+  endpointKey: string,
+  run: (management: EndpointManagementPort) => ExtendedRpcResult | Promise<ExtendedRpcResult>,
+): Promise<ExtendedRpcResult> {
+  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 as { management?: unknown }).management;
-  return {
-    management: management && typeof management === 'object'
-      ? management as EndpointManagementPort
-      : {},
-    adapter,
-    endpointId,
-  };
 }
 
-function requireEndpoint(
+function requireEndpointAddress(
   d: Record<string, unknown>,
-  ctx: ConsoleRpcExtendedCtx,
-): ResolveOk | { error: string } {
+): { adapter: string; endpointKey: string } | { 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 { 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,
         });