@zhin.js/host-http 1.0.11 → 1.0.13

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-rest-pages.d.ts

@@ -34,6 +34,7 @@ export interface ConsoleAgentIntrospection {
     components?(): readonly unknown[];
     bindings?(): readonly unknown[];
     tools?(): readonly unknown[];
+    promptSections?(): readonly unknown[];
     mcp?(): {
         rows: readonly unknown[];
         note?: string;

package/lib/console-rest-pages.js

@@ -6,6 +6,7 @@ const INTROSPECTION_PAGE_SIZES = {
     middlewares: 30,
     components: 30,
     tools: 15,
+    'prompt-sections': 20,
     endpoints: 30,
     bindings: 30,
     mcp: 30,
@@ -384,7 +385,7 @@ function registerIntrospectionRoutes(route, base, ctx, options) {
     const collectors = [
         {
             kind: 'commands',
-            collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.commands?.() ?? []) }),
+            collect: (value) => ({ rows: value?.commands?.() ?? [] }),
             fields: [
                 (c) => stringProp(c, 'pattern'),
                 (c) => stringProp(c, 'desc'),
@@ -393,7 +394,7 @@ function registerIntrospectionRoutes(route, base, ctx, options) {
         },
         {
             kind: 'middlewares',
-            collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.middlewares?.() ?? []) }),
+            collect: (value) => ({ rows: value?.middlewares?.() ?? [] }),
             fields: [
                 (m) => stringProp(m, 'name'),
                 (m) => stringProp(m, 'owner'),
@@ -404,7 +405,7 @@ function registerIntrospectionRoutes(route, base, ctx, options) {
         },
         {
             kind: 'components',
-            collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.components?.() ?? []) }),
+            collect: (value) => ({ rows: value?.components?.() ?? [] }),
             fields: [
                 (c) => stringProp(c, 'name'),
                 (c) => stringProp(c, 'owner'),
@@ -425,7 +426,7 @@ function registerIntrospectionRoutes(route, base, ctx, options) {
         },
         {
             kind: 'bindings',
-            collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.bindings?.() ?? []) }),
+            collect: (value) => ({ rows: value?.bindings?.() ?? [] }),
             fields: [
                 (a) => stringProp(a, 'name'),
                 (a) => stringProp(a, 'provider'),
@@ -434,17 +435,30 @@ function registerIntrospectionRoutes(route, base, ctx, options) {
         },
         {
             kind: 'tools',
-            collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.tools?.() ?? []) }),
+            collect: (value) => ({ rows: value?.tools?.() ?? [] }),
             fields: [
                 (t) => stringProp(t, 'name'),
                 (t) => stringProp(t, 'source'),
                 (t) => stringProp(t, 'description'),
             ],
         },
+        {
+            kind: 'prompt-sections',
+            collect: (value) => ({ rows: value?.promptSections?.() ?? [] }),
+            fields: [
+                (section) => stringProp(section, 'name'),
+                (section) => stringProp(section, 'qualifiedName'),
+                (section) => stringProp(section, 'title'),
+                (section) => stringProp(section, 'owner'),
+                (section) => stringProp(section, 'layer'),
+                (section) => stringProp(section, 'retention'),
+                (section) => stringProp(section, 'source'),
+            ],
+        },
         {
             kind: 'mcp',
-            collect: () => {
-                const result = withAgentIntrospection(ctx, (value) => value?.mcp?.());
+            collect: (value) => {
+                const result = value?.mcp?.();
                 if (result == null)
                     return { rows: [] };
                 // readonly 数组不能用 Array.isArray 收窄，按对象形状判断
@@ -458,15 +472,17 @@ function registerIntrospectionRoutes(route, base, ctx, options) {
     ];
     for (const { kind, collect, fields } of collectors) {
         route('GET', `${base}/introspection/${kind}`, async (_request, response, url) => {
+            const lease = kind === 'endpoints' ? null : ctx.acquireAgentRuntime?.() ?? null;
             try {
-                const { rows, note } = collect();
+                const introspection = lease?.value.introspection;
+                const { rows, note } = collect(introspection);
                 const query = url.searchParams;
                 const filter = query.get('filter')?.trim() || undefined;
                 const filtered = filterByFields([...rows], filter, fields);
                 const slice = paginateItems(filtered, parsePositiveInt(query.get('page'), 1), parsePositiveInt(query.get('pageSize'), INTROSPECTION_PAGE_SIZES[kind]));
                 const missing = kind === 'endpoints'
                     ? !ctx.getEndpoints
-                    : !hasAgentIntrospection(ctx);
+                    : !introspection;
                 const degradedNote = note ?? (missing
                     ? kind === 'endpoints'
                         ? 'Endpoints 数据源未接线（ctx.getEndpoints 缺失）'
@@ -484,6 +500,9 @@ function registerIntrospectionRoutes(route, base, ctx, options) {
                     error: err instanceof Error ? err.message : String(err),
                 });
             }
+            finally {
+                lease?.release();
+            }
         }, { summary: `Introspection: ${kind}`, tags: ['console', 'introspection'] });
     }
     let activeComponentPreviews = 0;
@@ -608,20 +627,6 @@ function assertPreviewOutput(output, maxBytes) {
         throw new ComponentPreviewLimitError(`Component preview 超过 ${byteLimit} bytes`);
     }
 }
-function withAgentIntrospection(ctx, operation) {
-    const lease = ctx.acquireAgentRuntime?.();
-    if (!lease)
-        return operation(undefined);
-    try {
-        return operation(lease.value.introspection);
-    }
-    finally {
-        lease.release();
-    }
-}
-function hasAgentIntrospection(ctx) {
-    return withAgentIntrospection(ctx, (value) => value !== undefined);
-}
 // ---------------------------------------------------------------------------
 // agent sessions（legacy agent-sessions-rest-api.ts；ADR 0010 D3）
 // ---------------------------------------------------------------------------

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,13 @@ 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/prompt-sections',
+    '/introspection/mcp',
+]);

