@zhin.js/host-http 1.1.13 → 1.1.15

package/lib/console-rest-pages.js

@@ -1,17 +1,16 @@
+/**
+ * Console REST pages — logs / marketplace / introspection / agent sessions。
+ *
+ * 统一提供日志、市场、Runtime snapshot 内省和 Agent session tree 页面。
+ *
+ * 数据源不可用时降级：读操作返回空数组 + `note` 说明，session tree 返回 503；
+ * 写操作要求 `ctx.fullScope && authScope === 'full'`，否则 403。
+ */
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { HttpBodyError, readJsonBody } from './json-body.js';
+import { readJsonBody } from './json-body.js';
 import { MarketplaceRegistry } from './marketplace-registry.js';
-const INTROSPECTION_PAGE_SIZES = {
-    commands: 25,
-    middlewares: 30,
-    components: 30,
-    tools: 15,
-    'prompt-sections': 20,
-    endpoints: 30,
-    bindings: 30,
-    mcp: 30,
-};
+import { clampPositiveInt, decodePathParam, normalizeBase, parsePositiveInt, registerAgentSessionRoutes, registerIntrospectionRoutes, requireWriteScope, trimTrailingSlashes, writeJson, } from './console-rest-pages-helpers.js';
 const PLUGINS_CACHE_TTL = 5 * 60 * 1000;
 /**
  * 注册 Console 页面 REST 路由。返回注销函数（注销全部已注册路由）。
@@ -399,562 +398,3 @@ async function listInstalledPluginPackages(projectRoot) {
         }
     }));
 }
-// ---------------------------------------------------------------------------
-// Runtime snapshot introspection
-// ---------------------------------------------------------------------------
-function registerIntrospectionRoutes(route, base, ctx, options) {
-    const collectors = [
-        {
-            kind: 'commands',
-            collect: (value) => ({ rows: value?.commands?.() ?? [] }),
-            fields: [
-                (c) => stringProp(c, 'pattern'),
-                (c) => stringProp(c, 'desc'),
-                (c) => stringProp(c, 'plugin'),
-            ],
-        },
-        {
-            kind: 'middlewares',
-            collect: (value) => ({ rows: 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: (value) => ({ rows: value?.components?.() ?? [] }),
-            fields: [
-                (c) => stringProp(c, 'name'),
-                (c) => stringProp(c, 'owner'),
-                (c) => stringProp(c, 'source'),
-            ],
-        },
-        {
-            kind: 'endpoints',
-            collect: () => ({
-                rows: (ctx.getEndpoints?.() ?? []).map((endpoint) => ({
-                    adapter: endpoint.adapter,
-                    name: endpoint.name,
-                    online: endpoint.connected,
-                    status: endpoint.status,
-                })),
-            }),
-            fields: [(b) => stringProp(b, 'adapter'), (b) => stringProp(b, 'name')],
-        },
-        {
-            kind: 'bindings',
-            collect: (value) => ({ rows: value?.bindings?.() ?? [] }),
-            fields: [
-                (a) => stringProp(a, 'name'),
-                (a) => stringProp(a, 'provider'),
-                (a) => stringProp(a, 'model'),
-            ],
-        },
-        {
-            kind: '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: (value) => {
-                const result = value?.mcp?.();
-                if (result == null)
-                    return { rows: [] };
-                // readonly 数组不能用 Array.isArray 收窄，按对象形状判断
-                if (typeof result === 'object' && 'rows' in result) {
-                    return { rows: result.rows, note: result.note };
-                }
-                return { rows: result };
-            },
-            fields: [(s) => stringProp(s, 'name')],
-        },
-    ];
-    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 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
-                    : !introspection;
-                const degradedNote = note ?? (missing
-                    ? kind === 'endpoints'
-                        ? 'Endpoints 数据源未接线（ctx.getEndpoints 缺失）'
-                        : 'Agent runtime 未装配（basic/cli 未接线 acquireAgentRuntime）'
-                    : undefined);
-                writeJson(response, 200, {
-                    success: true,
-                    data: { ...slice, filter, note: degradedNote },
-                });
-            }
-            catch (err) {
-                writeJson(response, 503, {
-                    success: false,
-                    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'] });
-    }
-    let activeComponentPreviews = 0;
-    route('POST', `${base}/introspection/components/render`, async (request, response, _url, authScope) => {
-        if (!requireWriteScope(response, ctx, authScope))
-            return;
-        const body = (await readJsonBody(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;
-        const previewDelivery = lease?.value.introspection?.previewComponentDelivery;
-        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(() => {
-            const input = { requester, name, props: body.props ?? {}, signal: controller.signal };
-            if (body.target === undefined)
-                return render(input).then(output => ({ output }));
-            if (!previewDelivery)
-                throw new Error('Target-aware Component preview 未就绪');
-            return previewDelivery({ ...input, target: body.target });
-        });
-        // 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 preview = await raceWithAbort(renderPromise, controller.signal);
-            assertPreviewOutput(preview, options.componentPreviewMaxBytes ?? 256 * 1024);
-            writeJson(response, 200, { success: true, data: { requester, name, ...preview } });
-        }
-        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 {
-    name = 'ComponentPreviewTimeoutError';
-}
-class ComponentPreviewLimitError extends Error {
-    name = 'ComponentPreviewLimitError';
-}
-function clampPositiveInt(value, fallback, ceiling) {
-    if (!Number.isFinite(value) || !value || value < 1)
-        return fallback;
-    return Math.min(Math.floor(value), ceiling);
-}
-async function raceWithAbort(promise, signal) {
-    if (signal.aborted)
-        throw abortReason(signal);
-    return await new Promise((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) {
-    return signal.reason instanceof Error
-        ? signal.reason
-        : new DOMException('Component preview aborted', 'AbortError');
-}
-function assertPreviewOutput(output, maxBytes) {
-    const byteLimit = clampPositiveInt(maxBytes, 256 * 1024, 1024 * 1024);
-    const seen = new WeakSet();
-    let nodes = 0;
-    const visit = (value, depth) => {
-        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))
-                visit(item, depth + 1);
-        }
-    };
-    visit(output, 0);
-    let serialized;
-    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`);
-    }
-}
-// ---------------------------------------------------------------------------
-// agent sessions（legacy agent-sessions-rest-api.ts；ADR 0010 D3）
-// ---------------------------------------------------------------------------
-function registerAgentSessionRoutes(route, base, ctx) {
-    const prefix = `${base}/agent/sessions/`;
-    const acquireSessionTree = () => {
-        const lease = ctx.acquireAgentRuntime?.();
-        const tree = lease?.value.sessionTree;
-        if (!lease || !tree || typeof tree.resolveActiveSessionId !== 'function') {
-            lease?.release();
-            return null;
-        }
-        return { tree, release: () => lease.release() };
-    };
-    const unavailable = (response) => {
-        writeJson(response, 503, {
-            success: false,
-            error: 'Agent session tree runtime 未就绪（新 Runtime 需经 acquireAgentRuntime 装配 sessionTree）',
-        });
-    };
-    // HttpHost 无 `:param` 路由，用前缀路由匹配 `<sessionKey>/tree|message|leaf`。
-    route('GET', `${base}/agent/sessions/*`, async (_request, response, url) => {
-        const messageAction = parseSessionAction(url.pathname, prefix, 'message');
-        if (messageAction)
-            response.setHeader('Cache-Control', 'no-store');
-        const parsed = messageAction ?? parseSessionAction(url.pathname, prefix, 'tree');
-        if (!parsed) {
-            writeJson(response, 404, { success: false, error: 'Not found' });
-            return;
-        }
-        const messageId = Number(url.searchParams.get('messageId'));
-        const expectedSessionId = url.searchParams.get('sessionId');
-        if (messageAction && (!Number.isSafeInteger(messageId) || messageId < 1 || !expectedSessionId)) {
-            writeJson(response, 400, { success: false, error: '需要 sessionId 和正安全整数 messageId' });
-            return;
-        }
-        const lease = acquireSessionTree();
-        if (!lease) {
-            unavailable(response);
-            return;
-        }
-        const runtime = lease.tree;
-        try {
-            if (messageAction && !runtime.readBranchMessage) {
-                writeJson(response, 501, { success: false, error: '当前 Agent runtime 不支持读取完整消息' });
-                return;
-            }
-            const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
-            if (messageAction) {
-                if (!sessionId) {
-                    writeJson(response, 404, { success: false, error: '未找到活跃会话' });
-                    return;
-                }
-                if (sessionId !== expectedSessionId) {
-                    writeJson(response, 409, { success: false, error: '会话已变化，请重新读取会话列表' });
-                    return;
-                }
-                const text = await runtime.readBranchMessage(sessionId, messageId);
-                if (text === null) {
-                    writeJson(response, 404, { success: false, error: '未找到此会话的用户消息' });
-                    return;
-                }
-                writeJson(response, 200, { success: true, data: { messageId, text } });
-                return;
-            }
-            if (!sessionId) {
-                if (!isRuntimeImSessionKey(parsed.sessionKey)) {
-                    writeJson(response, 404, {
-                        success: false,
-                        error: `未找到会话：${parsed.sessionKey}`,
-                    });
-                    return;
-                }
-                const knownConversation = await ctx.isKnownConversationSession?.(parsed.sessionKey);
-                if (knownConversation === false) {
-                    writeJson(response, 404, {
-                        success: false,
-                        error: `未找到会话：${parsed.sessionKey}`,
-                    });
-                    return;
-                }
-                // 渠道会话与 Agent 会话的生命周期不同：用户可以先在 Console
-                // 选中一个真实渠道会话，而该会话尚未触发过 Agent。树查询是只读操作，
-                // 因而将这种正常状态返回为可渲染空态，而不是误报资源不存在。
-                writeJson(response, 200, {
-                    success: true,
-                    data: {
-                        state: 'not_started',
-                        sessionKey: parsed.sessionKey,
-                        sessionId: null,
-                        activeLeafMessageId: null,
-                        points: [],
-                    },
-                });
-                return;
-            }
-            const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
-            const points = await runtime.listBranchPoints(sessionId);
-            writeJson(response, 200, {
-                success: true,
-                data: {
-                    state: 'active',
-                    sessionKey: parsed.sessionKey,
-                    sessionId,
-                    activeLeafMessageId,
-                    points,
-                },
-            });
-        }
-        finally {
-            lease.release();
-        }
-    }, { summary: 'Get agent session tree or message', tags: ['console', 'agent'] });
-    route('POST', `${base}/agent/sessions/*`, async (request, response, url, authScope) => {
-        const parsed = parseSessionAction(url.pathname, prefix, 'leaf');
-        if (!parsed) {
-            writeJson(response, 404, { success: false, error: 'Not found' });
-            return;
-        }
-        if (!requireWriteScope(response, ctx, authScope))
-            return;
-        let body;
-        try {
-            body = (await readJsonBody(request) ?? {});
-        }
-        catch (error) {
-            if (error instanceof HttpBodyError) {
-                writeJson(response, error.statusCode, { success: false, error: error.message });
-                return;
-            }
-            throw error;
-        }
-        const messageIdRaw = body.messageId;
-        const indexRaw = body.index;
-        let messageId;
-        let branchIndex;
-        if (messageIdRaw != null && messageIdRaw !== '') {
-            const value = Number(messageIdRaw);
-            if (!Number.isFinite(value) || value < 1) {
-                writeJson(response, 400, { success: false, error: 'messageId 须为正整数' });
-                return;
-            }
-            messageId = value;
-        }
-        else if (indexRaw != null && indexRaw !== '') {
-            const value = Number(indexRaw);
-            if (!Number.isFinite(value) || value < 1) {
-                writeJson(response, 400, { success: false, error: 'index 须为正整数' });
-                return;
-            }
-            branchIndex = value;
-        }
-        else {
-            writeJson(response, 400, { success: false, error: '需要 messageId 或 index 之一' });
-            return;
-        }
-        const lease = acquireSessionTree();
-        if (!lease) {
-            unavailable(response);
-            return;
-        }
-        const runtime = lease.tree;
-        try {
-            const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
-            if (!sessionId) {
-                writeJson(response, 404, {
-                    success: false,
-                    error: `未找到活跃会话：${parsed.sessionKey}`,
-                });
-                return;
-            }
-            if (branchIndex !== undefined) {
-                const result = await runtime.jumpToBranchIndex(sessionId, branchIndex);
-                const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
-                writeJson(response, result.ok ? 200 : 400, {
-                    success: result.ok,
-                    message: result.message,
-                    data: {
-                        sessionKey: parsed.sessionKey,
-                        sessionId,
-                        activeLeafMessageId,
-                    },
-                });
-                return;
-            }
-            const ok = await runtime.switchActiveLeaf(sessionId, messageId);
-            const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
-            writeJson(response, ok ? 200 : 400, {
-                success: ok,
-                message: ok ? `已切换 active leaf 至消息 #${messageId}` : '切换失败',
-                data: {
-                    sessionKey: parsed.sessionKey,
-                    sessionId,
-                    activeLeafMessageId,
-                },
-            });
-        }
-        finally {
-            lease.release();
-        }
-    }, { summary: 'Switch agent session active leaf', tags: ['console', 'agent'] });
-}
-/** Runtime IM session keys are `<platform>:<endpoint>:<scope>:<sceneId>`. */
-function isRuntimeImSessionKey(value) {
-    const first = value.indexOf(':');
-    const second = value.indexOf(':', first + 1);
-    const third = value.indexOf(':', second + 1);
-    return first > 0
-        && second > first + 1
-        && third > second + 1
-        && third < value.length - 1;
-}
-function parseSessionAction(pathname, prefix, action) {
-    if (!pathname.startsWith(prefix))
-        return null;
-    const rest = pathname.slice(prefix.length).replace(/\/+$/u, '');
-    const suffix = `/${action}`;
-    if (!rest.endsWith(suffix))
-        return null;
-    const rawKey = rest.slice(0, -suffix.length);
-    if (!rawKey)
-        return null;
-    return { sessionKey: decodePathParam(rawKey) };
-}
-// ---------------------------------------------------------------------------
-// 内部分页 / 过滤
-// ---------------------------------------------------------------------------
-function paginateItems(all, page, pageSize) {
-    const total = all.length;
-    const totalPages = Math.max(1, Math.ceil(total / pageSize) || 1);
-    const safePage = Math.min(Math.max(1, page), totalPages);
-    const start = (safePage - 1) * pageSize;
-    return {
-        items: all.slice(start, start + pageSize),
-        page: safePage,
-        pageSize,
-        total,
-        totalPages,
-    };
-}
-function filterByFields(items, filter, fields) {
-    if (!filter?.trim())
-        return items;
-    return items.filter((item) => {
-        const blob = fields
-            .map((f) => f(item) ?? '')
-            .join(' ')
-            .toLowerCase();
-        return blob.includes(filter.trim().toLowerCase());
-    });
-}
-function stringProp(value, key) {
-    if (!value || typeof value !== 'object')
-        return undefined;
-    const prop = value[key];
-    return typeof prop === 'string' ? prop : undefined;
-}
-function parsePositiveInt(raw, fallback) {
-    if (raw && /^\d+$/u.test(raw))
-        return Math.max(1, parseInt(raw, 10));
-    return fallback;
-}
-// ---------------------------------------------------------------------------
-// helpers
-// ---------------------------------------------------------------------------
-/** 写操作门禁：demo 部署（ctx.fullScope=false）或 demo token 均 403。 */
-function requireWriteScope(response, ctx, authScope) {
-    if (ctx.fullScope && authScope === 'full')
-        return true;
-    writeJson(response, 403, {
-        success: false,
-        error: 'Demo scope: 只读访问，写操作被拒绝',
-    });
-    return false;
-}
-function decodePathParam(raw) {
-    try {
-        return decodeURIComponent(raw);
-    }
-    catch {
-        return raw;
-    }
-}
-function trimTrailingSlashes(s) {
-    let i = s.length;
-    while (i > 0 && s[i - 1] === '/')
-        i--;
-    return s.slice(0, i);
-}
-function normalizeBase(value) {
-    if (!value.startsWith('/'))
-        return `/${value}`;
-    return trimTrailingSlashes(value) || '/api';
-}
-function writeJson(response, status, body) {
-    const payload = JSON.stringify(body);
-    response.writeHead(status, {
-        'content-type': 'application/json; charset=utf-8',
-        'content-length': Buffer.byteLength(payload),
-    });
-    response.end(payload);
-}

