@zhin.js/host-http 1.0.11 → 1.0.12

package/lib/console-events.d.ts

@@ -1,13 +1,27 @@
 import type { ServerResponse } from 'node:http';
+import type { ConsoleEventEnvelope, ConsoleEventHistoryPage, ConsoleEventHistoryQuery, ConsoleEventPayloadMap, KnownConsoleEventType } from '@zhin.js/console-protocol';
 /**
  * Console 实时事件枢纽（Plugin Runtime Host 的 `/api/events` SSE 事件源）。
  * 单进程内 fan-out：`publish` 向所有已订阅的 SSE response 写帧；
  * write 失败或连接断开自动摘除订阅。
  */
+export interface ConsoleEventSubscriptionOptions {
+    readonly runtimeId?: string;
+    readonly after?: number;
+}
 export interface ConsoleEventHub {
-    publish(type: string, data: unknown): void;
-    /** 订阅事件流；返回 unsubscribe。连接断开时也会自动摘除。 */
-    subscribe(response: ServerResponse): () => void;
+    publish<Type extends string>(type: Type, data: Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown): ConsoleEventEnvelope<Type, Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown>;
+    history(query?: ConsoleEventHistoryQuery): ConsoleEventHistoryPage;
+    /** Atomically replay the resumable suffix, then join live fan-out. */
+    subscribe(response: ServerResponse, options?: ConsoleEventSubscriptionOptions): () => void;
+    readonly runtimeId: string;
     readonly subscriberCount: number;
 }
-export declare function createConsoleEventHub(): ConsoleEventHub;
+export interface ConsoleEventHubOptions {
+    readonly runtimeId?: string;
+    readonly historyLimit?: number;
+    readonly historyByteLimit?: number;
+    readonly historyPageByteLimit?: number;
+}
+export declare function createConsoleEventHub(options?: ConsoleEventHubOptions): ConsoleEventHub;
+export declare function serializeConsoleEvent(event: ConsoleEventEnvelope): string;

package/lib/console-events.js

