@zhin.js/host-http 1.0.1 → 1.0.3

package/src/console-rpc.ts

@@ -1,5 +1,11 @@
 import type { AuthScope } from './token-registry.js';
 import type { DatabaseHostConsole } from '@zhin.js/plugin-runtime';
+import {
+  type ConsoleEndpointSummary,
+  assertDemoConsoleRpcAllowed,
+  endpointSendResult,
+  normalizeConsoleRpcMessage,
+} from '@zhin.js/console-protocol';
 import { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx } from './console-rpc-extended.js';
 
 export type RuntimeConsoleRpcMessage = {
@@ -57,21 +63,19 @@ export type RuntimeConsoleRpcContext = {
   database?: DatabaseHostConsole;
   /** Full-scope: request process restart (CLI daemon watches exit code). */
   requestRestart?(): Promise<void> | void;
+  /**
+   * Optional console event sink (`/api/events` SSE fan-out). Called after
+   * successful mutations: `config:updated` / `system:restarting`.
+   */
+  publishEvent?(type: string, data: unknown): void;
   /** Extended RPC surface（cron/schedule、endpoint 社交/inbox），fullScope 由 authScope 推导。 */
   extended?: Omit<ConsoleRpcExtendedCtx, 'fullScope'>;
 };
 
-export type RuntimeEndpointPhase =
-  'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+export type RuntimeEndpointPhase = NonNullable<ConsoleEndpointSummary['phase']>;
 
-export type RuntimeEndpointSummary = {
-  readonly name: string;
-  readonly adapter: string;
-  readonly connected: boolean;
-  readonly status: 'online' | 'offline';
-  readonly phase?: RuntimeEndpointPhase;
-  readonly pendingLogin?: boolean;
-};
+/** @deprecated Prefer `ConsoleEndpointSummary` from `@zhin.js/console-protocol`. */
+export type RuntimeEndpointSummary = ConsoleEndpointSummary;
 
 export type RuntimeDatabaseInfo = {
   readonly dialect: string | null;
@@ -88,47 +92,6 @@ export type RuntimeEndpointSendInput = {
   readonly parent?: { type?: string; id?: string; name?: string };
 };
 
-/**
- * Frontend SDK (@zhin.js/client) calls colon-named aliases; normalize to the
- * canonical dot names before scope checks and dispatch. Alias parameter shapes
- * (`data.{adapter, endpointId, id, type, content, parent}`) are mapped onto the
- * `$`-prefixed fields inside each endpoint case.
- */
-const RPC_TYPE_ALIASES: Readonly<Record<string, string>> = Object.freeze({
-  'endpoint:list': 'endpoint.list',
-  'endpoint:info': 'endpoint.info',
-  'endpoint:sendMessage': 'endpoint.send_message',
-});
-
-/** ADR 0016 demo allowlist subset available on Plugin Runtime Host. */
-const DEMO_RPC_ALLOWLIST = new Set([
-  'ping',
-  'entries:get',
-  'pages:list',
-  'config:get',
-  'config:get-all',
-  'config:get-yaml',
-  'schema:get',
-  'schema:get-all',
-  'endpoint.list',
-  'endpoint.info',
-  'endpoint.send_message',
-]);
-
-const DEMO_RPC_WRITE_BLOCKLIST = new Set([
-  'config:set',
-  'config:save-yaml',
-  'files:save',
-  'env:save',
-  'db:insert',
-  'db:update',
-  'db:delete',
-  'db:drop-table',
-  'db:kv:set',
-  'db:kv:delete',
-  'system:restart',
-]);
-
 export function pickRpcReply(
   message: RuntimeConsoleRpcMessage,
   payloads: readonly RuntimeConsoleRpcReply[],
@@ -149,14 +112,23 @@ export async function dispatchRuntimeConsoleRpc(
   const emit = (payload: RuntimeConsoleRpcReply) => {
     payloads.push(payload);
   };
-  const type = RPC_TYPE_ALIASES[String(message.type ?? '')] ?? String(message.type ?? '');
+  message = normalizeConsoleRpcMessage(message);
+  const type = String(message.type ?? '');
   const requestId = message.requestId as number | string | undefined;
 
-  // Extended RPC surface (cron/schedule、endpoint 社交/inbox) — 自带 scope 矩阵
+  if (ctx.authScope === 'demo') {
+    const denied = assertDemoConsoleRpcAllowed(type);
+    if (denied) {
+      emit({ requestId, error: denied });
+      return payloads;
+    }
+  }
+
+  // Extended RPC surface (cron/schedule、endpoint 社交/inbox)
   if (ctx.extended) {
     const extended = await dispatchExtendedConsoleRpc(
       type,
-      message.data as Record<string, unknown> | undefined,
+      message as Record<string, unknown>,
       { ...ctx.extended, fullScope: ctx.authScope === 'full' },
     );
     if (extended !== undefined) {
@@ -167,11 +139,6 @@ export async function dispatchRuntimeConsoleRpc(
     }
   }
 
-  if (ctx.authScope === 'demo' && (DEMO_RPC_WRITE_BLOCKLIST.has(type) || !DEMO_RPC_ALLOWLIST.has(type))) {
-    emit({ requestId, error: `Demo scope: RPC "${type}" is forbidden` });
-    return payloads;
-  }
-
   switch (type) {
     case 'ping':
       emit({ type: 'pong', requestId });
@@ -224,7 +191,9 @@ export async function dispatchRuntimeConsoleRpc(
     }
     case 'config:get': {
       try {
-        const key = String(message.key ?? message.pluginName ?? '');
+        // 兼容 console UI 的 data:{plugin} / data:{key} 形状
+        const data = (message.data ?? {}) as Record<string, unknown>;
+        const key = String(message.key ?? message.pluginName ?? data.pluginName ?? data.plugin ?? data.key ?? '');
         const document = ctx.readConfigDocument ? await ctx.readConfigDocument() : {};
         emit({ requestId, data: key ? document[key] : document });
       } catch (error) {
@@ -247,6 +216,7 @@ export async function dispatchRuntimeConsoleRpc(
           return payloads;
         }
         await ctx.writeConfigYaml(yaml);
+        ctx.publishEvent?.('config:updated', { pluginName: null, keys: [] });
         emit({
           requestId,
           data: { success: true, message: '配置已保存，需重启生效' },
@@ -271,6 +241,12 @@ export async function dispatchRuntimeConsoleRpc(
           return payloads;
         }
         const result = await ctx.setConfigKey(pluginName, message.data);
+        ctx.publishEvent?.('config:updated', {
+          pluginName,
+          keys: message.data && typeof message.data === 'object' && !Array.isArray(message.data)
+            ? Object.keys(message.data as Record<string, unknown>)
+            : [],
+        });
         emit({
           requestId,
           data: {
@@ -409,7 +385,10 @@ export async function dispatchRuntimeConsoleRpc(
     }
     case 'schema:get': {
       try {
-        const pluginName = typeof message.pluginName === 'string' ? message.pluginName : undefined;
+        // 兼容 console UI 的 data:{plugin} / data:{pluginName} 形状（SDK 发顶层 pluginName）
+        const data = (message.data ?? {}) as Record<string, unknown>;
+        const candidate = message.pluginName ?? data.pluginName ?? data.plugin;
+        const pluginName = typeof candidate === 'string' ? candidate : undefined;
         const schema = ctx.getSchema ? await ctx.getSchema(pluginName) : null;
         emit({ requestId, data: schema });
       } catch (error) {
@@ -613,10 +592,9 @@ export async function dispatchRuntimeConsoleRpc(
     }
     case 'endpoint.info': {
       try {
-        const data = (message.data ?? {}) as Record<string, unknown>;
-        // Accept both canonical `$`-fields and the SDK colon-alias shape.
-        const adapter = String(data.$adapter ?? data.adapter ?? '');
-        const endpointId = String(data.$endpoint ?? data.endpointId ?? '');
+        const data = message as Record<string, unknown>;
+        const adapter = String(data.$adapter ?? '');
+        const endpointId = String(data.$endpoint ?? '');
         if (!adapter || !endpointId) {
           emit({ requestId, error: '$adapter and $endpoint required' });
           return payloads;
@@ -641,14 +619,12 @@ export async function dispatchRuntimeConsoleRpc(
     }
     case 'endpoint.send_message': {
       try {
-        const data = (message.data ?? {}) as Record<string, unknown>;
-        // Accept both canonical `$`-fields and the SDK colon-alias shape
-        // (`endpoint:sendMessage` → data.{adapter, endpointId, id, type, content, parent}).
-        const adapter = String(data.$adapter ?? data.adapter ?? '');
-        const endpointId = String(data.$endpoint ?? data.endpointId ?? '');
-        const channelId = String(data.$channel_id ?? data.id ?? '');
-        const channelType = String(data.$channel_type ?? data.type ?? '');
-        const content = data.$content !== undefined ? data.$content : data.content;
+        const data = message as Record<string, unknown>;
+        const adapter = String(data.$adapter ?? '');
+        const endpointId = String(data.$endpoint ?? '');
+        const channelId = String(data.$channel_id ?? '');
+        const channelType = String(data.$channel_type ?? '');
+        const content = data.$content;
         // channelType is optional: ImRuntime tolerates an empty value and
         // targets the bare channel id (parity with the legacy RPC handler).
         if (!adapter || !endpointId || !channelId || content === undefined) {
@@ -668,11 +644,11 @@ export async function dispatchRuntimeConsoleRpc(
           channelId,
           channelType,
           content,
-          parent: (data.$parent ?? data.parent) as
+          parent: data.$parent as
             { type?: string; id?: string; name?: string } | undefined,
         });
         // Legacy contract: { message_id }. Keep messageId for new callers.
-        emit({ requestId, data: { message_id: result.messageId, messageId: result.messageId } });
+        emit({ requestId, data: endpointSendResult(result.messageId) });
       } catch (error) {
         emit({
           requestId,
@@ -687,6 +663,7 @@ export async function dispatchRuntimeConsoleRpc(
           emit({ requestId, error: 'Process restart is not configured' });
           return payloads;
         }
+        ctx.publishEvent?.('system:restarting', { timestamp: Date.now() });
         emit({ requestId, data: { success: true, message: '正在重启...' } });
         // Delay so the HTTP response can flush (parity with legacy host-api).
         setTimeout(() => {

package/src/http-host.ts

@@ -22,6 +22,7 @@ import {
   type RouteMeta,
 } from './openapi.js';
 import { isDemoHttpAllowed } from './console-rpc.js';
+import { HttpBodyError } from './json-body.js';
 
 const logger = getLogger('HttpHost');
 
@@ -276,6 +277,14 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
       response.setHeader('X-Frame-Options', 'SAMEORIGIN');
       await route.handler(request, response, url, auth.scope);
     } catch (err) {
+      // 统一把请求体错误（400/413）映射回对应状态码，
+      // 避免个别端点未捕获时退化成 500 空响应。
+      if (err instanceof HttpBodyError) {
+        if (!response.headersSent) {
+          writeJson(response, err.statusCode, { success: false, error: err.message });
+        }
+        return;
+      }
       logger.warn(formatCompact({
         op: 'http_handler_failed',
         path: pathname,

package/src/index.ts

@@ -19,6 +19,10 @@ export {
   type TokenRegistryConfig,
 } from './token-registry.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
+export {
+  createConsoleEventHub,
+  type ConsoleEventHub,
+} from './console-events.js';
 export {
   buildOpenApiDocument,
   patternToOpenApiPath,
@@ -61,3 +65,9 @@ export {
   type ConsoleRestCtx,
   type ConsoleRestPagesOptions,
 } from './console-rest-pages.js';
+export {
+  dispatchExtendedConsoleRpc,
+  type ConsoleRpcExtendedCtx,
+  type ConsoleScheduleEngine,
+  type ExtendedRpcResult,
+} from './console-rpc-extended.js';

package/src/json-body.ts

@@ -21,15 +21,21 @@ export async function readJsonBody<T = unknown>(
   const limit = options.limit ?? 1_048_576;
   const chunks: Buffer[] = [];
   let size = 0;
+  let exceeded = false;
   for await (const chunk of request) {
+    // 超限后继续 drain 到 end：提前 break 会 destroy 底层 socket，
+    // 客户端将永远收不到后面的 413 响应。
+    if (exceeded) continue;
     const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
     size += buffer.length;
     if (size > limit) {
-      request.destroy();
-      throw new HttpBodyError(`Request body exceeds ${limit} bytes`, 413);
+      exceeded = true;
+      chunks.length = 0;
+      continue;
     }
     chunks.push(buffer);
   }
+  if (exceeded) throw new HttpBodyError(`Request body exceeds ${limit} bytes`, 413);
   if (chunks.length === 0) return undefined;
   const raw = Buffer.concat(chunks).toString('utf8').trim();
   if (!raw) return undefined;

package/src/project-files.ts

@@ -6,6 +6,16 @@ export const FILE_MANAGER_ALLOWED = Object.freeze([
   'src',
   'plugins',
   'client',
+  // Plugin Runtime convention directories (file-based discovery)
+  'commands',
+  'adapters',
+  'components',
+  'middlewares',
+  'tools',
+  'mcp',
+  'pages',
+  'skills',
+  'agents',
   'package.json',
   'tsconfig.json',
   'zhin.config.yml',