@sovovs/bycli 1.8.0 → 2.0.0

package/dist/src/recorder/http/handlers.d.ts

@@ -0,0 +1,51 @@
+import { type ErrorCode } from './wrapper-envelope.js';
+import type { WrapperRegistry } from './wrapper-registry.js';
+import { type createAdapterDraft } from '../highlevel/init.js';
+import type { RunnerPortWithLifecycle } from '../runner/runner-port.js';
+import type { AnalyzeRunner } from './analyze-runner.js';
+export interface HandlerOutcome {
+    status: number;
+    body: unknown;
+    /** 供 finish-logger / metrics 打标(非 2xx 时设)。 */
+    errorCode?: ErrorCode;
+}
+/** handler 依赖(可注入,测试用)。 */
+export interface HandlerCtx {
+    registry: WrapperRegistry;
+    createDraft: typeof createAdapterDraft;
+    /** verify 委托的 runner(production=defaultRunnerPort();测试注入 fake);用于 startVerify + getRunStatus。 */
+    runner: RunnerPortWithLifecycle;
+    /** sessionId → per-session HMAC key(M7a;缺 session 用进程 fallback)。可注入,默认进程级 registry。 */
+    sessionKeyFor?: (sessionId?: string) => string;
+    /** analyze 委托(production=daemon-backed Page;测试注入 fake)。 */
+    analyzeRunner: AnalyzeRunner;
+    /** 在飞后台作业集合(analyze 的 in-process Page 工作);shutdown 时 drain 它们好让 finally closeWindow
+     * 释放 daemon Page lease,而不是被 process.exit 硬切(Codex M9 Med)。createWrapperApp 注入。 */
+    inflight?: Set<Promise<unknown>>;
+}
+/** GET /health —— 门禁已由 router 施加,此处只报存活。 */
+export declare function handleHealth(): HandlerOutcome;
+/**
+ * POST /v1/adapters/init —— 铸 requestId → createRequest → createAdapterDraft(同步)→ finalize →
+ * 202 AcceptedResponse。name 缺失/非法 → finalize failed(validation_failed),仍 202(错误经 status 查)。
+ */
+export declare function handleInit(ctx: HandlerCtx, body: Record<string, unknown>): HandlerOutcome;
+/**
+ * POST /v1/browser/analyze —— 校验 url/session/contextId → 铸 requestId → createRequest → **立即 202** →
+ * 后台 `runAnalyzeBackground`(构造 daemon-backed Page 跑 analyze,M6b 模式)。analyze 无 seed;结果是
+ * 站点分类 AnalyzeReport。daemon 不可达 → daemon_unavailable(503),超时 → analyze_timeout(504,status timeout)。
+ */
+export declare function handleAnalyze(ctx: HandlerCtx, body: Record<string, unknown>): HandlerOutcome;
+/**
+ * POST /v1/adapters/verify —— 铸 requestId(== runner canonical id)→ createRequest → 委托
+ * verifyAdapter(name 校验 → 派生 evidence HMAC → runner.startVerify)。runner 接受即留 running(202,
+ * 客户端轮询 GET status 拿 runner live 进度);startVerify 同步拒(validation_failed/queue_full/
+ * runner_protocol_error)→ finalize failed,仍 202。**raw executionSeedArgs 只进 runner input.json,
+ * 绝不进 registry/202/log**(verifyAdapter 内部经 input.json 0600 落盘,wrapper 这层不碰 raw)。
+ */
+export declare function handleVerify(ctx: HandlerCtx, body: Record<string, unknown>): Promise<HandlerOutcome>;
+/**
+ * GET /v1/requests/{requestId}(+waitMs long-poll)—— 未知/TTL 过期 → 404 request_not_found;否则
+ * 200 RequestStatus。verify 类经 runner getRunStatus 代理 live 进度并在终态 finalize summary。
+ */
+export declare function handleRequestStatus(ctx: HandlerCtx, requestId: string, waitMs: number): Promise<HandlerOutcome>;

package/dist/src/recorder/http/handlers.js

