@sovovs/bycli 1.8.0 → 2.1.0

package/dist/src/recorder/highlevel/init.js

@@ -0,0 +1,279 @@
+/**
+ * High-Level init module (M5b · createAdapterDraft, 07-high-level-services.md).
+ *
+ * Hosted main-repo side (Codex A' verdict): FS writes live here, not in dashboard-be.
+ * Uses the PURE pieces from @sovovs/bycli-recorder-core (validate/render/provenance/
+ * dry-run); this module adds the IO: overwrite/shadow check, write to disk, commit
+ * marker, config-snapshot injection.
+ *
+ * SCOPE (甲 / phase-1): writes report + adapter with an embedded provenance header
+ * and a commit marker, so a visible adapter always carries provenance (07 forbids an
+ * un-provenanced adapter). The FULL multi-file atomic write transaction (txn manifest
+ * + fsync + atomic rename) and the crash-recovery table (07:97-104) are deferred —
+ * tracked as M5b follow-up. Until then writes are direct (non-atomic), which is
+ * acceptable for a single-user local tool with the provenance+marker guard.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getUserClisDir, getSitesDir, getSiteRecorderDir } from '../../config-paths.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { validateAdapterName, renderAdapterTemplate, buildProvenanceHeader, computeDryRunDiff, decideInitRecovery, } from '@sovovs/bycli-recorder-core';
+const DEFAULT_SNAPSHOT = {
+    releaseChannel: 'stable', localExperimentProfile: 'off', configSnapshotVersion: 1,
+};
+function clisDir(site) {
+    return path.join(getUserClisDir(), site);
+}
+function sha256(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+/** fsync a directory so a contained rename/create is durable. Best-effort: some platforms
+ * (notably Windows) reject opening a directory for fsync. */
+function fsyncDir(dir) {
+    let dfd;
+    try {
+        dfd = fs.openSync(dir, 'r');
+        fs.fsyncSync(dfd);
+    }
+    catch { /* directory fsync unsupported on this platform */ }
+    finally {
+        if (dfd !== undefined)
+            fs.closeSync(dfd);
+    }
+}
+/** Atomic file write (07:101-103): write to a sibling temp, fsync the fd, rename onto the
+ * final path, then fsync the parent dir so the rename itself is durable. 0600 (owner-only). */
+function atomicWrite(finalPath, content) {
+    const dir = path.dirname(finalPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(finalPath)}.${randomUUID()}.tmp`);
+    const fd = fs.openSync(tmp, 'wx', 0o600); // exclusive create
+    try {
+        fs.writeSync(fd, content);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, finalPath);
+    fsyncDir(dir);
+}
+function writeManifest(manifestPath, manifest) {
+    atomicWrite(manifestPath, JSON.stringify(manifest));
+}
+/**
+ * Create an adapter draft. With writePolicy 'dry-run' (default) nothing is written —
+ * only the diff + intended report is returned. With 'write' it requires
+ * responsibleUseAcknowledgedAt (ADR-0005) and writes report + adapter to disk.
+ */
+export function createAdapterDraft(input, snapshot = DEFAULT_SNAPSHOT) {
+    const v = validateAdapterName(input.name);
+    if (!v.ok)
+        return { ok: false, errorCode: 'validation_failed', reason: v.reason };
+    const { site, command } = v.parts;
+    const writePolicy = input.writePolicy ?? 'dry-run';
+    if (writePolicy === 'write' && !input.responsibleUseAcknowledgedAt) {
+        return { ok: false, errorCode: 'responsible_use_required', reason: 'responsibleUseAcknowledgedAt required when writePolicy=write (ADR-0005)' };
+    }
+    const dir = clisDir(site);
+    const adapterPath = path.join(dir, `${command}.js`);
+    const reportPath = path.join(getSiteRecorderDir(site), `${command}-report.json`);
+    const warnings = [];
+    // shadow/overwrite check (mandatory, 07:64): refuse to silently clobber.
+    const existing = fs.existsSync(adapterPath) ? fs.readFileSync(adapterPath, 'utf-8') : null;
+    if (existing !== null) {
+        warnings.push(`adapter already exists at ${adapterPath}; init will overwrite (review the dry-run diff)`);
+    }
+    const report = {
+        adapterPath, reportPath, warnings,
+        responsibleUseAcknowledgedAt: input.responsibleUseAcknowledgedAt ?? 0,
+        releaseChannel: snapshot.releaseChannel,
+        localExperimentProfile: snapshot.localExperimentProfile,
+        configSnapshotVersion: snapshot.configSnapshotVersion,
+    };
+    // Render with provenance header so even phase-1 (non-atomic) writes are provenanced.
+    const txnId = randomUUID();
+    const reportJson = JSON.stringify(report, null, 2);
+    const provenanceHeader = buildProvenanceHeader({ txnId, reportPath, reportSha256: sha256(reportJson), llmModel: input.llmModel });
+    // browser derived from strategy (COOKIE/UI ⇒ authenticated browser context; PUBLIC ⇒ none),
+    // matching registry normalizeCommand — be derives & sends domain/strategy but not browser (03:74).
+    const browser = input.browser ?? (input.strategy !== undefined && input.strategy !== 'PUBLIC');
+    // LLM 合成产物(若有)填进模板留白;无则空骨架(渲染输出字节级不变)。
+    const rendered = renderAdapterTemplate({
+        site, command, domain: input.domain, strategy: input.strategy, browser, provenanceHeader,
+        funcBody: input.funcBody, columns: input.columns, description: input.description, access: input.access,
+    });
+    const dryRun = computeDryRunDiff(existing, rendered);
+    if (writePolicy === 'dry-run') {
+        return { ok: true, report, dryRun, generatedSource: rendered };
+    }
+    // Write transaction (07:95-104). A crash between the two artifact renames must never leave a
+    // visible adapter without provenance, so: manifest(preparing) → atomic report → atomic
+    // adapter (report committed FIRST) → atomic commit marker → manifest(committed). Each
+    // atomicWrite is temp-file + fsync + rename + parent-dir fsync. The crash-recovery sweep
+    // (recoverInitTransactions, 07:106-117) resolves any interruption from the manifest.
+    const adapterSha256 = sha256(rendered);
+    const reportSha256 = sha256(reportJson);
+    const recoveryDir = path.join(path.dirname(reportPath), '.txn');
+    const manifestPath = path.join(recoveryDir, `${command}.${txnId}.manifest.json`);
+    const markerPath = path.join(path.dirname(reportPath), `${command}.commit.json`);
+    writeManifest(manifestPath, { txnId, adapterPath, reportPath, markerPath, adapterSha256, reportSha256, state: 'preparing', createdAt: Date.now() });
+    atomicWrite(reportPath, reportJson);
+    atomicWrite(adapterPath, rendered);
+    atomicWrite(markerPath, JSON.stringify({ txnId, adapterPath, reportPath, adapterSha256, reportSha256, committedAt: Date.now() }));
+    writeManifest(manifestPath, { txnId, adapterPath, reportPath, markerPath, adapterSha256, reportSha256, state: 'committed', createdAt: Date.now() });
+    return { ok: true, report, dryRun, generatedSource: rendered };
+}
+export function saveAdapterSource(input) {
+    const v = validateAdapterName(input.name);
+    if (!v.ok)
+        return { ok: false, errorCode: 'validation_failed', reason: v.reason };
+    if (typeof input.source !== 'string' || !input.source.trim()) {
+        return { ok: false, errorCode: 'validation_failed', reason: 'source required' };
+    }
+    const { site, command } = v.parts;
+    const adapterPath = path.join(clisDir(site), `${command}.js`);
+    const reportPath = path.join(getSiteRecorderDir(site), `${command}-report.json`);
+    const txnId = randomUUID();
+    const report = { adapterPath, reportPath, source: 'llm-generated', llmModel: input.llmModel ?? null, savedAt: Date.now() };
+    const reportJson = JSON.stringify(report, null, 2);
+    const header = buildProvenanceHeader({ txnId, reportPath, reportSha256: sha256(reportJson), llmModel: input.llmModel });
+    const rendered = input.source.startsWith('// @generated-by') ? input.source : `${header}\n${input.source}`;
+    atomicWrite(reportPath, reportJson);
+    atomicWrite(adapterPath, rendered);
+    return { ok: true, adapterPath, reportPath };
+}
+/** First line of every recorder-generated adapter (buildProvenanceHeader). Recovery only
+ * ever quarantines a file carrying this — never an unknown user-authored file (07:106,117). */
+const PROVENANCE_MARKER = '// @generated-by adapter-recorder';
+function readManifest(p) {
+    try {
+        const m = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (typeof m.txnId !== 'string' || typeof m.adapterPath !== 'string' || typeof m.reportPath !== 'string'
+            || typeof m.markerPath !== 'string' || (m.state !== 'preparing' && m.state !== 'committed'))
+            return null;
+        return m;
+    }
+    catch {
+        return null;
+    }
+}
+function fileSha(p) {
+    try {
+        return sha256(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Gather the on-disk state of a manifest's referenced report/adapter/marker for decideInitRecovery. */
+function observeTxnState(m) {
+    const reportSha = fileSha(m.reportPath);
+    const adapterSha = fileSha(m.adapterPath);
+    const reportExists = reportSha !== null;
+    const adapterExists = adapterSha !== null;
+    const hashesMatch = reportExists && adapterExists && reportSha === m.reportSha256 && adapterSha === m.adapterSha256;
+    let markerExists = false;
+    let markerValid = false;
+    try {
+        const marker = JSON.parse(fs.readFileSync(m.markerPath, 'utf-8'));
+        markerExists = true;
+        markerValid = marker.txnId === m.txnId && marker.adapterPath === m.adapterPath && marker.reportPath === m.reportPath
+            && marker.adapterSha256 === m.adapterSha256 && marker.reportSha256 === m.reportSha256;
+    }
+    catch { /* no/unreadable marker */ }
+    return { reportExists, adapterExists, markerExists, markerValid, hashesMatch, manifestState: m.state };
+}
+/** Move an unprovenanced/corrupt adapter aside — only if it carries our provenance header. */
+function quarantineAdapter(m, log) {
+    let content;
+    try {
+        content = fs.readFileSync(m.adapterPath, 'utf-8');
+    }
+    catch {
+        return;
+    } // already gone
+    if (!content.startsWith(PROVENANCE_MARKER)) {
+        log(`[init-recovery] refuse to quarantine non-recorder file ${m.adapterPath}`);
+        return;
+    }
+    const qDir = path.join(path.dirname(m.reportPath), '.quarantine');
+    fs.mkdirSync(qDir, { recursive: true });
+    const dest = path.join(qDir, `${path.basename(m.adapterPath)}.${m.txnId}`);
+    try {
+        fs.renameSync(m.adapterPath, dest);
+        log(`[init-recovery] quarantined ${m.adapterPath} → ${dest}`);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Resolve init write transactions interrupted by a crash (07:106-117). Scans every
+ * ~/.bycli/sites/<site>/recorder/.txn/*.manifest.json, observes the referenced artifacts, and
+ * applies decideInitRecovery: write/refresh the marker for a provenance-complete transaction,
+ * quarantine an unprovenanced/corrupt adapter, or roll back an empty one. Only manifest paths
+ * (and adapters with the provenance header) are touched — unknown user files are never deleted.
+ * Designed to run once at daemon startup (extends the verify reap).
+ */
+export function recoverInitTransactions(opts = {}) {
+    const sitesRoot = opts.sitesRoot ?? getSitesDir();
+    const log = opts.log ?? (() => { });
+    const result = { scanned: 0, committed: 0, rolledForward: 0, rolledBack: 0, quarantined: 0 };
+    let sites;
+    try {
+        sites = fs.readdirSync(sitesRoot);
+    }
+    catch {
+        return result;
+    }
+    for (const site of sites) {
+        const txnDir = path.join(sitesRoot, site, 'recorder', '.txn');
+        let entries;
+        try {
+            entries = fs.readdirSync(txnDir).filter((f) => f.endsWith('.manifest.json'));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const manifestPath = path.join(txnDir, entry);
+            const m = readManifest(manifestPath);
+            if (!m) {
+                try {
+                    fs.rmSync(manifestPath, { force: true });
+                }
+                catch { /* ignore */ }
+                continue;
+            }
+            result.scanned++;
+            const action = decideInitRecovery(observeTxnState(m));
+            switch (action) {
+                case 'roll_forward':
+                    // provenance complete (report+adapter+hashes) but marker missing → write it.
+                    atomicWrite(m.markerPath, JSON.stringify({ txnId: m.txnId, adapterPath: m.adapterPath, reportPath: m.reportPath, adapterSha256: m.adapterSha256, reportSha256: m.reportSha256, committedAt: Date.now() }));
+                    result.rolledForward++;
+                    break;
+                case 'commit':
+                    result.committed++; // marker already valid; the manifest drop below is the commit
+                    break;
+                case 'quarantine':
+                    quarantineAdapter(m, log);
+                    result.quarantined++;
+                    break;
+                case 'rolled_back':
+                    result.rolledBack++; // orphan report retained; nothing live to undo
+                    break;
+                case 'noop':
+                default:
+                    break;
+            }
+            // terminal: drop the manifest (provenance now lives in the marker / quarantine record).
+            try {
+                fs.rmSync(manifestPath, { force: true });
+            }
+            catch { /* ignore */ }
+        }
+    }
+    if (result.scanned > 0)
+        log(`[init-recovery] swept ${result.scanned}: ${JSON.stringify(result)}`);
+    return result;
+}

package/dist/src/recorder/highlevel/init.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/recorder/highlevel/verify.d.ts

@@ -0,0 +1,73 @@
+/**
+ * High-Level verify module (M5c · verifyAdapter, 07-high-level-services.md).
+ *
+ * Hosted main-repo side (Codex A' verdict): verify runs user adapter JS, which MUST
+ * execute in a child-process runner (08), never in this process. M5c lands the
+ * INTERFACE + delegation seam only: validate the adapter name, derive display-only
+ * evidence from the raw seed args (HMAC, raw never echoed), then delegate to a
+ * RunnerPort. The real runner (spawn / JSONL / env isolation / input.json 0600 /
+ * timeout / reap) landed in M6 and is the production default (defaultRunnerPort);
+ * a stub RunnerPort is retained as a test double to exercise the seam without spawning.
+ *
+ * SECURITY (07:123-124, 167): raw executionSeedArgs stay in memory / input.json only;
+ * they never enter the returned summary, report, status, or logs.
+ */
+import { type SeedArgEvidence, type VerifySummary } from '@sovovs/bycli-recorder-core';
+export interface VerifyInput {
+    /** site/command */
+    name: string;
+    /** Recorder session id (non-secret) forwarded by be. Consumed daemon-side to look up the
+     * per-session HMAC salt (M7a · 04:111) — verifyAdapter itself takes the resolved key as a
+     * separate argument, so this field is not read here. */
+    sessionId?: string;
+    /** Canonical recorder requestId minted by be/Local Service; when set the runner uses it
+     * as the run id so be ↔ daemon ↔ runner all key on the same id. */
+    requestId?: string;
+    /** raw seed args — memory/input.json only, never returned. */
+    executionSeedArgs?: Record<string, unknown>;
+    fixture?: 'ignore' | 'match' | 'update';
+    trace?: 'off' | 'retain-on-failure' | 'always';
+    /** N3:显式 adapter 路径 override —— verify 录制器 LLM 生成的临时草稿(不在 clis/),缺省按 name 派生。 */
+    adapterPath?: string;
+}
+/** The runner boundary (08). M6 provides the real child-process implementation. */
+export interface RunnerPort {
+    startVerify(input: {
+        name: string;
+        /** Canonical requestId from the caller; runner generates one if absent. */
+        requestId?: string;
+        evidenceSeedArgs: Record<string, SeedArgEvidence>;
+        rawSeedArgs: Record<string, unknown>;
+        fixture: string;
+        trace: string;
+        /** N3: explicit adapter path override (recorder draft verify); default = name→clis path. */
+        adapterPath?: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    getVerifyStatus(requestId: string): Promise<VerifySummary | null>;
+    cancelVerify(requestId: string): Promise<{
+        cancelled: boolean;
+    }>;
+}
+export type VerifyResult = {
+    ok: true;
+    requestId: string;
+} | {
+    ok: false;
+    errorCode: 'validation_failed' | 'queue_full' | 'runner_protocol_error';
+    reason: string;
+};
+/**
+ * Stub runner — the seam without execution. Returns runner_protocol_error with a clear
+ * message so callers see the interface is wired but no child ran. Retained as a test
+ * double (inject it to exercise verifyAdapter without spawning); the production default is
+ * the real spawn-based RunnerPort (M6a).
+ */
+export declare const stubRunnerPort: RunnerPort;
+/**
+ * verifyAdapter: validate name → derive display-only evidence → delegate to the runner.
+ * `sessionHmacKey` keys the evidence HMAC; `runner` defaults to the real child-process
+ * RunnerPort (M6a) and can be overridden (stub/fake) in tests.
+ */
+export declare function verifyAdapter(input: VerifyInput, sessionHmacKey: string, runner?: RunnerPort): Promise<VerifyResult>;

package/dist/src/recorder/highlevel/verify.js

@@ -0,0 +1,74 @@
+/**
+ * High-Level verify module (M5c · verifyAdapter, 07-high-level-services.md).
+ *
+ * Hosted main-repo side (Codex A' verdict): verify runs user adapter JS, which MUST
+ * execute in a child-process runner (08), never in this process. M5c lands the
+ * INTERFACE + delegation seam only: validate the adapter name, derive display-only
+ * evidence from the raw seed args (HMAC, raw never echoed), then delegate to a
+ * RunnerPort. The real runner (spawn / JSONL / env isolation / input.json 0600 /
+ * timeout / reap) landed in M6 and is the production default (defaultRunnerPort);
+ * a stub RunnerPort is retained as a test double to exercise the seam without spawning.
+ *
+ * SECURITY (07:123-124, 167): raw executionSeedArgs stay in memory / input.json only;
+ * they never enter the returned summary, report, status, or logs.
+ */
+import { resolve, sep } from 'node:path';
+import { getConfigDir } from '../../config-paths.js';
+import { validateAdapterName, deriveEvidenceSeedArgs, } from '@sovovs/bycli-recorder-core';
+import { defaultRunnerPort } from '../runner/runner-port.js';
+/**
+ * Stub runner — the seam without execution. Returns runner_protocol_error with a clear
+ * message so callers see the interface is wired but no child ran. Retained as a test
+ * double (inject it to exercise verifyAdapter without spawning); the production default is
+ * the real spawn-based RunnerPort (M6a).
+ */
+export const stubRunnerPort = {
+    async startVerify() {
+        throw Object.assign(new Error('verify runner not implemented (stub)'), { code: 'runner_protocol_error' });
+    },
+    async getVerifyStatus() { return null; },
+    async cancelVerify() { return { cancelled: false }; },
+};
+/**
+ * verifyAdapter: validate name → derive display-only evidence → delegate to the runner.
+ * `sessionHmacKey` keys the evidence HMAC; `runner` defaults to the real child-process
+ * RunnerPort (M6a) and can be overridden (stub/fake) in tests.
+ */
+export async function verifyAdapter(input, sessionHmacKey, runner) {
+    const v = validateAdapterName(input.name);
+    if (!v.ok)
+        return { ok: false, errorCode: 'validation_failed', reason: v.reason };
+    // N3 安全:adapterPath override 必须是 byCLI 配置根(BYCLI_CONFIG_DIR,默认 ~/.bycli)下的绝对
+    // 路径(草稿/正式 clis),防越权读任意文件。根随 config-paths 解析,与 clis/sites 落盘同源。
+    let adapterPath = input.adapterPath;
+    if (adapterPath !== undefined) {
+        const abs = resolve(adapterPath);
+        const root = resolve(getConfigDir()) + sep;
+        if (!abs.startsWith(root)) {
+            return { ok: false, errorCode: 'validation_failed', reason: `adapterPath must be under ${getConfigDir()}` };
+        }
+        adapterPath = abs;
+    }
+    const port = runner ?? defaultRunnerPort();
+    const rawSeedArgs = input.executionSeedArgs ?? {};
+    const evidenceSeedArgs = deriveEvidenceSeedArgs(rawSeedArgs, sessionHmacKey);
+    try {
+        const { requestId } = await port.startVerify({
+            name: input.name,
+            requestId: input.requestId, // canonical id from be (undefined → runner generates)
+            evidenceSeedArgs,
+            rawSeedArgs, // memory→input.json only, runner's responsibility; never returned
+            fixture: input.fixture ?? 'ignore',
+            trace: input.trace ?? 'retain-on-failure',
+            adapterPath, // N3: validated draft path override (undefined → name→clis)
+        });
+        return { ok: true, requestId };
+    }
+    catch (e) {
+        // queue_full (M6c: runner at maxConcurrency + queue saturated, 03 → 429) is surfaced
+        // distinctly; any other failure normalizes to runner_protocol_error (08:95).
+        const code = e?.code;
+        const errorCode = code === 'queue_full' ? 'queue_full' : 'runner_protocol_error';
+        return { ok: false, errorCode, reason: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/src/recorder/http/analyze-runner.d.ts

@@ -0,0 +1,28 @@
+import type { AnalyzeReport, AdapterRef } from '../../browser/analyze.js';
+export interface AnalyzeRunInput {
+    url: string;
+    session: string;
+    contextId: string;
+    settleMs?: number;
+}
+/** 可注入 seam:production 构造 daemon-backed Page 跑 analyze;测试注入 fake 返 report 或抛错。 */
+export type AnalyzeRunner = (input: AnalyzeRunInput) => Promise<AnalyzeReport>;
+/**
+ * Lightweight adapter registry for nearest-adapter matching. The wrapper process
+ * SKIPS full adapter discovery (main.ts `internal highlevel-http` fast-path), so
+ * `getRegistry()` is empty here. Instead read the same `cli-manifest.json` that
+ * discovery reads and build the `{site,name,domain}` AdapterRefs `findNearestAdapter`
+ * needs — no adapter code is loaded, faithful to the wrapper's lightweight design.
+ * User manifest is read last so it overrides built-ins on `site/name` collisions
+ * (mirrors discovery order). Cached for the server lifetime; pass explicit
+ * `manifestPaths` (tests) to bypass the cache.
+ */
+export declare function loadAdapterRegistry(manifestPaths?: string[]): Map<string, AdapterRef>;
+/**
+ * 默认 analyzeRunner(M6b daemon-backed Page)。timeoutMs 透传给 analyzeBrowserWithTimeout(超时 →
+ * AnalyzeTimeoutError code='analyze_timeout')。nearest-adapter registry 经 loadAdapterRegistry()
+ * 从 cli-manifest.json 轻量加载(wrapper 跳过 discovery,getRegistry() 在此进程为空)。
+ */
+export declare function createAnalyzeRunner(opts: {
+    timeoutMs: number;
+}): AnalyzeRunner;

package/dist/src/recorder/http/analyze-runner.js

@@ -0,0 +1,78 @@
+// M9c High-Level HTTP wrapper —— analyze 异步 worker。analyzeBrowser 需要活的 IPage:这里复刻 M6b
+// 连回模式(verify-runner-main.ts:138-154)——直接 `new Page(...)`(**不经 BrowserBridge**,后者
+// connect() 会 health-check + spawn/重启 daemon;wrapper 只该 attach 现有 daemon、绝不管理 daemon 生命
+// 周期),经 `BYCLI_DAEMON_PORT`(daemon-client.ts:12 模块加载时读)连回父 daemon 拿 Page,跑
+// analyzeBrowserWithTimeout,finally 释放 lease(closeWindow)。隔离成可注入 seam → 测试无需真 daemon/Page。
+import fs from 'node:fs';
+import path from 'node:path';
+import { getUserClisDir } from '../../config-paths.js';
+import { fileURLToPath } from 'node:url';
+import { findPackageRoot, getCliManifestPath } from '../../package-paths.js';
+let cachedRegistry = null;
+function defaultManifestPaths() {
+    const root = findPackageRoot(fileURLToPath(import.meta.url));
+    return [
+        getCliManifestPath(path.join(root, 'clis')), // built-in adapters
+        getCliManifestPath(getUserClisDir()), // user adapters
+    ];
+}
+/**
+ * Lightweight adapter registry for nearest-adapter matching. The wrapper process
+ * SKIPS full adapter discovery (main.ts `internal highlevel-http` fast-path), so
+ * `getRegistry()` is empty here. Instead read the same `cli-manifest.json` that
+ * discovery reads and build the `{site,name,domain}` AdapterRefs `findNearestAdapter`
+ * needs — no adapter code is loaded, faithful to the wrapper's lightweight design.
+ * User manifest is read last so it overrides built-ins on `site/name` collisions
+ * (mirrors discovery order). Cached for the server lifetime; pass explicit
+ * `manifestPaths` (tests) to bypass the cache.
+ */
+export function loadAdapterRegistry(manifestPaths) {
+    if (!manifestPaths && cachedRegistry)
+        return cachedRegistry;
+    const registry = new Map();
+    for (const manifestPath of manifestPaths ?? defaultManifestPaths()) {
+        let raw;
+        try {
+            raw = fs.readFileSync(manifestPath, 'utf8');
+        }
+        catch {
+            continue; /* no manifest on disk */
+        }
+        let entries;
+        try {
+            entries = JSON.parse(raw);
+        }
+        catch {
+            continue; /* corrupt → skip, best-effort */
+        }
+        if (!Array.isArray(entries))
+            continue;
+        for (const e of entries) {
+            if (!e?.site || !e?.name)
+                continue;
+            registry.set(`${e.site}/${e.name}`, { site: e.site, name: e.name, domain: e.domain });
+        }
+    }
+    if (!manifestPaths)
+        cachedRegistry = registry;
+    return registry;
+}
+/**
+ * 默认 analyzeRunner(M6b daemon-backed Page)。timeoutMs 透传给 analyzeBrowserWithTimeout(超时 →
+ * AnalyzeTimeoutError code='analyze_timeout')。nearest-adapter registry 经 loadAdapterRegistry()
+ * 从 cli-manifest.json 轻量加载(wrapper 跳过 discovery,getRegistry() 在此进程为空)。
+ */
+export function createAnalyzeRunner(opts) {
+    return async (input) => {
+        const { Page } = await import('../../browser/page.js');
+        const { analyzeBrowserWithTimeout } = await import('../highlevel/analyze.js');
+        // background automation window + ephemeral per-run session,直接连回 daemon(同 M6b)。
+        const page = new Page(input.session, undefined, input.contextId, 'background', 'adapter', 'ephemeral');
+        try {
+            return await analyzeBrowserWithTimeout(page, loadAdapterRegistry(), { url: input.url, settleMs: input.settleMs }, opts.timeoutMs);
+        }
+        finally {
+            await page.closeWindow?.().catch(() => { });
+        }
+    };
+}

package/dist/src/recorder/http/analyze-runner.test.d.ts

@@ -0,0 +1 @@
+export {};

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>;