@@ -1,33 +1,145 @@
-export function createConsoleEventHub() {
+import { randomUUID } from 'node:crypto';
+const DEFAULT_HISTORY_LIMIT = 256;
+const DEFAULT_PAGE_LIMIT = 200;
+const MAX_PAGE_LIMIT = 500;
+const MAX_EVENT_BYTES = 64 * 1024;
+const DEFAULT_HISTORY_BYTE_LIMIT = 8 * 1024 * 1024;
+const DEFAULT_HISTORY_PAGE_BYTE_LIMIT = 1024 * 1024;
+export function createConsoleEventHub(options = {}) {
     let nextId = 0;
+    const runtimeId = options.runtimeId ?? randomUUID();
+    const historyLimit = positiveInteger(options.historyLimit, DEFAULT_HISTORY_LIMIT);
+    const historyByteLimit = positiveInteger(options.historyByteLimit, DEFAULT_HISTORY_BYTE_LIMIT);
+    const historyPageByteLimit = positiveInteger(options.historyPageByteLimit, DEFAULT_HISTORY_PAGE_BYTE_LIMIT);
+    const journal = [];
+    let journalBytes = 0;
     const subscribers = new Set();
     const remove = (response) => {
         subscribers.delete(response);
     };
+    const write = (response, entry) => {
+        let failed = false;
+        const accepted = response.write(entry.frame, (error) => {
+            if (error) {
+                failed = true;
+                remove(response);
+            }
+        });
+        if (failed)
+            throw new Error('Console event subscriber rejected replay');
+        if (!accepted) {
+            remove(response);
+            response.destroy(new Error('Console event subscriber backpressure limit reached'));
+            throw new Error('Console event subscriber backpressure limit reached');
+        }
+    };
     return {
+        runtimeId,
         get subscriberCount() {
             return subscribers.size;
         },
         publish(type, data) {
-            nextId += 1;
-            const frame = `id: ${nextId}\nevent: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+            const snapshot = jsonSnapshot(data);
+            const event = Object.freeze({
+                runtimeId,
+                eventId: ++nextId,
+                type,
+                data: snapshot,
+                timestamp: Date.now(),
+            });
+            const frame = serializeConsoleEvent(event);
+            const entry = Object.freeze({ event, frame, bytes: Buffer.byteLength(frame, 'utf8') });
+            journal.push(entry);
+            journalBytes += entry.bytes;
+            while (journal.length > historyLimit || journalBytes > historyByteLimit) {
+                journalBytes -= journal.shift()?.bytes ?? 0;
+            }
             for (const response of [...subscribers]) {
                 try {
-                    response.write(frame, (error) => {
-                        if (error)
-                            remove(response);
-                    });
+                    write(response, entry);
                 }
                 catch {
                     remove(response);
                 }
             }
+            return event;
         },
-        subscribe(response) {
-            subscribers.add(response);
+        history(query = {}) {
+            const requestedAfter = nonNegativeInteger(query.after, 0);
+            const sameRuntime = !query.runtimeId || query.runtimeId === runtimeId;
+            const cursorAhead = requestedAfter > nextId;
+            const after = sameRuntime && !cursorAhead ? requestedAfter : 0;
+            const limit = Math.min(MAX_PAGE_LIMIT, positiveInteger(query.limit, DEFAULT_PAGE_LIMIT));
+            const oldestAvailableEventId = journal[0]?.event.eventId ?? null;
+            const latestEventId = nextId;
+            const gap = !sameRuntime || cursorAhead
+                || (oldestAvailableEventId !== null
+                    ? after < oldestAvailableEventId - 1
+                    : after < latestEventId);
+            const available = journal.filter((entry) => entry.event.eventId > after);
+            const selected = [];
+            let selectedBytes = 0;
+            for (const entry of available) {
+                if (selected.length >= limit)
+                    break;
+                if (selected.length > 0 && selectedBytes + entry.bytes > historyPageByteLimit)
+                    break;
+                selected.push(entry.event);
+                selectedBytes += entry.bytes;
+            }
+            const items = Object.freeze(selected);
+            const nextAfter = items.at(-1)?.eventId ?? after;
+            return Object.freeze({
+                runtimeId,
+                items,
+                oldestAvailableEventId,
+                latestEventId,
+                nextAfter,
+                hasMore: available.length > items.length,
+                gap,
+            });
+        },
+        subscribe(response, options = {}) {
+            // Replay and subscription are synchronous relative to publish(), closing
+            // the race between HTTP recovery and the live stream hand-off.
+            const requestedAfter = nonNegativeInteger(options.after, 0);
+            const after = options.runtimeId && options.runtimeId !== runtimeId
+                || requestedAfter > nextId
+                ? 0
+                : requestedAfter;
+            try {
+                for (const entry of journal) {
+                    if (entry.event.eventId > after)
+                        write(response, entry);
+                }
+                subscribers.add(response);
+            }
+            catch {
+                remove(response);
+            }
             response.once('close', () => remove(response));
             response.once('error', () => remove(response));
             return () => remove(response);
         },
     };
 }
+export function serializeConsoleEvent(event) {
+    return `id: ${event.eventId}\nevent: ${event.type}\nruntime: ${event.runtimeId}\ntimestamp: ${event.timestamp}\ndata: ${JSON.stringify(event.data)}\n\n`;
+}
+function positiveInteger(value, fallback) {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function nonNegativeInteger(value, fallback) {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function jsonSnapshot(value) {
+    const encoded = JSON.stringify(value ?? null);
+    if (encoded === undefined)
+        throw new TypeError('Console event data must be JSON serializable');
+    if (Buffer.byteLength(encoded, 'utf8') > MAX_EVENT_BYTES) {
+        throw new RangeError(`Console event data exceeds ${MAX_EVENT_BYTES} bytes`);
+    }
+    return JSON.parse(encoded);
+}

package/lib/console-rpc-extended.js

@@ -21,6 +21,7 @@ import { assertDemoConsoleRpcAllowed, normalizeConsoleRpcType, } from '@zhin.js/
 const TABLE_MESSAGE = 'unified_inbox_message';
 const TABLE_REQUEST = 'unified_inbox_request';
 const TABLE_NOTICE = 'unified_inbox_notice';
+const MAX_INBOX_OFFSET = 10_000;
 const CRON_NOT_WIRED = '持久化调度未接线：当前 Plugin Runtime ScheduleHost 仅支持插件注册的内存任务（list），' +
     '不支持 add/remove/pause/resume（需要 @zhin.js/agent 持久化调度引擎）';
 const CONSUMED_NOT_WIRED = '收件箱已读标记未接线：unified_inbox_request/notice 表未注册或 DatabaseHost 未启动';
@@ -330,21 +331,30 @@ function getInboxModel(ctx, table) {
 async function readInboxRows(ctx, table, where, options) {
     const model = getInboxModel(ctx, table);
     if (!model)
-        return { rows: [], enabled: false };
+        return { rows: [], enabled: false, offsetApplied: false };
     try {
         let selection = model.select().where(where);
+        let orderApplied = options?.orderBy == null;
         if (options?.orderBy && typeof selection.orderBy === 'function') {
             selection = selection.orderBy(options.orderBy.field, options.orderBy.direction ?? 'DESC');
+            orderApplied = true;
         }
-        if (options?.limit != null && typeof selection.limit === 'function') {
-            selection = selection.limit(options.limit);
+        const offset = options?.offset ?? 0;
+        const offsetSelection = orderApplied ? selection.offset : undefined;
+        const canApplyOffset = typeof offsetSelection === 'function';
+        const offsetApplied = offset === 0 || canApplyOffset;
+        if (offset > 0 && canApplyOffset) {
+            selection = offsetSelection.call(selection, offset);
+        }
+        if (options?.limit != null && orderApplied && typeof selection.limit === 'function') {
+            selection = selection.limit(options.limit + (offsetApplied ? 0 : offset));
         }
         const rows = await selection;
-        return { rows: Array.isArray(rows) ? rows : [], enabled: true };
+        return { rows: Array.isArray(rows) ? rows : [], enabled: true, offsetApplied };
     }
     catch {
         // 表未创建 / 方言未启动等场景降级为空，不向上抛。
-        return { rows: [], enabled: false };
+        return { rows: [], enabled: false, offsetApplied: false };
     }
 }
 async function listInbox(d, ctx, table, key, mapRow) {
@@ -352,20 +362,24 @@ async function listInbox(d, ctx, table, key, mapRow) {
     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, {
+    const limit = boundedIntegerField(d, 30, 1, 100, '$limit', 'limit');
+    const offset = boundedIntegerField(d, 0, 0, MAX_INBOX_OFFSET, '$offset', 'offset');
+    const unreadOnly = table === TABLE_NOTICE
+        && boolField(d, false, '$unread_only', 'unreadOnly', 'unread_only');
+    const { rows, enabled, offsetApplied } = await readInboxRows(ctx, table, {
         adapter,
         endpoint_id: endpointKey,
+        ...(unreadOnly ? { consumed: 0 } : {}),
     }, {
         // sort/limit 下推到 DB 侧（内存 sort/slice 保留，作为无下推能力模型的兜底）
         orderBy: { field: 'created_at', direction: 'DESC' },
-        limit: offset + limit,
+        limit,
+        offset,
     });
     const sorted = rows
         .slice()
         .sort((a, b) => Number(b.created_at ?? 0) - Number(a.created_at ?? 0))
-        .slice(offset, offset + limit)
+        .slice(offsetApplied ? 0 : offset, (offsetApplied ? 0 : offset) + limit)
         .map(mapRow);
     return { data: { [key]: sorted, inboxEnabled: enabled } };
 }
@@ -422,7 +436,7 @@ async function listInboxMessages(d, ctx) {
     if (!adapter || !endpointKey || !channelId || !channelType) {
         return { error: '$adapter, $endpoint, $channel_id, $channel_type required' };
     }
-    const limit = Math.min(numField(d, 50, '$limit', 'limit'), 100);
+    const limit = boundedIntegerField(d, 50, 1, 100, '$limit', 'limit');
     const beforeTs = optionalNum(d, '$before_ts', 'beforeTs', 'before_ts');
     const beforeId = optionalNum(d, '$before_id', 'beforeId', 'before_id');
     const parent = normalizeParent(d.$parent ?? d.parent);
@@ -489,16 +503,18 @@ function mapRequestRow(row) {
 function mapNoticeRow(row) {
     const actorId = row.actor_id ?? undefined;
     const actorName = row.actor_name ?? undefined;
-    const sceneId = row.scene_id;
-    const sceneType = row.scene_type ?? undefined;
+    const sceneId = String(row.scene_id ?? '');
+    const sceneType = row.scene_type == null ? undefined : String(row.scene_type);
     return {
         id: row.id,
         platform_notice_id: row.platform_notice_id,
         type: row.type,
+        noticeType: row.type,
         scene_type: sceneType,
         scene_id: sceneId,
         channel_id: sceneId,
         channel_type: sceneType,
+        channel: { id: sceneId, type: sceneType ?? '' },
         sub_type: row.sub_type ?? undefined,
         actor_id: actorId,
         actor_name: actorName,
@@ -510,6 +526,8 @@ function mapNoticeRow(row) {
         payload: row.payload,
         created_at: row.created_at,
         timestamp: row.created_at,
+        consumed: row.consumed,
+        consumed_at: row.consumed_at ?? undefined,
     };
 }
 // ---------------------------------------------------------------- consumed 标记
@@ -725,6 +743,20 @@ function numField(d, fallback, ...keys) {
     }
     return fallback;
 }
+function boundedIntegerField(d, fallback, minimum, maximum, ...keys) {
+    const value = numField(d, fallback, ...keys);
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(maximum, Math.max(minimum, Math.trunc(value)));
+}
+function boolField(d, fallback, ...keys) {
+    for (const key of keys) {
+        const value = d[key];
+        if (typeof value === 'boolean')
+            return value;
+    }
+    return fallback;
+}
 function optionalNum(d, ...keys) {
     for (const key of keys) {
         if (d[key] == null)

package/lib/console-rpc.js

@@ -699,6 +699,10 @@ export function isDemoHttpAllowed(method, pathname, apiBase) {
     const m = method.toUpperCase();
     if (m === 'GET' && pathname === `${normalizedBase}/events`)
         return true;
+    if (m === 'GET' && pathname === `${normalizedBase}/events/history`)
+        return true;
+    if (m === 'GET' && DEMO_INTROSPECTION_PATHS.has(pathname.slice(normalizedBase.length)))
+        return true;
     if (m === 'POST' && pathname === `${normalizedBase}/console/request`)
         return true;
     // Read-only dashboard / plugin inspection routes (legacy host-api parity).
@@ -711,3 +715,12 @@ export function isDemoHttpAllowed(method, pathname, apiBase) {
         return true;
     return false;
 }
+const DEMO_INTROSPECTION_PATHS = new Set([
+    '/introspection/commands',
+    '/introspection/middlewares',
+    '/introspection/components',
+    '/introspection/endpoints',
+    '/introspection/bindings',
+    '/introspection/tools',
+    '/introspection/mcp',
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.1.3",
+    "@zhin.js/console-protocol": "1.1.4",
     "@zhin.js/host-http-contract": "1.0.1",
     "@zhin.js/logger": "1.0.76",
     "@zhin.js/plugin-runtime": "1.1.7"

package/src/console-events.ts

@@ -1,47 +1,205 @@
+import { randomUUID } from 'node:crypto';
 import type { ServerResponse } from 'node:http';
+import type {
+  ConsoleEventEnvelope,
+  ConsoleEventHistoryPage,
+  ConsoleEventHistoryQuery,
+  ConsoleEventPayloadMap,
+  KnownConsoleEventType,
+} from '@zhin.js/console-protocol';
 
 /**
  * Console 实时事件枢纽（Plugin Runtime Host 的 `/api/events` SSE 事件源）。
  * 单进程内 fan-out：`publish` 向所有已订阅的 SSE response 写帧；
  * write 失败或连接断开自动摘除订阅。
  */
+export interface ConsoleEventSubscriptionOptions {
+  readonly runtimeId?: string;
+  readonly after?: number;
+}
+
 export interface ConsoleEventHub {
-  publish(type: string, data: unknown): void;
-  /** 订阅事件流；返回 unsubscribe。连接断开时也会自动摘除。 */
-  subscribe(response: ServerResponse): () => void;
+  publish<Type extends string>(
+    type: Type,
+    data: Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown,
+  ): ConsoleEventEnvelope<
+    Type,
+    Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown
+  >;
+  history(query?: ConsoleEventHistoryQuery): ConsoleEventHistoryPage;
+  /** Atomically replay the resumable suffix, then join live fan-out. */
+  subscribe(response: ServerResponse, options?: ConsoleEventSubscriptionOptions): () => void;
+  readonly runtimeId: string;
   readonly subscriberCount: number;
 }
 
-export function createConsoleEventHub(): ConsoleEventHub {
+export interface ConsoleEventHubOptions {
+  readonly runtimeId?: string;
+  readonly historyLimit?: number;
+  readonly historyByteLimit?: number;
+  readonly historyPageByteLimit?: number;
+}
+
+const DEFAULT_HISTORY_LIMIT = 256;
+const DEFAULT_PAGE_LIMIT = 200;
+const MAX_PAGE_LIMIT = 500;
+const MAX_EVENT_BYTES = 64 * 1024;
+const DEFAULT_HISTORY_BYTE_LIMIT = 8 * 1024 * 1024;
+const DEFAULT_HISTORY_PAGE_BYTE_LIMIT = 1024 * 1024;
+
+interface JournalEntry {
+  readonly event: ConsoleEventEnvelope;
+  readonly frame: string;
+  readonly bytes: number;
+}
+
+export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): ConsoleEventHub {
   let nextId = 0;
+  const runtimeId = options.runtimeId ?? randomUUID();
+  const historyLimit = positiveInteger(options.historyLimit, DEFAULT_HISTORY_LIMIT);
+  const historyByteLimit = positiveInteger(options.historyByteLimit, DEFAULT_HISTORY_BYTE_LIMIT);
+  const historyPageByteLimit = positiveInteger(
+    options.historyPageByteLimit,
+    DEFAULT_HISTORY_PAGE_BYTE_LIMIT,
+  );
+  const journal: JournalEntry[] = [];
+  let journalBytes = 0;
   const subscribers = new Set<ServerResponse>();
 
   const remove = (response: ServerResponse): void => {
     subscribers.delete(response);
   };
 
+  const write = (response: ServerResponse, entry: JournalEntry): void => {
+    let failed = false;
+    const accepted = response.write(entry.frame, (error) => {
+      if (error) {
+        failed = true;
+        remove(response);
+      }
+    });
+    if (failed) throw new Error('Console event subscriber rejected replay');
+    if (!accepted) {
+      remove(response);
+      response.destroy(new Error('Console event subscriber backpressure limit reached'));
+      throw new Error('Console event subscriber backpressure limit reached');
+    }
+  };
+
   return {
+    runtimeId,
     get subscriberCount() {
       return subscribers.size;
     },
-    publish(type, data) {
-      nextId += 1;
-      const frame = `id: ${nextId}\nevent: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+    publish<Type extends string>(
+      type: Type,
+      data: Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown,
+    ): ConsoleEventEnvelope<
+      Type,
+      Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown
+    > {
+      const snapshot = jsonSnapshot(data);
+      const event = Object.freeze({
+        runtimeId,
+        eventId: ++nextId,
+        type,
+        data: snapshot,
+        timestamp: Date.now(),
+      });
+      const frame = serializeConsoleEvent(event);
+      const entry = Object.freeze({ event, frame, bytes: Buffer.byteLength(frame, 'utf8') });
+      journal.push(entry);
+      journalBytes += entry.bytes;
+      while (journal.length > historyLimit || journalBytes > historyByteLimit) {
+        journalBytes -= journal.shift()?.bytes ?? 0;
+      }
       for (const response of [...subscribers]) {
         try {
-          response.write(frame, (error) => {
-            if (error) remove(response);
-          });
+          write(response, entry);
         } catch {
           remove(response);
         }
       }
+      return event as ConsoleEventEnvelope<
+        Type,
+        Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown
+      >;
     },
-    subscribe(response) {
-      subscribers.add(response);
+    history(query = {}): ConsoleEventHistoryPage {
+      const requestedAfter = nonNegativeInteger(query.after, 0);
+      const sameRuntime = !query.runtimeId || query.runtimeId === runtimeId;
+      const cursorAhead = requestedAfter > nextId;
+      const after = sameRuntime && !cursorAhead ? requestedAfter : 0;
+      const limit = Math.min(MAX_PAGE_LIMIT, positiveInteger(query.limit, DEFAULT_PAGE_LIMIT));
+      const oldestAvailableEventId = journal[0]?.event.eventId ?? null;
+      const latestEventId = nextId;
+      const gap = !sameRuntime || cursorAhead
+        || (oldestAvailableEventId !== null
+          ? after < oldestAvailableEventId - 1
+          : after < latestEventId);
+      const available = journal.filter((entry) => entry.event.eventId > after);
+      const selected: ConsoleEventEnvelope[] = [];
+      let selectedBytes = 0;
+      for (const entry of available) {
+        if (selected.length >= limit) break;
+        if (selected.length > 0 && selectedBytes + entry.bytes > historyPageByteLimit) break;
+        selected.push(entry.event);
+        selectedBytes += entry.bytes;
+      }
+      const items = Object.freeze(selected);
+      const nextAfter = items.at(-1)?.eventId ?? after;
+      return Object.freeze({
+        runtimeId,
+        items,
+        oldestAvailableEventId,
+        latestEventId,
+        nextAfter,
+        hasMore: available.length > items.length,
+        gap,
+      });
+    },
+    subscribe(response, options = {}) {
+      // Replay and subscription are synchronous relative to publish(), closing
+      // the race between HTTP recovery and the live stream hand-off.
+      const requestedAfter = nonNegativeInteger(options.after, 0);
+      const after = options.runtimeId && options.runtimeId !== runtimeId
+        || requestedAfter > nextId
+        ? 0
+        : requestedAfter;
+      try {
+        for (const entry of journal) {
+          if (entry.event.eventId > after) write(response, entry);
+        }
+        subscribers.add(response);
+      } catch {
+        remove(response);
+      }
       response.once('close', () => remove(response));
       response.once('error', () => remove(response));
       return () => remove(response);
     },
   };
 }
+
+export function serializeConsoleEvent(event: ConsoleEventEnvelope): string {
+  return `id: ${event.eventId}\nevent: ${event.type}\nruntime: ${event.runtimeId}\ntimestamp: ${event.timestamp}\ndata: ${JSON.stringify(event.data)}\n\n`;
+}
+
+function positiveInteger(value: unknown, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function nonNegativeInteger(value: unknown, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function jsonSnapshot(value: unknown): unknown {
+  const encoded = JSON.stringify(value ?? null);
+  if (encoded === undefined) throw new TypeError('Console event data must be JSON serializable');
+  if (Buffer.byteLength(encoded, 'utf8') > MAX_EVENT_BYTES) {
+    throw new RangeError(`Console event data exceeds ${MAX_EVENT_BYTES} bytes`);
+  }
+  return JSON.parse(encoded) as unknown;
+}

package/src/console-rpc-extended.ts

@@ -26,6 +26,7 @@ import {
 const TABLE_MESSAGE = 'unified_inbox_message';
 const TABLE_REQUEST = 'unified_inbox_request';
 const TABLE_NOTICE = 'unified_inbox_notice';
+const MAX_INBOX_OFFSET = 10_000;
 
 export interface ConsoleRpcExtendedCtx {
   /** full scope 才允许写操作；demo scope 只放行只读 RPC。 */
@@ -131,6 +132,8 @@ interface InboxSelection {
   orderBy?(field: string, direction?: 'ASC' | 'DESC'): InboxSelection;
   /** 可选：DB 侧 limit 下推。 */
   limit?(count: number): InboxSelection;
+  /** 可选：DB 侧 offset 下推。 */
+  offset?(count: number): InboxSelection;
   then<TResult1 = Record<string, unknown>[], TResult2 = never>(
     onfulfilled?: ((value: Record<string, unknown>[]) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
@@ -509,23 +512,34 @@ async function readInboxRows(
     orderBy?: { field: string; direction?: 'ASC' | 'DESC' };
     /** DB 侧 limit 下推（模型不支持时由调用方内存分页兜底）。 */
     limit?: number;
+    /** DB 侧 offset 下推（模型不支持时由调用方内存分页兜底）。 */
+    offset?: number;
   },
-): Promise<{ rows: Record<string, unknown>[]; enabled: boolean }> {
+): Promise<{ rows: Record<string, unknown>[]; enabled: boolean; offsetApplied: boolean }> {
   const model = getInboxModel(ctx, table);
-  if (!model) return { rows: [], enabled: false };
+  if (!model) return { rows: [], enabled: false, offsetApplied: false };
   try {
     let selection: InboxSelection = model.select().where(where);
+    let orderApplied = options?.orderBy == null;
     if (options?.orderBy && typeof selection.orderBy === 'function') {
       selection = selection.orderBy(options.orderBy.field, options.orderBy.direction ?? 'DESC');
+      orderApplied = true;
     }
-    if (options?.limit != null && typeof selection.limit === 'function') {
-      selection = selection.limit(options.limit);
+    const offset = options?.offset ?? 0;
+    const offsetSelection = orderApplied ? selection.offset : undefined;
+    const canApplyOffset = typeof offsetSelection === 'function';
+    const offsetApplied = offset === 0 || canApplyOffset;
+    if (offset > 0 && canApplyOffset) {
+      selection = offsetSelection.call(selection, offset);
+    }
+    if (options?.limit != null && orderApplied && typeof selection.limit === 'function') {
+      selection = selection.limit(options.limit + (offsetApplied ? 0 : offset));
     }
     const rows = await selection;
-    return { rows: Array.isArray(rows) ? rows : [], enabled: true };
+    return { rows: Array.isArray(rows) ? rows : [], enabled: true, offsetApplied };
   } catch {
     // 表未创建 / 方言未启动等场景降级为空，不向上抛。
-    return { rows: [], enabled: false };
+    return { rows: [], enabled: false, offsetApplied: false };
   }
 }
 
@@ -539,20 +553,26 @@ async function listInbox(
   const adapter = strField(d, '$adapter', 'adapter');
   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, {
+  const limit = boundedIntegerField(d, 30, 1, 100, '$limit', 'limit');
+  const offset = boundedIntegerField(
+    d, 0, 0, MAX_INBOX_OFFSET, '$offset', 'offset',
+  );
+  const unreadOnly = table === TABLE_NOTICE
+    && boolField(d, false, '$unread_only', 'unreadOnly', 'unread_only');
+  const { rows, enabled, offsetApplied } = await readInboxRows(ctx, table, {
     adapter,
     endpoint_id: endpointKey,
+    ...(unreadOnly ? { consumed: 0 } : {}),
   }, {
     // sort/limit 下推到 DB 侧（内存 sort/slice 保留，作为无下推能力模型的兜底）
     orderBy: { field: 'created_at', direction: 'DESC' },
-    limit: offset + limit,
+    limit,
+    offset,
   });
   const sorted = rows
     .slice()
     .sort((a, b) => Number(b.created_at ?? 0) - Number(a.created_at ?? 0))
-    .slice(offset, offset + limit)
+    .slice(offsetApplied ? 0 : offset, (offsetApplied ? 0 : offset) + limit)
     .map(mapRow);
   return { data: { [key]: sorted, inboxEnabled: enabled } };
 }
@@ -615,7 +635,7 @@ async function listInboxMessages(
   if (!adapter || !endpointKey || !channelId || !channelType) {
     return { error: '$adapter, $endpoint, $channel_id, $channel_type required' };
   }
-  const limit = Math.min(numField(d, 50, '$limit', 'limit'), 100);
+  const limit = boundedIntegerField(d, 50, 1, 100, '$limit', 'limit');
   const beforeTs = optionalNum(d, '$before_ts', 'beforeTs', 'before_ts');
   const beforeId = optionalNum(d, '$before_id', 'beforeId', 'before_id');
   const parent = normalizeParent(d.$parent ?? d.parent);
@@ -685,16 +705,18 @@ function mapRequestRow(row: Record<string, unknown>): Record<string, unknown> {
 function mapNoticeRow(row: Record<string, unknown>): Record<string, unknown> {
   const actorId = row.actor_id ?? undefined;
   const actorName = row.actor_name ?? undefined;
-  const sceneId = row.scene_id;
-  const sceneType = row.scene_type ?? undefined;
+  const sceneId = String(row.scene_id ?? '');
+  const sceneType = row.scene_type == null ? undefined : String(row.scene_type);
   return {
     id: row.id,
     platform_notice_id: row.platform_notice_id,
     type: row.type,
+    noticeType: row.type,
     scene_type: sceneType,
     scene_id: sceneId,
     channel_id: sceneId,
     channel_type: sceneType,
+    channel: { id: sceneId, type: sceneType ?? '' },
     sub_type: row.sub_type ?? undefined,
     actor_id: actorId,
     actor_name: actorName,
@@ -706,6 +728,8 @@ function mapNoticeRow(row: Record<string, unknown>): Record<string, unknown> {
     payload: row.payload,
     created_at: row.created_at,
     timestamp: row.created_at,
+    consumed: row.consumed,
+    consumed_at: row.consumed_at ?? undefined,
   };
 }
 
@@ -965,6 +989,26 @@ function numField(d: Record<string, unknown>, fallback: number, ...keys: string[
   return fallback;
 }
 
+function boundedIntegerField(
+  d: Record<string, unknown>,
+  fallback: number,
+  minimum: number,
+  maximum: number,
+  ...keys: string[]
+): number {
+  const value = numField(d, fallback, ...keys);
+  if (!Number.isFinite(value)) return fallback;
+  return Math.min(maximum, Math.max(minimum, Math.trunc(value)));
+}
+
+function boolField(d: Record<string, unknown>, fallback: boolean, ...keys: string[]): boolean {
+  for (const key of keys) {
+    const value = d[key];
+    if (typeof value === 'boolean') return value;
+  }
+  return fallback;
+}
+
 function optionalNum(d: Record<string, unknown>, ...keys: string[]): number | undefined {
   for (const key of keys) {
     if (d[key] == null) continue;

package/src/console-rpc.ts

@@ -801,6 +801,8 @@ export function isDemoHttpAllowed(method: string, pathname: string, apiBase: str
   const normalizedBase = apiBase.replace(/\/$/u, '') || '/api';
   const m = method.toUpperCase();
   if (m === 'GET' && pathname === `${normalizedBase}/events`) return true;
+  if (m === 'GET' && pathname === `${normalizedBase}/events/history`) return true;
+  if (m === 'GET' && DEMO_INTROSPECTION_PATHS.has(pathname.slice(normalizedBase.length))) return true;
   if (m === 'POST' && pathname === `${normalizedBase}/console/request`) return true;
   // Read-only dashboard / plugin inspection routes (legacy host-api parity).
   if (m === 'GET' && pathname === `${normalizedBase}/system/status`) return true;
@@ -809,3 +811,13 @@ export function isDemoHttpAllowed(method: string, pathname: string, apiBase: str
     || pathname.startsWith(`${normalizedBase}/plugins/`))) return true;
   return false;
 }
+
+const DEMO_INTROSPECTION_PATHS: ReadonlySet<string> = new Set([
+  '/introspection/commands',
+  '/introspection/middlewares',
+  '/introspection/components',
+  '/introspection/endpoints',
+  '/introspection/bindings',
+  '/introspection/tools',
+  '/introspection/mcp',
+]);