@@ -0,0 +1,219 @@
+// M9 High-Level HTTP wrapper —— 端点 handler。返回纯 HandlerOutcome(status/body/errorCode),由
+// wrapper-server 写入 res —— handler 不碰 res,便于单测直接断言。M9a 只含 init/status/health;
+// verify(M9b)/analyze(M9c)随后加。统一 202 语义:init 同步跑完后立刻 finalize,仍返 202 + requestId,
+// 失败经 GET /v1/requests/{id} 查(high-level.openapi 的 POST 只定义 202)。
+import { accepted, errorBody, newRequestId, } from './wrapper-envelope.js';
+import { verifyAdapter } from '../highlevel/verify.js';
+import { defaultSessionKeyRegistry } from '../runner/session-keys.js';
+const TERMINAL = new Set(['succeeded', 'failed', 'timeout', 'cancelled']);
+const RUN_TERMINAL = new Set(['succeeded', 'failed', 'timeout', 'cancelled']);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** GET /health —— 门禁已由 router 施加,此处只报存活。 */
+export function handleHealth() {
+    return { status: 200, body: { status: 'ok', schemaVersion: 'high-level.v1' } };
+}
+/**
+ * POST /v1/adapters/init —— 铸 requestId → createRequest → createAdapterDraft(同步)→ finalize →
+ * 202 AcceptedResponse。name 缺失/非法 → finalize failed(validation_failed),仍 202(错误经 status 查)。
+ */
+export function handleInit(ctx, body) {
+    const requestId = newRequestId();
+    ctx.registry.createRequest({ requestId, type: 'init' });
+    const name = body.name;
+    if (typeof name !== 'string' || name.length === 0) {
+        ctx.registry.finalizeRequest(requestId, {
+            status: 'failed',
+            error: errorBody('validation_failed', 'name is required (site/command)'),
+        });
+        return { status: 202, body: accepted(requestId) };
+    }
+    const strategyRaw = body.strategy;
+    const strategy = strategyRaw === 'PUBLIC' || strategyRaw === 'COOKIE' || strategyRaw === 'UI' ? strategyRaw : undefined;
+    const writePolicyRaw = body.writePolicy;
+    const writePolicy = writePolicyRaw === 'write' || writePolicyRaw === 'dry-run' ? writePolicyRaw : undefined;
+    const input = {
+        name,
+        domain: typeof body.domain === 'string' ? body.domain : undefined,
+        strategy,
+        browser: typeof body.browser === 'boolean' ? body.browser : undefined,
+        writePolicy,
+        responsibleUseAcknowledgedAt: typeof body.responsibleUseAcknowledgedAt === 'number' ? body.responsibleUseAcknowledgedAt : undefined,
+    };
+    const result = ctx.createDraft(input);
+    if (result.ok) {
+        ctx.registry.finalizeRequest(requestId, {
+            status: 'succeeded',
+            result: { report: result.report, dryRun: result.dryRun },
+        });
+    }
+    else {
+        ctx.registry.finalizeRequest(requestId, {
+            status: 'failed',
+            error: errorBody(result.errorCode, result.reason),
+        });
+    }
+    return { status: 202, body: accepted(requestId) };
+}
+/** analyze 后台 worker:跑 daemon-backed analyzeRunner → finalize report;映射 timeout/daemon-unavailable。 */
+async function runAnalyzeBackground(ctx, requestId, input) {
+    try {
+        const report = await ctx.analyzeRunner(input);
+        ctx.registry.finalizeRequest(requestId, { status: 'succeeded', result: report });
+    }
+    catch (e) {
+        const code = e?.code;
+        const msg = e instanceof Error ? e.message : String(e);
+        let errorCode;
+        let status;
+        if (code === 'analyze_timeout') {
+            errorCode = 'analyze_timeout';
+            status = 'timeout';
+        }
+        else if (code === 'daemon_unavailable' ||
+            // 只认**连接级**失败签名(Codex M9 Med:原宽匹配 connect/network error/daemon 会把普通运行时/
+            // 站点异常误报 503)。daemon-client 连不上时 undici 抛 "fetch failed"、重试耗尽抛 "max retries
+            // exhausted"、底层 ECONNREFUSED/ECONNRESET —— 这些才是 daemon 不可达,其余归 adapter_runtime_error。
+            /ECONNREFUSED|ECONNRESET|fetch failed|max retries exhausted/i.test(msg)) {
+            errorCode = 'daemon_unavailable';
+            status = 'failed';
+        }
+        else {
+            errorCode = 'adapter_runtime_error';
+            status = 'failed';
+        }
+        ctx.registry.finalizeRequest(requestId, { status, error: errorBody(errorCode, msg) });
+    }
+}
+/**
+ * POST /v1/browser/analyze —— 校验 url/session/contextId → 铸 requestId → createRequest → **立即 202** →
+ * 后台 `runAnalyzeBackground`(构造 daemon-backed Page 跑 analyze,M6b 模式)。analyze 无 seed;结果是
+ * 站点分类 AnalyzeReport。daemon 不可达 → daemon_unavailable(503),超时 → analyze_timeout(504,status timeout)。
+ */
+export function handleAnalyze(ctx, body) {
+    const requestId = newRequestId();
+    ctx.registry.createRequest({ requestId, type: 'analyze' });
+    const url = body.url;
+    const session = body.session;
+    const contextId = body.contextId;
+    if (typeof url !== 'string' || url.length === 0 ||
+        typeof session !== 'string' || session.length === 0 ||
+        typeof contextId !== 'string' || contextId.length === 0) {
+        ctx.registry.finalizeRequest(requestId, {
+            status: 'failed',
+            error: errorBody('validation_failed', 'url, session and contextId are required'),
+        });
+        return { status: 202, body: accepted(requestId) };
+    }
+    const settleMs = typeof body.settleMs === 'number' ? body.settleMs : undefined;
+    // fire-and-forget;客户端轮询 GET /v1/requests/{id}(analyze 类无 runner,registry 是唯一权威)。
+    // 登记进 inflight 供 shutdown drain(release Page lease);runAnalyzeBackground 永不 reject。
+    const job = runAnalyzeBackground(ctx, requestId, { url, session, contextId, settleMs });
+    if (ctx.inflight) {
+        ctx.inflight.add(job);
+        void job.finally(() => ctx.inflight.delete(job));
+    }
+    return { status: 202, body: accepted(requestId) };
+}
+/**
+ * POST /v1/adapters/verify —— 铸 requestId(== runner canonical id)→ createRequest → 委托
+ * verifyAdapter(name 校验 → 派生 evidence HMAC → runner.startVerify)。runner 接受即留 running(202,
+ * 客户端轮询 GET status 拿 runner live 进度);startVerify 同步拒(validation_failed/queue_full/
+ * runner_protocol_error)→ finalize failed,仍 202。**raw executionSeedArgs 只进 runner input.json,
+ * 绝不进 registry/202/log**(verifyAdapter 内部经 input.json 0600 落盘,wrapper 这层不碰 raw)。
+ */
+export async function handleVerify(ctx, body) {
+    const requestId = newRequestId();
+    ctx.registry.createRequest({ requestId, type: 'verify', runnerId: requestId });
+    const name = body.name;
+    if (typeof name !== 'string' || name.length === 0) {
+        ctx.registry.finalizeRequest(requestId, {
+            status: 'failed',
+            error: errorBody('validation_failed', 'name is required (site/command)'),
+        });
+        return { status: 202, body: accepted(requestId) };
+    }
+    const sessionId = typeof body.sessionId === 'string' ? body.sessionId : undefined;
+    const keyFor = ctx.sessionKeyFor ?? ((sid) => defaultSessionKeyRegistry().keyFor(sid));
+    const sessionHmacKey = keyFor(sessionId);
+    const fixtureRaw = body.fixture;
+    const fixture = fixtureRaw === 'ignore' || fixtureRaw === 'match' || fixtureRaw === 'update' ? fixtureRaw : undefined;
+    const traceRaw = body.trace;
+    const trace = traceRaw === 'off' || traceRaw === 'retain-on-failure' || traceRaw === 'always' ? traceRaw : undefined;
+    const executionSeedArgs = body.executionSeedArgs && typeof body.executionSeedArgs === 'object' && !Array.isArray(body.executionSeedArgs)
+        ? body.executionSeedArgs
+        : undefined;
+    const input = { name, requestId, sessionId, executionSeedArgs, fixture, trace };
+    const result = await verifyAdapter(input, sessionHmacKey, ctx.runner);
+    if (!result.ok) {
+        ctx.registry.finalizeRequest(requestId, { status: 'failed', error: errorBody(result.errorCode, result.reason) });
+        return { status: 202, body: accepted(requestId) };
+    }
+    // ok:true → 后台收尾:runner settle 时 finalize registry,**与客户端是否轮询无关**(否则 abandoned
+    // verify 永远卡 running〔expiresAt=null〕→ 永不被 sweep → 泄漏)。finalizeRequest 幂等,与轮询 refresh()
+    // 双触发安全;whenSettled resolve/reject 都收尾(用 getRunStatus 取终态;null/non-terminal 则 idle 兜底)。
+    const settled = ctx.runner.whenSettled(requestId);
+    if (settled)
+        void settled.then(() => finalizeVerifyFromRunner(ctx, requestId), () => finalizeVerifyFromRunner(ctx, requestId));
+    return { status: 202, body: accepted(requestId) };
+}
+/** 从 runner 当前态收尾一个 verify 记录(终态 → finalize summary-only;非终态 → updateRequest)。幂等。 */
+function finalizeVerifyFromRunner(ctx, requestId) {
+    const live = ctx.runner.getRunStatus(requestId);
+    if (!live)
+        return;
+    if (RUN_TERMINAL.has(live.status)) {
+        // 把 runner 终态错误(VerifySummary.error,如 verify_timeout/adapter_runtime_error)投影到顶层
+        // RequestStatus.error,使 verify 失败与 init/analyze 同一读取出口(Codex M9 Med);summary 仍保留完整体。
+        const e = live.summary?.error;
+        ctx.registry.finalizeRequest(requestId, {
+            status: live.status,
+            result: live.summary ?? undefined,
+            error: e ? errorBody(e.code, e.message, e.hint) : undefined,
+        });
+    }
+    else {
+        ctx.registry.updateRequest(requestId, { status: live.status });
+    }
+}
+/**
+ * 把 verify 记录从 runner 拉取 live status 投影进 registry(终态 finalize summary,summary-only 已脱敏)。
+ * init/analyze 类不动(它们的终态由各自 handler finalize)。返回最新投影后的 RequestStatus。
+ */
+function refresh(ctx, requestId) {
+    const r = ctx.registry.getRecord(requestId);
+    if (r && r.type === 'verify' && !TERMINAL.has(r.status)) {
+        const live = ctx.runner.getRunStatus(r.runnerId);
+        if (live) {
+            if (RUN_TERMINAL.has(live.status)) {
+                ctx.registry.finalizeRequest(requestId, {
+                    status: live.status,
+                    result: live.summary ?? undefined,
+                });
+            }
+            else {
+                ctx.registry.updateRequest(requestId, { status: live.status });
+            }
+        }
+    }
+    return ctx.registry.getRequest(requestId);
+}
+/**
+ * GET /v1/requests/{requestId}(+waitMs long-poll)—— 未知/TTL 过期 → 404 request_not_found;否则
+ * 200 RequestStatus。verify 类经 runner getRunStatus 代理 live 进度并在终态 finalize summary。
+ */
+export async function handleRequestStatus(ctx, requestId, waitMs) {
+    const deadline = Date.now() + waitMs;
+    let rec = refresh(ctx, requestId);
+    while (rec && !TERMINAL.has(rec.status) && Date.now() < deadline) {
+        await sleep(Math.min(200, Math.max(0, deadline - Date.now())));
+        rec = refresh(ctx, requestId);
+    }
+    if (!rec) {
+        return {
+            status: 404,
+            body: { error: errorBody('request_not_found', 'no such request (unknown or expired)') },
+            errorCode: 'request_not_found',
+        };
+    }
+    return { status: 200, body: rec };
+}

