@zhin.js/host-http 1.0.12 → 1.0.13

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.js

@@ -722,5 +722,6 @@ const DEMO_INTROSPECTION_PATHS = new Set([
     '/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.12",
+  "version": "1.0.13",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -20,8 +20,8 @@
     "ws": "^8.21.1",
     "@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-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.ts

@@ -819,5 +819,6 @@ const DEMO_INTROSPECTION_PATHS: ReadonlySet<string> = new Set([
   '/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';