package/lib/http-host.d.ts

@@ -38,16 +38,21 @@ export type HttpHandler = (request: IncomingMessage, response: ServerResponse, u
 export interface HttpRouteRegistration {
     (): void;
 }
-export interface HttpHost extends GenerationAdmissionBindable<HttpHost> {
+/** @public Stable HTTP and WebSocket Host contract resolved through `httpHostToken`. */
+export interface HttpHost {
     ws(path: string): WsHandle;
     route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
     listRoutes(): readonly ListedRoute[];
     get address(): HttpHostAddress | undefined;
+    /** @internal Console authentication registry owned by the process Host. */
     get tokenRegistry(): TokenRegistry;
 }
-export interface ProcessHttpHost extends HttpHost {
+/** @internal Process-root lifecycle and generation admission surface. */
+export interface ProcessHttpHost extends HttpHost, GenerationAdmissionBindable<HttpHost> {
     listen(): Promise<HttpHostAddress>;
     close(): Promise<void>;
 }
+/** @public Stable Plugin Runtime HTTP Host token. */
 export declare const httpHostToken: import("@zhin.js/plugin-runtime").Token<HttpHost>;
+/** @internal CLI composition-root factory. */
 export declare function createHttpHost(options?: HttpHostOptions): ProcessHttpHost;

package/lib/http-host.js

@@ -9,7 +9,9 @@ import { HttpBodyError } from './json-body.js';
 const logger = getLogger('http');
 export const REMOTE_CONSOLE_ORIGIN = 'https://console.zhin.dev';
 const DEFAULT_CORS_ORIGINS = Object.freeze([REMOTE_CONSOLE_ORIGIN]);
+/** @public Stable Plugin Runtime HTTP Host token. */
 export const httpHostToken = createToken('zhin.host.http');
+/** @internal CLI composition-root factory. */
 export function createHttpHost(options = {}) {
     const host = options.host ?? '127.0.0.1';
     const port = options.port ?? 8086;

package/lib/public-api.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Plugin-facing HTTP Host contract exposed from `@zhin.js/host-http`.
+ * @module @zhin.js/host-http
+ */
+export { httpHostToken, type HttpHandler, type HttpHost, type HttpHostAddress, type HttpRouteRegistration, type WsConnection, type WsHandle, } from './http-host.js';
+export type { AuthenticatedTokenPrincipal, AuthScope } from './token-registry.js';
+export type { ListedRoute, OpenApiParameter, RouteMeta } from './openapi.js';

package/lib/public-api.js

@@ -0,0 +1,5 @@
+/**
+ * Plugin-facing HTTP Host contract exposed from `@zhin.js/host-http`.
+ * @module @zhin.js/host-http
+ */
+export { httpHostToken, } from './http-host.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "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.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"
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/plugin-runtime": "1.1.8"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

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-rest-pages.ts

@@ -51,6 +51,7 @@ export interface ConsoleAgentIntrospection {
   components?(): readonly unknown[];
   bindings?(): readonly unknown[];
   tools?(): readonly unknown[];
+  promptSections?(): readonly unknown[];
   mcp?(): { rows: readonly unknown[]; note?: string } | readonly unknown[];
   renderComponent?(input: Readonly<{
     requester: string;
@@ -122,6 +123,7 @@ const INTROSPECTION_PAGE_SIZES = {
   middlewares: 30,
   components: 30,
   tools: 15,
+  'prompt-sections': 20,
   endpoints: 30,
   bindings: 30,
   mcp: 30,
@@ -567,12 +569,12 @@ function registerIntrospectionRoutes(
 ): void {
   const collectors: Array<{
     kind: IntrospectionKind;
-    collect: () => { rows: readonly unknown[]; note?: string };
+    collect: (introspection: ConsoleAgentIntrospection | undefined) => { rows: readonly unknown[]; note?: string };
     fields: Array<(item: unknown) => string | undefined>;
   }> = [
     {
       kind: 'commands',
-      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.commands?.() ?? []) }),
+      collect: (value) => ({ rows: value?.commands?.() ?? [] }),
       fields: [
         (c) => stringProp(c, 'pattern'),
         (c) => stringProp(c, 'desc'),
@@ -581,7 +583,7 @@ function registerIntrospectionRoutes(
     },
     {
       kind: 'middlewares',
-      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.middlewares?.() ?? []) }),
+      collect: (value) => ({ rows: value?.middlewares?.() ?? [] }),
       fields: [
         (m) => stringProp(m, 'name'),
         (m) => stringProp(m, 'owner'),
@@ -592,7 +594,7 @@ function registerIntrospectionRoutes(
     },
     {
       kind: 'components',
-      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.components?.() ?? []) }),
+      collect: (value) => ({ rows: value?.components?.() ?? [] }),
       fields: [
         (c) => stringProp(c, 'name'),
         (c) => stringProp(c, 'owner'),
@@ -613,7 +615,7 @@ function registerIntrospectionRoutes(
     },
     {
       kind: 'bindings',
-      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.bindings?.() ?? []) }),
+      collect: (value) => ({ rows: value?.bindings?.() ?? [] }),
       fields: [
         (a) => stringProp(a, 'name'),
         (a) => stringProp(a, 'provider'),
@@ -622,17 +624,30 @@ function registerIntrospectionRoutes(
     },
     {
       kind: 'tools',
-      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.tools?.() ?? []) }),
+      collect: (value) => ({ rows: value?.tools?.() ?? [] }),
       fields: [
         (t) => stringProp(t, 'name'),
         (t) => stringProp(t, 'source'),
         (t) => stringProp(t, 'description'),
       ],
     },
+    {
+      kind: 'prompt-sections',
+      collect: (value) => ({ rows: value?.promptSections?.() ?? [] }),
+      fields: [
+        (section) => stringProp(section, 'name'),
+        (section) => stringProp(section, 'qualifiedName'),
+        (section) => stringProp(section, 'title'),
+        (section) => stringProp(section, 'owner'),
+        (section) => stringProp(section, 'layer'),
+        (section) => stringProp(section, 'retention'),
+        (section) => stringProp(section, 'source'),
+      ],
+    },
     {
       kind: 'mcp',
-      collect: () => {
-        const result = withAgentIntrospection(ctx, (value) => value?.mcp?.());
+      collect: (value) => {
+        const result = value?.mcp?.();
         if (result == null) return { rows: [] as readonly unknown[] };
         // readonly 数组不能用 Array.isArray 收窄，按对象形状判断
         if (typeof result === 'object' && 'rows' in result) {
@@ -646,8 +661,10 @@ function registerIntrospectionRoutes(
 
   for (const { kind, collect, fields } of collectors) {
     route('GET', `${base}/introspection/${kind}`, async (_request, response, url) => {
+      const lease = kind === 'endpoints' ? null : ctx.acquireAgentRuntime?.() ?? null;
       try {
-        const { rows, note } = collect();
+        const introspection = lease?.value.introspection;
+        const { rows, note } = collect(introspection);
         const query = url.searchParams;
         const filter = query.get('filter')?.trim() || undefined;
         const filtered = filterByFields([...rows], filter, fields);
@@ -658,7 +675,7 @@ function registerIntrospectionRoutes(
         );
         const missing = kind === 'endpoints'
           ? !ctx.getEndpoints
-          : !hasAgentIntrospection(ctx);
+          : !introspection;
         const degradedNote = note ?? (missing
           ? kind === 'endpoints'
             ? 'Endpoints 数据源未接线（ctx.getEndpoints 缺失）'
@@ -674,6 +691,8 @@ function registerIntrospectionRoutes(
           data: { items: [], page: 1, pageSize: 0, total: 0, totalPages: 0 },
           error: err instanceof Error ? err.message : String(err),
         });
+      } finally {
+        lease?.release();
       }
     }, { summary: `Introspection: ${kind}`, tags: ['console', 'introspection'] });
   }
@@ -800,23 +819,6 @@ function assertPreviewOutput(output: unknown, maxBytes: number): void {
   }
 }
 
-function withAgentIntrospection<T>(
-  ctx: ConsoleRestCtx,
-  operation: (value: ConsoleAgentIntrospection | undefined) => T,
-): T {
-  const lease = ctx.acquireAgentRuntime?.();
-  if (!lease) return operation(undefined);
-  try {
-    return operation(lease.value.introspection);
-  } finally {
-    lease.release();
-  }
-}
-
-function hasAgentIntrospection(ctx: ConsoleRestCtx): boolean {
-  return withAgentIntrospection(ctx, (value) => value !== undefined);
-}
-
 // ---------------------------------------------------------------------------
 // agent sessions（legacy agent-sessions-rest-api.ts；ADR 0010 D3）
 // ---------------------------------------------------------------------------

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,14 @@ 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/prompt-sections',
+  '/introspection/mcp',
+]);

package/src/http-host.ts

@@ -81,7 +81,8 @@ export interface HttpRouteRegistration {
   (): void;
 }
 
-export interface HttpHost extends GenerationAdmissionBindable<HttpHost> {
+/** @public Stable HTTP and WebSocket Host contract resolved through `httpHostToken`. */
+export interface HttpHost {
   ws(path: string): WsHandle;
   route(
     method: string,
@@ -91,10 +92,12 @@ export interface HttpHost extends GenerationAdmissionBindable<HttpHost> {
   ): HttpRouteRegistration;
   listRoutes(): readonly ListedRoute[];
   get address(): HttpHostAddress | undefined;
+  /** @internal Console authentication registry owned by the process Host. */
   get tokenRegistry(): TokenRegistry;
 }
 
-export interface ProcessHttpHost extends HttpHost {
+/** @internal Process-root lifecycle and generation admission surface. */
+export interface ProcessHttpHost extends HttpHost, GenerationAdmissionBindable<HttpHost> {
   listen(): Promise<HttpHostAddress>;
   close(): Promise<void>;
 }
@@ -109,13 +112,17 @@ interface HttpRoute {
   readonly admission?: GenerationAdmissionGate;
 }
 
+interface AdmissionBoundHttpHost extends HttpHost, GenerationAdmissionBindable<HttpHost> {}
+
 interface WsRoute {
   readonly listener: (connection: WsConnection) => void;
   readonly admission?: GenerationAdmissionGate;
 }
 
+/** @public Stable Plugin Runtime HTTP Host token. */
 export const httpHostToken = createToken<HttpHost>('zhin.host.http');
 
+/** @internal CLI composition-root factory. */
 export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   const host = options.host ?? '127.0.0.1';
   const port = options.port ?? 8086;
@@ -453,8 +460,8 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
 
   function createBoundHost(
     admission: GenerationAdmissionGate,
-  ): HttpHost {
-    const bound: HttpHost = {
+  ): AdmissionBoundHttpHost {
+    const bound: AdmissionBoundHttpHost = {
       [generationAdmissionBinder]: (next) => createBoundHost(next),
       ws: (path) => registerWs(path, admission),
       route: (method, path, handler, meta) => registerRoute(

package/src/public-api.ts

@@ -0,0 +1,15 @@
+/**
+ * Plugin-facing HTTP Host contract exposed from `@zhin.js/host-http`.
+ * @module @zhin.js/host-http
+ */
+export {
+  httpHostToken,
+  type HttpHandler,
+  type HttpHost,
+  type HttpHostAddress,
+  type HttpRouteRegistration,
+  type WsConnection,
+  type WsHandle,
+} from './http-host.js';
+export type { AuthenticatedTokenPrincipal, AuthScope } from './token-registry.js';
+export type { ListedRoute, OpenApiParameter, RouteMeta } from './openapi.js';