package/dist/src/recorder/http/wrapper-config.d.ts

@@ -0,0 +1,20 @@
+export interface WrapperConfig {
+    readonly HOST: '127.0.0.1';
+    readonly PORT: number;
+    readonly ALLOWED_ORIGINS: readonly string[];
+    readonly TOKEN: string;
+    readonly DAEMON_PORT: number;
+    readonly LOG_LEVEL: 'error' | 'warn' | 'info' | 'debug';
+    /** 终态 RequestStatus TTL(过期 → getRequest 返 undefined → 404)。 */
+    readonly REQUEST_TERMINAL_STATUS_TTL_MS: number;
+    /** RequestStatus.pollAfterMs 提示。 */
+    readonly REQUEST_POLL_AFTER_MS: number;
+    /** GET /v1/requests long-poll waitMs 上限(server 侧 clamp,防客户端长挂连接)。 */
+    readonly REQUEST_WAIT_MS_MAX: number;
+    /** 请求体上限(超 → validation_failed)。 */
+    readonly BODY_LIMIT_BYTES: number;
+    /** analyze 整体超时(analyzeBrowserWithTimeout → analyze_timeout)。 */
+    readonly ANALYZE_TIMEOUT_MS: number;
+}
+/** load + validate;失败抛 ConfigError(config_invalid,fail-closed)。token 缺省时生成。 */
+export declare function loadWrapperConfig(env?: NodeJS.ProcessEnv): WrapperConfig;