package/lib/console-rpc-handlers.d.ts

@@ -0,0 +1,21 @@
+import { type ConsoleConfigApplicationStatus } from '@zhin.js/console-protocol';
+import type { ConversationAddress, RuntimeConsoleRpcContext, RuntimeConsoleRpcMessage, RuntimeConsoleRpcReply } from './console-rpc.js';
+/** Canonical Console wire fields → runtime conversation address. */
+export declare function wireConversation(channelType: string, channelId: string, parent: unknown): ConversationAddress;
+/**
+ * Structural check for `config:patch-project` operations at the RPC boundary, so no project
+ * port implementation receives a malformed request. The store repeats the full validation.
+ */
+export declare function invalidProjectPatchOperations(patches: readonly unknown[]): string | undefined;
+export declare function dispatchHostResourceConsoleRpc(type: string, message: RuntimeConsoleRpcMessage, ctx: RuntimeConsoleRpcContext, requestId: number | string | undefined, payloads: RuntimeConsoleRpcReply[]): Promise<boolean>;
+export declare function stringField(message: RuntimeConsoleRpcMessage, key: string): string;
+export declare function recordField(value: unknown): Record<string, unknown> | undefined;
+export declare function positiveInteger(value: unknown, fallback: number): number;
+export declare function errorMessage(error: unknown): string;
+export declare function errorReply(payloads: RuntimeConsoleRpcReply[], requestId: number | string | undefined, error: string): RuntimeConsoleRpcReply[];
+/** HTTP paths under apiBase that demo scope may call (ADR 0016). */
+export declare function isDemoHttpAllowed(method: string, pathname: string, apiBase: string): boolean;
+export declare function configurationSaveMessage(result: {
+    restartRequired: boolean;
+    revision?: string;
+} & ConsoleConfigApplicationStatus): string;