@zhin.js/host-http 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @zhin.js/host-http
+
+Minimal HTTP and WebSocket host for Plugin Runtime. Provides `httpHostToken` so Adapters and
+Console can register path-scoped WebSocket / HTTP routes without importing Koa or the legacy
+`@zhin.js/host-router`.
+
+Root installs the host via `installResources` (see `basic/cli/src/plugin-runtime/http-host-installer.ts`
+and `console-host-installer.ts`).
+
+## Capabilities (this slice)
+
+- Path-scoped WebSocket upgrades (`ws(path)`)
+- HTTP `route(method, path, handler, meta?)` (exact + `/*` prefix)
+- Built-in `GET /pub/health` and `GET /pub/openapi.json`
+- CORS allowlist (always includes `https://console.zhin.dev`)
+- Optional Bearer auth for `/api/*` when `http.token` / `http.tokens` are set (ADR 0016 scopes)
+- WebSocket upgrade auth (Authorization or `?token=`); demo scope limited to `/sandbox`
+- `readJsonBody()` helper for JSON POST/PUT bodies (no Koa)
+
+```ts
+import { httpHostToken, type HttpHost } from '@zhin.js/host-http';
+
+const http = context.use(httpHostToken);
+const handle = http.ws('/sandbox');
+handle.onConnection(({ socket, authScope }) => { /* ... */ });
+
+http.route('GET', '/api/secure', (_req, res, _url, scope) => {
+  res.writeHead(200, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({ scope }));
+});
+```
+
+## Config (`http` in Root YAML)
+
+```yaml
+http:
+  host: 127.0.0.1
+  port: 8086
+  token: ${HTTP_TOKEN}          # full scope
+  tokens:
+    - token: ${DEMO_TOKEN}
+      scope: demo
+  corsOrigins:
+    - https://example.test
+  base: /api                    # auth prefix
+```
+
+Still deferred to later host migration: full `@zhin.js/host-api` management-plane REST/RPC/SSE
+and retiring the legacy Koa `@zhin.js/host-router` stack.

package/lib/console-rest-pages.d.ts

@@ -0,0 +1,70 @@
+import type { HttpHost } from './http-host.js';
+/** 与 basic/cli 接线方对齐的上下文约定。 */
+export interface ConsoleRestCtx {
+    /** false = demo 部署：只读 GET 放行，写操作一律 403。 */
+    readonly fullScope: boolean;
+    readonly projectRoot: string;
+    readonly getEndpoints?: () => readonly {
+        name: string;
+        adapter: string;
+        connected: boolean;
+        status: string;
+    }[];
+    /**
+     * 可选：返回新 Runtime 的 agent 门面（见 {@link ConsoleAgentRuntime}）。
+     * 未接线时 introspection 降级为空列表 + note，session tree 返回 503。
+     */
+    readonly getAgentRuntime?: () => unknown;
+    /** Database host（logs 页数据源：SystemLog 模型）。 */
+    readonly databaseHost?: {
+        readonly dialect: string;
+        readonly started: boolean;
+        readonly models: {
+            get(name: string): unknown;
+        };
+    };
+}
+/** 内省数据门面 — 由 basic/cli 用 agent 包 collectIntrospection* 装配。 */
+export interface ConsoleAgentIntrospection {
+    commands?(): readonly unknown[];
+    bindings?(): readonly unknown[];
+    tools?(): readonly unknown[];
+    mcp?(): {
+        rows: readonly unknown[];
+        note?: string;
+    } | readonly 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>;
+    };
+    listBranchPoints(sessionId: string): Promise<readonly unknown[]>;
+    switchActiveLeaf(sessionId: string, messageId: number): Promise<boolean>;
+    jumpToBranchIndex(sessionId: string, index: number): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+}
+/** `ctx.getAgentRuntime()` 返回值的最小结构约定（全部可选，逐项降级）。 */
+export interface ConsoleAgentRuntime {
+    readonly introspection?: ConsoleAgentIntrospection;
+    readonly sessionTree?: ConsoleAgentSessionTree;
+}
+export interface ConsoleRestPagesOptions {
+    /** 默认 `/api`。 */
+    readonly apiBase?: string;
+    /** 测试注入用；默认全局 fetch。 */
+    readonly fetchFn?: typeof fetch;
+    /** 默认 `https://zhin.js.org/plugins.json`（legacy 同源）。 */
+    readonly pluginRegistryUrl?: string;
+    /** 默认 `https://registry.npmmirror.com`（legacy 同源）。 */
+    readonly npmRegistryUrl?: string;
+}
+/**
+ * 注册 Console 页面 REST 路由。返回注销函数（注销全部已注册路由）。
+ */
+export declare function registerConsoleRestPages(host: HttpHost, ctx: ConsoleRestCtx, options?: ConsoleRestPagesOptions): () => void;