package/dist/src/recorder/http/wrapper-config.js

@@ -0,0 +1,82 @@
+// M9 High-Level HTTP wrapper —— 配置(09 章 RecorderConfig 子集 + 04 章 loopback HTTP shape)。
+// 形态对齐主仓既有手写 env 校验(src/recorder/runner/config.ts resolveTempPolicy 的 {key,def,min,max}
+// 表 + fail-closed ConfigError;主仓无 zod,故不用 dashboard-be 的 zod loadConfig)。差异:① 独立 env
+// 命名空间 BYCLI_HIGHLEVEL_*(不复用 be 的 RECORDER_*,避免 wrapper 与 be 同机并跑抢同名 env);
+// ② PORT 默认 19827(避开 daemon 19825 / be 19826);③ 无 UI_DIST / scoring profile / feature flags
+// (wrapper 纯 API、不托管 UI);④ HOST 锁死 127.0.0.1(非 loopback override 直接 fail-closed)。
+import { randomToken } from '@sovovs/bycli-recorder-core';
+import { ConfigError } from '../../errors.js';
+const INT_FIELDS = {
+    PORT: { key: 'BYCLI_HIGHLEVEL_PORT', def: 19_827, min: 1024, max: 65_535 },
+    DAEMON_PORT: { key: 'BYCLI_DAEMON_PORT', def: 19_825, min: 1024, max: 65_535 },
+    REQUEST_TERMINAL_STATUS_TTL_MS: { key: 'BYCLI_HIGHLEVEL_REQUEST_TTL_MS', def: 1_800_000, min: 60_000, max: 86_400_000 },
+    REQUEST_POLL_AFTER_MS: { key: 'BYCLI_HIGHLEVEL_POLL_AFTER_MS', def: 1_000, min: 250, max: 10_000 },
+    REQUEST_WAIT_MS_MAX: { key: 'BYCLI_HIGHLEVEL_WAIT_MS_MAX', def: 25_000, min: 1_000, max: 60_000 },
+    BODY_LIMIT_BYTES: { key: 'BYCLI_HIGHLEVEL_BODY_LIMIT_BYTES', def: 262_144, min: 1024, max: 4_194_304 },
+    ANALYZE_TIMEOUT_MS: { key: 'BYCLI_HIGHLEVEL_ANALYZE_TIMEOUT_MS', def: 30_000, min: 1_000, max: 600_000 },
+};
+const LOG_LEVELS = ['error', 'warn', 'info', 'debug'];
+function intFromEnv(env, f) {
+    const raw = env[f.key];
+    if (raw === undefined || raw === '')
+        return f.def;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < f.min || n > f.max) {
+        throw new ConfigError(`config_invalid: ${f.key}=${raw} is out of range [${f.min}, ${f.max}]`, `Fix the ${f.key} environment variable and retry.`);
+    }
+    return n;
+}
+/** load + validate;失败抛 ConfigError(config_invalid,fail-closed)。token 缺省时生成。 */
+export function loadWrapperConfig(env = process.env) {
+    // HOST loopback-only:任何非 127.0.0.1 override 直接拒(不可绕过 loopback 绑定)。
+    const host = env.BYCLI_HIGHLEVEL_HOST;
+    if (host !== undefined && host !== '' && host !== '127.0.0.1') {
+        throw new ConfigError(`config_invalid: BYCLI_HIGHLEVEL_HOST=${host} not allowed (loopback-only)`, 'Unset BYCLI_HIGHLEVEL_HOST or set it to 127.0.0.1.');
+    }
+    const ints = {};
+    for (const k of Object.keys(INT_FIELDS)) {
+        ints[k] = intFromEnv(env, INT_FIELDS[k]);
+    }
+    // Origin allowlist:逗号分隔,逐个校验是合法 URL。默认空 —— 程序客户端不发 Origin 即放行;
+    // 浏览器发非白名单 Origin 则被门禁拒。
+    const rawOrigins = env.BYCLI_HIGHLEVEL_ALLOWED_ORIGINS;
+    const origins = typeof rawOrigins === 'string' && rawOrigins.length
+        ? rawOrigins.split(',').map((s) => s.trim()).filter(Boolean)
+        : [];
+    for (const o of origins) {
+        try {
+            new URL(o);
+        }
+        catch {
+            throw new ConfigError(`config_invalid: invalid origin "${o}" in BYCLI_HIGHLEVEL_ALLOWED_ORIGINS`, 'Provide comma-separated absolute URLs (e.g. http://127.0.0.1:8000).');
+        }
+    }
+    // TOKEN:显式给则 ≥16 字符,否则进程内生成(04 章 startup random,重启轮换)。
+    const rawToken = env.BYCLI_HIGHLEVEL_TOKEN;
+    if (rawToken !== undefined && rawToken !== '' && rawToken.length < 16) {
+        throw new ConfigError('config_invalid: BYCLI_HIGHLEVEL_TOKEN too short (min 16 chars)', 'Use a token of at least 16 chars, or unset to auto-generate.');
+    }
+    const token = rawToken && rawToken.length >= 16 ? rawToken : randomToken();
+    // LOG_LEVEL:非法值 fail-closed。
+    const rawLevel = env.LOG_LEVEL;
+    let level = 'info';
+    if (rawLevel !== undefined && rawLevel !== '') {
+        if (!LOG_LEVELS.includes(rawLevel)) {
+            throw new ConfigError(`config_invalid: LOG_LEVEL=${rawLevel} not in [${LOG_LEVELS.join(', ')}]`, 'Set LOG_LEVEL to one of error|warn|info|debug.');
+        }
+        level = rawLevel;
+    }
+    return Object.freeze({
+        HOST: '127.0.0.1',
+        PORT: ints.PORT,
+        ALLOWED_ORIGINS: Object.freeze(origins),
+        TOKEN: token,
+        DAEMON_PORT: ints.DAEMON_PORT,
+        LOG_LEVEL: level,
+        REQUEST_TERMINAL_STATUS_TTL_MS: ints.REQUEST_TERMINAL_STATUS_TTL_MS,
+        REQUEST_POLL_AFTER_MS: ints.REQUEST_POLL_AFTER_MS,
+        REQUEST_WAIT_MS_MAX: ints.REQUEST_WAIT_MS_MAX,
+        BODY_LIMIT_BYTES: ints.BODY_LIMIT_BYTES,
+        ANALYZE_TIMEOUT_MS: ints.ANALYZE_TIMEOUT_MS,
+    });
+}

