@zhin.js/host-http 1.0.10 → 1.0.12

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

@@ -47,19 +47,23 @@ export interface ConsoleRestCtx {
 /** 内省数据门面 — 由 basic/cli 用 agent 包 collectIntrospection* 装配。 */
 export interface ConsoleAgentIntrospection {
   commands?(): readonly unknown[];
+  middlewares?(): readonly unknown[];
+  components?(): readonly unknown[];
   bindings?(): readonly unknown[];
   tools?(): readonly unknown[];
   mcp?(): { rows: readonly unknown[]; note?: string } | readonly unknown[];
+  renderComponent?(input: Readonly<{
+    requester: string;
+    name: string;
+    props: unknown;
+    signal: AbortSignal;
+  }>): Promise<unknown>;
 }
 
 /** Session tree 门面 — 形状对齐 agent 包 SessionTreeRuntimeHandle。 */
 export interface ConsoleAgentSessionTree {
   resolveActiveSessionId(sessionKey: string): Promise<string | null>;
-  agentSessionStore: {
-    getBySessionId(sessionId: string): Promise<
-      { active_leaf_message_id?: number | null } | null | undefined
-    >;
-  };
+  getActiveLeafMessageId(sessionId: string): Promise<number | null>;
   listBranchPoints(sessionId: string): Promise<readonly unknown[]>;
   switchActiveLeaf(sessionId: string, messageId: number): Promise<boolean>;
   jumpToBranchIndex(
@@ -83,6 +87,12 @@ export interface ConsoleRestPagesOptions {
   readonly pluginRegistryUrl?: string;
   /** 默认 `https://registry.npmmirror.com`（legacy 同源）。 */
   readonly npmRegistryUrl?: string;
+  /** Component preview deadline; default 5 seconds. */
+  readonly componentPreviewTimeoutMs?: number;
+  /** Maximum serialized Component preview; default 256 KiB. */
+  readonly componentPreviewMaxBytes?: number;
+  /** Maximum in-flight Component previews per Console route set; default 2. */
+  readonly componentPreviewMaxConcurrent?: number;
 }
 
 type LogModelLike = {
@@ -109,6 +119,8 @@ type LogRow = {
 
 const INTROSPECTION_PAGE_SIZES = {
   commands: 25,
+  middlewares: 30,
+  components: 30,
   tools: 15,
   endpoints: 30,
   bindings: 30,
@@ -143,7 +155,7 @@ export function registerConsoleRestPages(
 
   registerLogsRoutes(route, base, ctx);
   registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl, npmRegistryUrl);
-  registerIntrospectionRoutes(route, base, ctx);
+  registerIntrospectionRoutes(route, base, ctx, options);
   registerAgentSessionRoutes(route, base, ctx);
 
   return () => {
@@ -551,6 +563,7 @@ function registerIntrospectionRoutes(
   route: HttpHost['route'],
   base: string,
   ctx: ConsoleRestCtx,
+  options: ConsoleRestPagesOptions,
 ): void {
   const collectors: Array<{
     kind: IntrospectionKind;
@@ -559,13 +572,33 @@ function registerIntrospectionRoutes(
   }> = [
     {
       kind: 'commands',
-      collect: () => ({ rows: agentIntrospection(ctx)?.commands?.() ?? [] }),
+      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.commands?.() ?? []) }),
       fields: [
         (c) => stringProp(c, 'pattern'),
         (c) => stringProp(c, 'desc'),
         (c) => stringProp(c, 'plugin'),
       ],
     },
+    {
+      kind: 'middlewares',
+      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.middlewares?.() ?? []) }),
+      fields: [
+        (m) => stringProp(m, 'name'),
+        (m) => stringProp(m, 'owner'),
+        (m) => stringProp(m, 'phase'),
+        (m) => stringProp(m, 'target'),
+        (m) => stringProp(m, 'source'),
+      ],
+    },
+    {
+      kind: 'components',
+      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.components?.() ?? []) }),
+      fields: [
+        (c) => stringProp(c, 'name'),
+        (c) => stringProp(c, 'owner'),
+        (c) => stringProp(c, 'source'),
+      ],
+    },
     {
       kind: 'endpoints',
       collect: () => ({
@@ -580,7 +613,7 @@ function registerIntrospectionRoutes(
     },
     {
       kind: 'bindings',
-      collect: () => ({ rows: agentIntrospection(ctx)?.bindings?.() ?? [] }),
+      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.bindings?.() ?? []) }),
       fields: [
         (a) => stringProp(a, 'name'),
         (a) => stringProp(a, 'provider'),
@@ -589,7 +622,7 @@ function registerIntrospectionRoutes(
     },
     {
       kind: 'tools',
-      collect: () => ({ rows: agentIntrospection(ctx)?.tools?.() ?? [] }),
+      collect: () => ({ rows: withAgentIntrospection(ctx, (value) => value?.tools?.() ?? []) }),
       fields: [
         (t) => stringProp(t, 'name'),
         (t) => stringProp(t, 'source'),
@@ -599,7 +632,7 @@ function registerIntrospectionRoutes(
     {
       kind: 'mcp',
       collect: () => {
-        const result = agentIntrospection(ctx)?.mcp?.();
+        const result = withAgentIntrospection(ctx, (value) => value?.mcp?.());
         if (result == null) return { rows: [] as readonly unknown[] };
         // readonly 数组不能用 Array.isArray 收窄，按对象形状判断
         if (typeof result === 'object' && 'rows' in result) {
@@ -625,7 +658,7 @@ function registerIntrospectionRoutes(
         );
         const missing = kind === 'endpoints'
           ? !ctx.getEndpoints
-          : !agentIntrospection(ctx);
+          : !hasAgentIntrospection(ctx);
         const degradedNote = note ?? (missing
           ? kind === 'endpoints'
             ? 'Endpoints 数据源未接线（ctx.getEndpoints 缺失）'
@@ -644,18 +677,146 @@ function registerIntrospectionRoutes(
       }
     }, { summary: `Introspection: ${kind}`, tags: ['console', 'introspection'] });
   }
+
+  let activeComponentPreviews = 0;
+  route('POST', `${base}/introspection/components/render`, async (request, response, _url, authScope) => {
+    if (!requireWriteScope(response, ctx, authScope)) return;
+    const body = (await readJsonBody<Record<string, unknown>>(request)) ?? {};
+    const requester = typeof body.requester === 'string' ? body.requester.trim() : '';
+    const name = typeof body.name === 'string' ? body.name.trim() : '';
+    if (!requester || !name || requester.length > 256 || name.length > 160) {
+      writeJson(response, 400, { success: false, error: '请提供有效的 requester 与 component name' });
+      return;
+    }
+    const maxConcurrent = clampPositiveInt(options.componentPreviewMaxConcurrent, 2, 8);
+    if (activeComponentPreviews >= maxConcurrent) {
+      writeJson(response, 503, { success: false, error: 'Component preview 正忙，请稍后重试' });
+      return;
+    }
+    const lease = ctx.acquireAgentRuntime?.();
+    const render = lease?.value.introspection?.renderComponent;
+    if (!lease || !render) {
+      lease?.release();
+      writeJson(response, 503, { success: false, error: 'Component Runtime 未就绪' });
+      return;
+    }
+    const controller = new AbortController();
+    const timeoutMs = clampPositiveInt(options.componentPreviewTimeoutMs, 5_000, 30_000);
+    const timeout = setTimeout(() => controller.abort(
+      new ComponentPreviewTimeoutError(`Component preview 超过 ${timeoutMs}ms`),
+    ), timeoutMs);
+    activeComponentPreviews += 1;
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      activeComponentPreviews -= 1;
+      lease.release();
+    };
+    const renderPromise = Promise.resolve().then(() =>
+      render({ requester, name, props: body.props ?? {}, signal: controller.signal }));
+    // A timed-out implementation may ignore AbortSignal. Keep its generation
+    // lease until the real operation settles; the bounded concurrency gate
+    // prevents non-cooperative previews from pinning unbounded generations.
+    void renderPromise.then(release, release);
+    try {
+      const output = await raceWithAbort(
+        renderPromise,
+        controller.signal,
+      );
+      assertPreviewOutput(output, options.componentPreviewMaxBytes ?? 256 * 1024);
+      writeJson(response, 200, { success: true, data: { requester, name, output } });
+    } catch (error) {
+      const status = error instanceof ComponentPreviewTimeoutError
+        ? 408
+        : error instanceof ComponentPreviewLimitError ? 413 : 422;
+      writeJson(response, status, {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      clearTimeout(timeout);
+      if (!controller.signal.aborted) controller.abort();
+    }
+  }, { summary: 'Render a Component preview', tags: ['console', 'introspection', 'component'] });
+}
+
+class ComponentPreviewTimeoutError extends Error {
+  override readonly name = 'ComponentPreviewTimeoutError';
+}
+
+class ComponentPreviewLimitError extends Error {
+  override readonly name = 'ComponentPreviewLimitError';
+}
+
+function clampPositiveInt(value: number | undefined, fallback: number, ceiling: number): number {
+  if (!Number.isFinite(value) || !value || value < 1) return fallback;
+  return Math.min(Math.floor(value), ceiling);
+}
+
+async function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) throw abortReason(signal);
+  return await new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(abortReason(signal));
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+  });
+}
+
+function abortReason(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new DOMException('Component preview aborted', 'AbortError');
+}
+
+function assertPreviewOutput(output: unknown, maxBytes: number): void {
+  const byteLimit = clampPositiveInt(maxBytes, 256 * 1024, 1024 * 1024);
+  const seen = new WeakSet<object>();
+  let nodes = 0;
+  const visit = (value: unknown, depth: number): void => {
+    nodes += 1;
+    if (nodes > 10_000) throw new ComponentPreviewLimitError('Component preview 节点数超过 10000');
+    if (depth > 24) throw new ComponentPreviewLimitError('Component preview 嵌套深度超过 24');
+    if (!value || typeof value !== 'object') return;
+    if (seen.has(value)) throw new ComponentPreviewLimitError('Component preview 不能包含循环引用');
+    seen.add(value);
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item, depth + 1);
+    } else {
+      for (const item of Object.values(value as Record<string, unknown>)) visit(item, depth + 1);
+    }
+  };
+  visit(output, 0);
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(output);
+  } catch (error) {
+    throw new ComponentPreviewLimitError(
+      `Component preview 无法序列化: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (Buffer.byteLength(serialized ?? '') > byteLimit) {
+    throw new ComponentPreviewLimitError(`Component preview 超过 ${byteLimit} bytes`);
+  }
 }
 
-function agentIntrospection(ctx: ConsoleRestCtx): ConsoleAgentIntrospection | undefined {
+function withAgentIntrospection<T>(
+  ctx: ConsoleRestCtx,
+  operation: (value: ConsoleAgentIntrospection | undefined) => T,
+): T {
   const lease = ctx.acquireAgentRuntime?.();
-  if (!lease) return undefined;
+  if (!lease) return operation(undefined);
   try {
-    return lease.value.introspection;
+    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）
 // ---------------------------------------------------------------------------
@@ -708,14 +869,14 @@ function registerAgentSessionRoutes(
         return;
       }
 
-      const session = await runtime.agentSessionStore.getBySessionId(sessionId);
+      const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
       const points = await runtime.listBranchPoints(sessionId);
       writeJson(response, 200, {
         success: true,
         data: {
           sessionKey: parsed.sessionKey,
           sessionId,
-          activeLeafMessageId: session?.active_leaf_message_id ?? null,
+          activeLeafMessageId,
           points,
         },
       });
@@ -782,28 +943,28 @@ function registerAgentSessionRoutes(
 
       if (branchIndex !== undefined) {
         const result = await runtime.jumpToBranchIndex(sessionId, branchIndex);
-        const session = await runtime.agentSessionStore.getBySessionId(sessionId);
+        const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
         writeJson(response, result.ok ? 200 : 400, {
           success: result.ok,
           message: result.message,
           data: {
             sessionKey: parsed.sessionKey,
             sessionId,
-            activeLeafMessageId: session?.active_leaf_message_id ?? null,
+            activeLeafMessageId,
           },
         });
         return;
       }
 
       const ok = await runtime.switchActiveLeaf(sessionId, messageId!);
-      const session = await runtime.agentSessionStore.getBySessionId(sessionId);
+      const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
       writeJson(response, ok ? 200 : 400, {
         success: ok,
         message: ok ? `已切换 active leaf 至消息 #${messageId}` : '切换失败',
         data: {
           sessionKey: parsed.sessionKey,
           sessionId,
-          activeLeafMessageId: session?.active_leaf_message_id ?? null,
+          activeLeafMessageId,
         },
       });
     } finally {