package/dist/src/recorder/http/wrapper-envelope.d.ts

@@ -0,0 +1,31 @@
+import type { ErrorCode, RecorderError } from '@sovovs/bycli-recorder-core';
+export type { ErrorCode, RecorderError };
+/** RequestStatus.type(high-level.openapi.yaml:188-190)。 */
+export type RequestType = 'analyze' | 'init' | 'verify';
+/** RequestStatus.status(high-level.openapi.yaml:191-193);与 runner-port RunStatus 一致。 */
+export type RequestStatusValue = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'cancelled';
+/** 202 AcceptedResponse(high-level.openapi.yaml:97-109)。 */
+export interface AcceptedResponse {
+    requestId: string;
+    schemaVersion: 'high-level.v1';
+    error: RecorderError | null;
+}
+/** 200 RequestStatus(high-level.openapi.yaml:182-216)。 */
+export interface RequestStatus {
+    requestId: string;
+    type: RequestType;
+    status: RequestStatusValue;
+    startedAt: number;
+    updatedAt: number;
+    expiresAt: number | null;
+    pollAfterMs: number | null;
+    queueReason: 'profile_busy' | 'queue_full' | null;
+    progress: unknown;
+    result: unknown;
+    error: RecorderError | null;
+}
+/** 请求 id:req_<16hex>(传输层细节,与 be newRequestId 对齐格式)。 */
+export declare const newRequestId: () => string;
+export declare const accepted: (requestId: string, error?: RecorderError | null) => AcceptedResponse;
+export declare const httpStatusForHighLevel: (code: ErrorCode) => number;
+export declare const errorBody: (code: ErrorCode, message: string, hint?: string) => RecorderError;

package/dist/src/recorder/http/wrapper-envelope.js

@@ -0,0 +1,51 @@
+// M9 High-Level HTTP wrapper —— 响应封装(high-level.openapi.yaml:97-216)。
+// AcceptedResponse(202)/ RequestStatus(200)wire 形状 + ErrorCode→HTTP status 映射。
+// ErrorCode/RecorderError 从 @sovovs/bycli-recorder-core 取(单一 TS 镜像源,Q2 改良 A);
+// **STATUS_BY_CODE 是传输关注点,故意留在本传输层、不进 recorder-core**(与 be envelope 各持一份,
+// 值同步自 03 章 Error Mapping 表)。schemaVersion 字面量 'high-level.v1'(与 be 的 'recorder.v1' 不同)。
+import { randomUUID } from 'node:crypto';
+/** 请求 id:req_<16hex>(传输层细节,与 be newRequestId 对齐格式)。 */
+export const newRequestId = () => `req_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+export const accepted = (requestId, error = null) => ({
+    requestId,
+    schemaVersion: 'high-level.v1',
+    error,
+});
+// 03 章 Error Mapping:ErrorCode → HTTP status。未列出兜底 500。**传输关注点,故意留本层(不进 core)**。
+// `Record<ErrorCode, number>` 保证新增 code 时编译期 exhaustiveness 压力。⚠️ 值的唯一权威 = 03 章 Error
+// Mapping 表;本表必须与 dashboard-be/src/transport/envelope.ts 的 STATUS_BY_CODE **保持值一致**(两份
+// 各自传输层持有,边界正确但值会 drift;改一处必同步另一处 + 见 wrapper.test.ts 的关键码钉值测试)。
+const STATUS_BY_CODE = {
+    validation_failed: 400,
+    invalid_state: 400,
+    insufficient_samples: 400,
+    navigation_url_forbidden: 400,
+    navigation_redirect_requires_interception: 400,
+    dns_resolution_failed: 400,
+    page_lost: 400,
+    csrf_failed: 403,
+    auth_failed: 403,
+    feature_disabled: 403,
+    auth_required: 500,
+    responsible_use_required: 400,
+    ambiguous_iframe_target: 400,
+    request_not_found: 404,
+    idempotency_conflict: 409,
+    queue_full: 429,
+    profile_busy: 429,
+    daemon_unavailable: 503,
+    extension_disconnected: 503,
+    network_error: 503,
+    verify_timeout: 504,
+    pipeline_timeout: 504,
+    analyze_timeout: 504,
+    runner_protocol_error: 500,
+    adapter_runtime_error: 500,
+    shape_mismatch: 500,
+    fixture_mismatch: 500,
+    output_truncated: 500,
+    temp_store_full: 507,
+    config_invalid: 500,
+};
+export const httpStatusForHighLevel = (code) => STATUS_BY_CODE[code] ?? 500;
+export const errorBody = (code, message, hint) => hint ? { code, message, hint } : { code, message };

package/dist/src/recorder/http/wrapper-gates.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage } from 'node:http';
+export interface WrapperGateResult {
+    ok: boolean;
+    /** 仅 auth_failed(门禁层不区分细分原因,避免给攻击者反馈)。 */
+    code?: 'auth_failed';
+    message?: string;
+}
+export interface WrapperGateConfig {
+    allowedOrigins: readonly string[];
+    token: string;
+}
+/**
+ * 门禁校验链(顺序:header → origin → token)。比 daemon /v1/*(仅 X-byCLI presence)强一档 —— 多了
+ * 启动随机 token secret 这层。所有端点(含 /health)统一过此链(无契约理由豁免 health)。
+ */
+export declare function checkWrapperGates(req: IncomingMessage, cfg: WrapperGateConfig): WrapperGateResult;

package/dist/src/recorder/http/wrapper-gates.js

@@ -0,0 +1,28 @@
+import { safeEqual } from '@sovovs/bycli-recorder-core';
+const PASS = { ok: true };
+/** 读单个 header(数组取首项)。 */
+function header(req, name) {
+    const v = req.headers[name.toLowerCase()];
+    return Array.isArray(v) ? v[0] : v;
+}
+/**
+ * 门禁校验链(顺序:header → origin → token)。比 daemon /v1/*(仅 X-byCLI presence)强一档 —— 多了
+ * 启动随机 token secret 这层。所有端点(含 /health)统一过此链(无契约理由豁免 health)。
+ */
+export function checkWrapperGates(req, cfg) {
+    // 1) 自定义 header gate —— 浏览器跨站无法伪造自定义 header(07 · X-byCLI:1)
+    if (header(req, 'X-byCLI') !== '1') {
+        return { ok: false, code: 'auth_failed', message: 'missing X-byCLI header' };
+    }
+    // 2) Origin allowlist —— 程序客户端不发 Origin 即放行;浏览器发非白名单 Origin 则拒
+    const origin = header(req, 'Origin');
+    if (origin !== undefined && !cfg.allowedOrigins.includes(origin)) {
+        return { ok: false, code: 'auth_failed', message: 'origin not allowed' };
+    }
+    // 3) 启动随机 token secret(X-byCLI-Token,恒定时间比较)
+    const token = header(req, 'X-byCLI-Token');
+    if (!token || !safeEqual(token, cfg.token)) {
+        return { ok: false, code: 'auth_failed', message: 'invalid token' };
+    }
+    return PASS;
+}

package/dist/src/recorder/http/wrapper-metrics.d.ts

@@ -0,0 +1 @@
+export { createMetrics, type Metrics, type MetricsSnapshot, type HistogramStat, } from '@sovovs/bycli-recorder-core';

package/dist/src/recorder/http/wrapper-metrics.js

@@ -0,0 +1,5 @@
+// M9 High-Level HTTP wrapper —— 进程内 metrics(09 Metrics)。实现已抽进 recorder-core(#3,Q2 改良A
+// 原则下:纯内存计数器、零 IO/HTTP,合 charter,与 transport-crypto 同构)——这里 re-export,消除原
+// copy-port 自 dashboard-be 的副本 drift(be 同样 re-export 同一源)。GET /metrics scrape 端点(绑 http
+// 类型)仍留 wrapper 传输层(wrapper-server.ts),不进 core。
+export { createMetrics, } from '@sovovs/bycli-recorder-core';

package/dist/src/recorder/http/wrapper-registry.d.ts

@@ -0,0 +1,50 @@
+import type { RequestType, RequestStatusValue, RequestStatus, RecorderError } from './wrapper-envelope.js';
+/** 内部记录:RequestStatus + wrapper-only 字段(投影掉再返给客户端)。 */
+interface WrapperRequestRecord extends RequestStatus {
+    /** 查询 daemon runner 用的 canonical id(== requestId;保留以解耦 wrapper↔runner id)。 */
+    runnerId: string;
+}
+export interface WrapperRegistryOptions {
+    /** 终态 RequestStatus TTL(过期 → getRequest 返 undefined)。 */
+    terminalTtlMs: number;
+    /** RequestStatus.pollAfterMs 默认提示。 */
+    pollAfterMs: number;
+    /** 可注入时钟(测试 TTL 用,仿 session-keys.ts)。 */
+    now?: () => number;
+}
+export declare class WrapperRegistry {
+    private readonly opts;
+    private requests;
+    private readonly now;
+    constructor(opts: WrapperRegistryOptions);
+    /** 铸一条 in-flight 记录。init 同步跑完会立刻 finalize;verify/analyze 留 running 待轮询/后台收尾。 */
+    createRequest(input: {
+        requestId: string;
+        type: RequestType;
+        runnerId?: string;
+        status?: RequestStatusValue;
+    }): RequestStatus;
+    /** 合并一条非终态 status/result/error/queueReason 更新;终态记录不可变。 */
+    updateRequest(requestId: string, patch: {
+        status?: RequestStatusValue;
+        result?: unknown;
+        error?: RecorderError;
+        queueReason?: 'profile_busy' | 'queue_full' | null;
+    }): void;
+    /** 置终态 + 武装 TTL(终态过期 → getRequest 返 undefined → 404)。已终态则幂等 no-op。 */
+    finalizeRequest(requestId: string, patch: {
+        status: 'succeeded' | 'failed' | 'timeout' | 'cancelled';
+        result?: unknown;
+        error?: RecorderError;
+    }): void;
+    /** 面向客户端的 RequestStatus(TTL 校验,wrapper-only 字段投影掉)。 */
+    getRequest(id: string): RequestStatus | undefined;
+    /** 内部记录(含 runnerId;handler 用,不返客户端)。TTL 过期即删并返 undefined。 */
+    getRecord(id: string): WrapperRequestRecord | undefined;
+    /**
+     * 周期清理:删除所有已过 TTL 的终态记录(getRecord 只在"被访问"时删,abandoned 的终态记录否则常驻
+     * 内存)。non-terminal 记录 expiresAt=null,绝不被清。返回清理条数。
+     */
+    sweepExpired(): number;
+}
+export {};