@world-engines/project-host 0.1.0-alpha.0

package/dist/account-model-proxy.d.ts

@@ -0,0 +1,21 @@
+import type { LocalGuiAuth } from "./local-gui-auth.js";
+export declare const LOCAL_ACCOUNT_MODEL_PROXY_HOST = "127.0.0.1";
+export declare const LOCAL_ACCOUNT_MODEL_PROXY_PORT = 11450;
+export declare const LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN = "http://127.0.0.1:11450";
+export interface LocalAccountModelProxy {
+    readonly origin: typeof LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN | string;
+    close(): Promise<void>;
+}
+export interface StartLocalAccountModelProxyOptions {
+    readonly projectRoot: string;
+    readonly projectId: string;
+    readonly auth: LocalGuiAuth;
+    /** 仅供 HTTP contract 测试；生产必须独占固定 11450。 */
+    readonly testOnlyPort?: 0;
+}
+export type LocalAccountProjectBinding = Readonly<{
+    canonicalRoot: string;
+    rootIdentity: string;
+}>;
+export declare function resolveLocalAccountProjectBinding(projectRoot: string, projectId: string): Promise<LocalAccountProjectBinding>;
+export declare function startLocalAccountModelProxy(options: StartLocalAccountModelProxyOptions): Promise<LocalAccountModelProxy>;

package/dist/account-model-proxy.js

@@ -0,0 +1,470 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import { createServer } from "node:http";
+import { join, resolve } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { canonicalAccountProjectRootIdentityBytes } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath } from "./safe-project-path.js";
+export const LOCAL_ACCOUNT_MODEL_PROXY_HOST = "127.0.0.1";
+export const LOCAL_ACCOUNT_MODEL_PROXY_PORT = 11450;
+export const LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN = `http://${LOCAL_ACCOUNT_MODEL_PROXY_HOST}:${LOCAL_ACCOUNT_MODEL_PROXY_PORT}`;
+const MAX_REQUEST_BYTES = 8 * 1024 * 1024;
+const PROJECT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
+const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/u;
+const OPERATION_ID_PATTERN = /^[A-Za-z0-9._:-]{1,256}$/u;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+const TERMINAL_STATUS = new Set([
+    "authorized_no_response", "settled_no_response", "failed_no_response", "reconcile_required",
+]);
+const LEDGER_STATUS = new Set([
+    "authorized", "dispatched", "provider_succeeded", "settled", "failed", "ambiguous", "reconcile_required",
+]);
+class ModelProxyHttpError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function fail(status, code, message) {
+    throw new ModelProxyHttpError(status, code, message);
+}
+function accountIdentity(projectId, principalId) {
+    return createHash("sha256").update("worldengine-account-model-v1\0").update(projectId).update("\0").update(principalId).digest("hex");
+}
+function sessionIdentity(response, expectedProjectId) {
+    if (response.status === 401)
+        fail(401, "E_AUTH_REQUIRED", "账户模型代理需要登录");
+    if (response.status !== 200)
+        fail(response.status, "E_OPERATION_UNCERTAIN", "账户身份读取失败");
+    const principalId = response.body.principal_id;
+    const projectId = response.body.project_id;
+    if (typeof principalId !== "string" || principalId.length === 0 || principalId.length > 256
+        || typeof projectId !== "string" || projectId !== expectedProjectId || response.session === undefined) {
+        fail(502, "E_VALIDATION_FAILED", "账户身份响应无效");
+    }
+    return Object.freeze({ principalId, projectId, accountIdentity: accountIdentity(projectId, principalId), lease: response.session });
+}
+export async function resolveLocalAccountProjectBinding(projectRoot, projectId) {
+    if (!PROJECT_ID_PATTERN.test(projectId))
+        fail(400, "E_SCHEMA_INVALID", "project_id 无效");
+    const canonicalRoot = await realpath(resolve(projectRoot));
+    const manifestPath = await assertSafeExistingProjectPath(canonicalRoot, join(canonicalRoot, "worldengine.project.json"));
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    catch {
+        fail(400, "E_SCHEMA_INVALID", "项目 manifest 无效");
+    }
+    if (record(manifest)?.project_id !== projectId)
+        fail(409, "E_AUTH_REQUIRED", "项目 identity 不匹配");
+    const rootIdentity = createHash("sha256")
+        .update(canonicalAccountProjectRootIdentityBytes(canonicalRoot, process.platform === "win32" ? "win32" : "posix"))
+        .digest("hex");
+    return Object.freeze({ canonicalRoot, rootIdentity });
+}
+function assertNodeRequest(request, host, projectId, rootIdentity) {
+    if (request.headers.host !== host)
+        fail(403, "E_PROXY_HOST_FORBIDDEN", "Host 无效");
+    if (request.headers.origin !== undefined || request.headers.referer !== undefined
+        || request.headers["sec-fetch-site"] !== undefined || request.headers["sec-fetch-dest"] !== undefined) {
+        fail(403, "E_PROXY_BROWSER_FORBIDDEN", "浏览器请求不允许访问账户模型代理");
+    }
+    if (request.headers["x-worldengine-project-id"] !== projectId) {
+        fail(403, "E_AUTH_REQUIRED", "请求未绑定当前项目");
+    }
+    if (request.headers["x-worldengine-project-root-sha256"] !== rootIdentity) {
+        fail(403, "E_AUTH_REQUIRED", "请求未绑定当前项目根");
+    }
+}
+function assertExpectedAccount(request, current) {
+    if (request.headers["x-worldengine-account-identity"] !== current.accountIdentity) {
+        fail(409, "E_ACCOUNT_CHANGED", "请求账户 identity 已失效");
+    }
+}
+async function readJsonBody(request) {
+    const declared = Number(request.headers["content-length"]);
+    if (Number.isFinite(declared) && declared > MAX_REQUEST_BYTES)
+        fail(413, "E_SCHEMA_INVALID", "模型请求过大");
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.from(chunk);
+        total += bytes.byteLength;
+        if (total > MAX_REQUEST_BYTES)
+            fail(413, "E_SCHEMA_INVALID", "模型请求过大");
+        chunks.push(bytes);
+    }
+    try {
+        const parsed = record(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+        if (parsed !== undefined)
+            return parsed;
+    }
+    catch { /* 统一返回公开 schema 错误。 */ }
+    fail(400, "E_SCHEMA_INVALID", "模型请求不是有效 JSON object");
+}
+function sendJson(response, status, body) {
+    const encoded = JSON.stringify(body);
+    response.statusCode = status;
+    response.setHeader("Content-Type", "application/json; charset=utf-8");
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader("Content-Length", Buffer.byteLength(encoded));
+    response.end(encoded);
+}
+function publicError(error) {
+    if (error instanceof ModelProxyHttpError)
+        return error;
+    if (error instanceof AuthoringBridgeError) {
+        if (error.code === "E_AUTH_REQUIRED")
+            return { status: 401, code: error.code, message: "账户模型代理需要登录" };
+        if (error.code === "E_REMOTE_FORBIDDEN")
+            return { status: 403, code: error.code, message: "账户模型请求被拒绝" };
+    }
+    return { status: 503, code: "E_OPERATION_UNCERTAIN", message: "账户模型代理暂时不可用" };
+}
+const CHAT_REQUEST_FIELDS = new Set([
+    "model", "messages", "max_tokens", "max_completion_tokens", "temperature", "top_p", "stop",
+    "frequency_penalty", "presence_penalty", "seed", "response_format", "tools", "tool_choice",
+    "parallel_tool_calls", "stream",
+]);
+function assertChatRequest(body) {
+    if (Object.keys(body).some((key) => !CHAT_REQUEST_FIELDS.has(key))
+        || typeof body.model !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u.test(body.model)
+        || !Array.isArray(body.messages) || body.messages.length === 0 || body.messages.length > 256
+        || (body.stream !== undefined && body.stream !== false)) {
+        fail(400, "E_SCHEMA_INVALID", "chat completions 请求字段无效");
+    }
+    for (const messageValue of body.messages) {
+        const message = record(messageValue);
+        if (message === undefined || typeof message.role !== "string"
+            || !["system", "user", "assistant", "tool"].includes(message.role)
+            || (typeof message.content !== "string" && !Array.isArray(message.content))) {
+            fail(400, "E_SCHEMA_INVALID", "chat completions message 无效");
+        }
+    }
+}
+function publicChatResponse(body) {
+    if (typeof body.model !== "string" || !Array.isArray(body.choices) || record(body.usage) === undefined
+        || typeof body.operation_id !== "string" || !/^[A-Za-z0-9._:-]{1,256}$/u.test(body.operation_id)) {
+        fail(502, "E_VALIDATION_FAILED", "chat completions 响应无效");
+    }
+    const allowed = ["id", "object", "created", "model", "provider", "choices", "usage", "operation_id", "cost_status"];
+    return Object.freeze(Object.fromEntries(allowed.filter((key) => body[key] !== undefined).map((key) => [key, body[key]])));
+}
+/** chat 和 embedding 的已持久化计费终态共用同一公开、脱敏的幂等恢复契约。 */
+function publicTerminalOperationReceipt(body) {
+    const error = record(body.error);
+    const operationId = body.operation_id;
+    const status = body.status;
+    const ledgerStatus = body.ledger_status;
+    const resultSha256 = body.provider_result_sha256;
+    if (error?.code !== "E_OPERATION_UNCERTAIN"
+        || typeof operationId !== "string" || !OPERATION_ID_PATTERN.test(operationId)
+        || typeof status !== "string" || !TERMINAL_STATUS.has(status)
+        || typeof ledgerStatus !== "string" || !LEDGER_STATUS.has(ledgerStatus)
+        || (resultSha256 !== undefined && resultSha256 !== null && (typeof resultSha256 !== "string" || !SHA256_PATTERN.test(resultSha256)))
+        || body.retryable !== false || body.retry_policy !== "do_not_change_idempotency_key") {
+        return undefined;
+    }
+    return Object.freeze({
+        error: Object.freeze({
+            code: "E_OPERATION_UNCERTAIN",
+            message: "模型操作已有持久终态；保留并使用同一 Idempotency-Key，不得换 key 自动重试",
+        }),
+        operation_id: operationId,
+        status,
+        ledger_status: ledgerStatus,
+        ...(resultSha256 === undefined ? {} : { provider_result_sha256: resultSha256 }),
+        retryable: false,
+        retry_policy: "do_not_change_idempotency_key",
+    });
+}
+function executionErrorCode(status) {
+    return status === 401 ? "E_AUTH_REQUIRED"
+        : status === 402 ? "E_BALANCE_REQUIRED"
+            : status === 429 ? "E_RATE_LIMITED"
+                : "E_OPERATION_UNCERTAIN";
+}
+function embeddingDescriptor(body) {
+    const inputKinds = record(body.input_kinds);
+    const documentKind = record(inputKinds?.document);
+    const queryKind = record(inputKinds?.query);
+    if (typeof body.provider !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(body.provider)
+        || typeof body.model !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u.test(body.model)
+        || !Number.isSafeInteger(body.dimensions) || body.dimensions < 1 || body.dimensions > 65_536
+        || !Number.isSafeInteger(body.max_inputs) || body.max_inputs < 1 || body.max_inputs > 128
+        || !Number.isSafeInteger(body.max_input_chars) || body.max_input_chars < 1 || body.max_input_chars > 1_000_000
+        || typeof body.descriptor_sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(body.descriptor_sha256)
+        || documentKind?.descriptor_sha256 !== body.descriptor_sha256
+        || typeof queryKind?.descriptor_sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(queryKind.descriptor_sha256)) {
+        fail(502, "E_VALIDATION_FAILED", "embedding descriptor 无效");
+    }
+    return Object.freeze({
+        provider: body.provider,
+        model: body.model,
+        dimensions: body.dimensions,
+        maxInputs: body.max_inputs,
+        maxInputChars: body.max_input_chars,
+        descriptorSha256: body.descriptor_sha256,
+        descriptorSha256ByInputKind: Object.freeze({ document: body.descriptor_sha256, query: queryKind.descriptor_sha256 }),
+    });
+}
+function chatCatalog(body) {
+    if (typeof body.catalog_digest !== "string" || !SHA256_PATTERN.test(body.catalog_digest)
+        || !Array.isArray(body.models) || body.models.length === 0 || body.models.length > 512) {
+        fail(502, "E_VALIDATION_FAILED", "chat catalog 无效");
+    }
+    const seen = new Set();
+    const models = body.models.map((value) => {
+        const item = record(value);
+        if (item === undefined || typeof item.model !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u.test(item.model)
+            || !Number.isSafeInteger(item.max_output_tokens) || item.max_output_tokens < 1) {
+            fail(502, "E_VALIDATION_FAILED", "chat catalog 无效");
+        }
+        if (seen.has(item.model))
+            fail(502, "E_VALIDATION_FAILED", "chat catalog 无效");
+        seen.add(item.model);
+        return Object.freeze({ model: item.model, maxOutputTokens: item.max_output_tokens });
+    });
+    return Object.freeze({ catalogDigest: body.catalog_digest, models: Object.freeze(models) });
+}
+function assertEmbeddingRequest(body, descriptor) {
+    if (Object.keys(body).sort().join("\0") !== "dimensions\0encoding_format\0input\0input_kind\0model"
+        || body.model !== descriptor.model || body.dimensions !== descriptor.dimensions || body.encoding_format !== "float"
+        || (body.input_kind !== "document" && body.input_kind !== "query")
+        || !Array.isArray(body.input) || body.input.length === 0 || body.input.length > descriptor.maxInputs
+        || body.input.some((text) => typeof text !== "string" || text.length === 0 || [...text].length > descriptor.maxInputChars)) {
+        fail(400, "E_SCHEMA_INVALID", "embedding 请求不符合当前 descriptor");
+    }
+}
+/**
+ * 本地 loopback 是账户凭据边界，不能把 provider 成功响应的任意嵌套字段转给桌面。
+ * 只重建 embedding 客户端实际消费的稳定结构；任何漂移一律作为上游校验失败。
+ */
+function publicEmbeddingResponse(body, descriptor) {
+    const usage = record(body.usage);
+    if ((body.object !== undefined && body.object !== "list")
+        || body.model !== descriptor.model || body.provider !== descriptor.provider
+        || body.dimensions !== descriptor.dimensions
+        || (body.input_kind !== "document" && body.input_kind !== "query")
+        || typeof body.operation_id !== "string" || !OPERATION_ID_PATTERN.test(body.operation_id)
+        || !Number.isSafeInteger(usage?.prompt_tokens) || usage?.prompt_tokens < 0
+        || !Number.isSafeInteger(usage?.total_tokens) || usage?.total_tokens < usage?.prompt_tokens
+        || !Array.isArray(body.data)) {
+        fail(502, "E_VALIDATION_FAILED", "embedding 响应无效");
+    }
+    const data = new Array(body.data.length);
+    for (const value of body.data) {
+        const item = record(value);
+        if (item === undefined || (item.object !== undefined && item.object !== "embedding"))
+            fail(502, "E_VALIDATION_FAILED", "embedding 响应无效");
+        if (!Number.isSafeInteger(item.index) || item.index < 0 || item.index >= data.length
+            || data[item.index] !== undefined || !Array.isArray(item.embedding)
+            || item.embedding.length !== descriptor.dimensions
+            || item.embedding.some((entry) => typeof entry !== "number" || !Number.isFinite(entry))) {
+            fail(502, "E_VALIDATION_FAILED", "embedding 响应无效");
+        }
+        data[item.index] = Object.freeze({ object: "embedding", index: item.index, embedding: Object.freeze([...item.embedding]) });
+    }
+    if (data.some((item) => item === undefined))
+        fail(502, "E_VALIDATION_FAILED", "embedding 响应无效");
+    return Object.freeze({
+        object: "list",
+        data: Object.freeze(data),
+        model: descriptor.model,
+        provider: descriptor.provider,
+        dimensions: descriptor.dimensions,
+        input_kind: body.input_kind,
+        usage: Object.freeze({ prompt_tokens: usage.prompt_tokens, total_tokens: usage.total_tokens }),
+        operation_id: body.operation_id,
+    });
+}
+function publicDescriptorResponse(descriptor, projectId, identity) {
+    return Object.freeze({
+        provider: descriptor.provider,
+        model: descriptor.model,
+        dimensions: descriptor.dimensions,
+        max_inputs: descriptor.maxInputs,
+        max_input_chars: descriptor.maxInputChars,
+        descriptor_sha256: descriptor.descriptorSha256,
+        input_kinds: Object.freeze({
+            document: Object.freeze({ descriptor_sha256: descriptor.descriptorSha256ByInputKind.document }),
+            query: Object.freeze({ descriptor_sha256: descriptor.descriptorSha256ByInputKind.query }),
+        }),
+        project_id: projectId,
+        account_identity: identity,
+    });
+}
+function publicChatCatalogResponse(catalog, principalId, projectId, identity) {
+    return Object.freeze({
+        principal_id: principalId,
+        catalog_digest: catalog.catalogDigest,
+        models: catalog.models.map(({ model, maxOutputTokens }) => Object.freeze({ model, max_output_tokens: maxOutputTokens })),
+        project_id: projectId,
+        account_identity: identity,
+    });
+}
+export async function startLocalAccountModelProxy(options) {
+    const projectBinding = await resolveLocalAccountProjectBinding(options.projectRoot, options.projectId);
+    let hostHeader = "";
+    const server = createServer(async (request, response) => {
+        try {
+            assertNodeRequest(request, hostHeader, options.projectId, projectBinding.rootIdentity);
+            const url = new URL(request.url ?? "/", `http://${hostHeader}`);
+            if (url.search !== "")
+                fail(400, "E_SCHEMA_INVALID", "账户模型代理不接受查询参数");
+            if (options.auth.status().state !== "signed_in")
+                fail(401, "E_AUTH_REQUIRED", "账户模型代理需要登录");
+            const current = sessionIdentity(await options.auth.requestModel({ kind: "session" }), options.projectId);
+            if (request.method === "GET" && url.pathname === "/v1/session") {
+                sendJson(response, 200, { project_id: options.projectId, account_identity: current.accountIdentity });
+                return;
+            }
+            if (request.method === "GET" && url.pathname === "/v1/chat/catalog") {
+                assertExpectedAccount(request, current);
+                const remote = await options.auth.requestModel({ kind: "chat_catalog", session: current.lease });
+                if (remote.status !== 200) {
+                    sendJson(response, remote.status, { error: { code: remote.status === 401 ? "E_AUTH_REQUIRED" : "E_OPERATION_UNCERTAIN" } });
+                    return;
+                }
+                if ((remote.body.project_id !== undefined && remote.body.project_id !== options.projectId)
+                    || (remote.body.principal_id !== undefined && remote.body.principal_id !== current.principalId)) {
+                    fail(409, "E_ACCOUNT_CHANGED", "chat catalog 账户 identity 不匹配");
+                }
+                sendJson(response, 200, publicChatCatalogResponse(chatCatalog(remote.body), current.principalId, options.projectId, current.accountIdentity));
+                return;
+            }
+            if (request.method === "GET" && url.pathname === "/v1/embedding/descriptor") {
+                assertExpectedAccount(request, current);
+                const remote = await options.auth.requestModel({ kind: "embedding_descriptor", session: current.lease });
+                if (remote.status !== 200) {
+                    sendJson(response, remote.status, { error: { code: remote.status === 401 ? "E_AUTH_REQUIRED" : "E_OPERATION_UNCERTAIN" } });
+                    return;
+                }
+                const remoteProject = remote.body.project_id;
+                const remotePrincipal = remote.body.principal_id;
+                if ((remoteProject !== undefined && remoteProject !== options.projectId)
+                    || (remotePrincipal !== undefined && remotePrincipal !== current.principalId)) {
+                    fail(409, "E_ACCOUNT_CHANGED", "descriptor 账户 identity 不匹配");
+                }
+                sendJson(response, 200, publicDescriptorResponse(embeddingDescriptor(remote.body), options.projectId, current.accountIdentity));
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/v1/embeddings") {
+                assertExpectedAccount(request, current);
+                if (request.headers["content-type"]?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+                    fail(415, "E_SCHEMA_INVALID", "模型请求 content-type 无效");
+                }
+                const idempotencyKey = request.headers["idempotency-key"];
+                if (typeof idempotencyKey !== "string" || !IDEMPOTENCY_KEY_PATTERN.test(idempotencyKey)) {
+                    fail(400, "E_SCHEMA_INVALID", "idempotency-key 无效");
+                }
+                const body = await readJsonBody(request);
+                const descriptorResponse = await options.auth.requestModel({ kind: "embedding_descriptor", session: current.lease });
+                if (descriptorResponse.status !== 200) {
+                    sendJson(response, descriptorResponse.status, { error: { code: descriptorResponse.status === 401 ? "E_AUTH_REQUIRED" : "E_OPERATION_UNCERTAIN" } });
+                    return;
+                }
+                if ((descriptorResponse.body.project_id !== undefined && descriptorResponse.body.project_id !== options.projectId)
+                    || (descriptorResponse.body.principal_id !== undefined && descriptorResponse.body.principal_id !== current.principalId)) {
+                    fail(409, "E_ACCOUNT_CHANGED", "descriptor 账户 identity 不匹配");
+                }
+                const descriptor = embeddingDescriptor(descriptorResponse.body);
+                assertEmbeddingRequest(body, descriptor);
+                const remote = await options.auth.requestModel({ kind: "embedding", session: current.lease, idempotency_key: idempotencyKey, body });
+                if (remote.status < 200 || remote.status >= 300) {
+                    const terminal = publicTerminalOperationReceipt(remote.body);
+                    if (remote.status === 409 && terminal !== undefined) {
+                        sendJson(response, 409, terminal);
+                        return;
+                    }
+                    sendJson(response, remote.status, { error: { code: executionErrorCode(remote.status) } });
+                    return;
+                }
+                if ((remote.body.project_id !== undefined && remote.body.project_id !== options.projectId)
+                    || (remote.body.principal_id !== undefined && remote.body.principal_id !== current.principalId)) {
+                    fail(409, "E_ACCOUNT_CHANGED", "模型响应账户 identity 不匹配");
+                }
+                sendJson(response, remote.status, publicEmbeddingResponse(remote.body, descriptor));
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/v1/chat/completions") {
+                assertExpectedAccount(request, current);
+                if (request.headers["content-type"]?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+                    fail(415, "E_SCHEMA_INVALID", "模型请求 content-type 无效");
+                }
+                const idempotencyKey = request.headers["idempotency-key"];
+                if (typeof idempotencyKey !== "string" || !IDEMPOTENCY_KEY_PATTERN.test(idempotencyKey)) {
+                    fail(400, "E_SCHEMA_INVALID", "idempotency-key 无效");
+                }
+                const body = await readJsonBody(request);
+                assertChatRequest(body);
+                const remote = await options.auth.requestModel({ kind: "chat_completions", session: current.lease, idempotency_key: idempotencyKey, body });
+                if (remote.status < 200 || remote.status >= 300) {
+                    const terminal = publicTerminalOperationReceipt(remote.body);
+                    if (remote.status === 409 && terminal !== undefined) {
+                        sendJson(response, 409, terminal);
+                        return;
+                    }
+                    sendJson(response, remote.status, { error: { code: executionErrorCode(remote.status) } });
+                    return;
+                }
+                if ((remote.body.project_id !== undefined && remote.body.project_id !== options.projectId)
+                    || (remote.body.principal_id !== undefined && remote.body.principal_id !== current.principalId)) {
+                    fail(409, "E_ACCOUNT_CHANGED", "模型响应账户 identity 不匹配");
+                }
+                sendJson(response, remote.status, publicChatResponse(remote.body));
+                return;
+            }
+            fail(404, "E_NOT_FOUND", "账户模型端点不存在");
+        }
+        catch (error) {
+            if (response.headersSent) {
+                response.destroy();
+                return;
+            }
+            const rendered = publicError(error);
+            sendJson(response, rendered.status, { error: { code: rendered.code, message: rendered.message } });
+        }
+    });
+    const port = options.testOnlyPort ?? LOCAL_ACCOUNT_MODEL_PROXY_PORT;
+    try {
+        await new Promise((resolvePromise, rejectPromise) => {
+            const onError = (error) => { server.off("listening", onListening); rejectPromise(error); };
+            const onListening = () => { server.off("error", onError); resolvePromise(); };
+            server.once("error", onError);
+            server.once("listening", onListening);
+            server.listen({ host: LOCAL_ACCOUNT_MODEL_PROXY_HOST, port });
+        });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EADDRINUSE")
+            fail(409, "E_ACCOUNT_MODEL_PROXY_PORT_IN_USE", "127.0.0.1:11450 已被其他服务占用");
+        fail(503, "E_ACCOUNT_MODEL_PROXY_UNAVAILABLE", "账户模型代理启动失败");
+    }
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        await new Promise((resolvePromise) => server.close(() => resolvePromise()));
+        fail(503, "E_ACCOUNT_MODEL_PROXY_UNAVAILABLE", "账户模型代理地址无效");
+    }
+    hostHeader = `${LOCAL_ACCOUNT_MODEL_PROXY_HOST}:${address.port}`;
+    const origin = `http://${hostHeader}`;
+    let closed;
+    return Object.freeze({
+        origin,
+        close() {
+            closed ??= new Promise((resolvePromise, rejectPromise) => server.close((error) => error === undefined ? resolvePromise() : rejectPromise(error)));
+            return closed;
+        },
+    });
+}

package/dist/authoring-browser-runtime.d.ts

@@ -0,0 +1,7 @@
+import type { DesktopAuthoringCapabilities } from "./desktop-authoring-runtime.js";
+import { LocalPreviewRuntime } from "./preview-runtime.js";
+/** 浏览器只在外部开发 harness 实际调用 Preview 时启动；不让 iframe 接触作者工具。 */
+export declare function createAuthoringBrowserRuntime(projectRoot: string, preview: LocalPreviewRuntime): {
+    capabilities: Pick<DesktopAuthoringCapabilities, "preview_inspect" | "preview_interact">;
+    close(): Promise<void>;
+};

package/dist/authoring-browser-runtime.js

@@ -0,0 +1,110 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { createChromiumPreviewBrowserHarness } from "./chromium-preview-browser-driver.js";
+import { startLocalGuiServer } from "./local-gui-server.js";
+import { LOCAL_GUI_ORIGIN } from "./local-gui-contract.js";
+import { LocalProjectHost } from "./project-host.js";
+import { attachLocalGuiPreview } from "./local-gui-preview-client.js";
+import { LocalPreviewRuntime, readLivePreviewSessionOwner } from "./preview-runtime.js";
+/** 浏览器只在外部开发 harness 实际调用 Preview 时启动；不让 iframe 接触作者工具。 */
+export function createAuthoringBrowserRuntime(projectRoot, preview) {
+    let opening;
+    let gui;
+    let attachedPreview = null;
+    let ownedPreview = false;
+    let closed = false;
+    const ensure = () => {
+        if (closed)
+            return Promise.reject(new AuthoringBridgeError("E_PREVIEW_NOT_RUNNING", "开发浏览器已关闭"));
+        opening ??= (async () => {
+            const identityHost = await LocalProjectHost.open(projectRoot);
+            let projectId;
+            try {
+                projectId = (await identityHost.inspect()).project_id;
+            }
+            finally {
+                await identityHost.close();
+            }
+            attachedPreview = await attachLocalGuiPreview(projectRoot, projectId);
+            if (attachedPreview === null && preview.inspect() === null) {
+                // 其他 GUI/MCP 的预览不能被本进程自动接管或重启。
+                const owner = await readLivePreviewSessionOwner(projectRoot);
+                if (owner !== null) {
+                    attachedPreview = Object.freeze({
+                        session_id: owner.session_id, project_root: owner.project_root, cwd: owner.cwd,
+                        url: owner.url, port: owner.port, state: "running", pid: owner.pid,
+                        started_at_ms: 0, stopped_at_ms: null, exit_code: null,
+                        stdout: "", stderr: "", stdout_truncated: false, stderr_truncated: false,
+                    });
+                }
+                else {
+                    try {
+                        await lstat(join(projectRoot, ".worldengine", "preview-session.json"));
+                        throw new AuthoringBridgeError("E_PROJECT_BUSY", "Preview ledger 存在但无法安全附着；拒绝接管或重启");
+                    }
+                    catch (error) {
+                        if (error.code !== "ENOENT")
+                            throw error;
+                    }
+                    await preview.start(projectRoot);
+                    ownedPreview = true;
+                }
+            }
+            const deadline = Date.now() + 20_000;
+            while (preview.inspect()?.state === "starting" && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 50));
+            }
+            const sessionPort = { inspect: () => preview.inspect() ?? attachedPreview };
+            if (sessionPort.inspect()?.state !== "running")
+                throw new AuthoringBridgeError("E_PREVIEW_NOT_RUNNING", "Preview 未在时限内就绪");
+            if (attachedPreview === null)
+                gui = await startLocalGuiServer(projectRoot, { previewRuntime: preview });
+            return createChromiumPreviewBrowserHarness(sessionPort, {
+                hostPageUrl: gui?.url ?? LOCAL_GUI_ORIGIN,
+                previewFrameSelector: "#preview-frame",
+                activatePreviewSelector: '[data-view="view"]',
+                expectedProjectId: projectId,
+            });
+        })().catch(async (error) => {
+            opening = undefined;
+            await gui?.close();
+            gui = undefined;
+            attachedPreview = null;
+            if (ownedPreview) {
+                ownedPreview = false;
+                await preview.stop();
+            }
+            throw error;
+        });
+        return opening;
+    };
+    const capabilities = {
+        async preview_inspect(input) {
+            return (await ensure()).desktopAuthoringCapabilities.preview_inspect(input);
+        },
+        async preview_interact(input) {
+            return (await ensure()).desktopAuthoringCapabilities.preview_interact(input);
+        },
+    };
+    return {
+        capabilities,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                await (await opening)?.close();
+            }
+            finally {
+                await gui?.close();
+                gui = undefined;
+                attachedPreview = null;
+                if (ownedPreview) {
+                    ownedPreview = false;
+                    await preview.stop();
+                }
+            }
+        },
+    };
+}

package/dist/authoring-ingestion.d.ts

@@ -0,0 +1,38 @@
+import type { AuthoringToolCall } from "@world-engines/authoring-bridge";
+import { type NaturalLanguageChunkingOptions, type NaturalLanguageSource, type WorldFactCommitReceipt } from "@world-engines/tmw/natural-language-ingestion";
+import type { AuthoringModelConnection } from "./authoring-model-connection.js";
+export interface ProjectDocumentIngestionHost {
+    inspect(): Promise<Readonly<{
+        project_revision: number;
+    }>>;
+    dispatchTool(call: AuthoringToolCall): Promise<unknown>;
+}
+/** secret 由调用方在 host process 内构造 model connection；本 capability 不序列化认证材料。 */
+export interface ProjectDocumentIngestionCapability {
+    readonly modelConnection: AuthoringModelConnection;
+    readonly maximumConcurrentExtractions?: number;
+    readonly chunking?: NaturalLanguageChunkingOptions;
+    readonly clock?: () => number;
+}
+export type ProjectDocumentIngestionWarning = Readonly<{
+    code: "world_facts_rejected" | "evidence_offsets_corrected" | "unverified_chunks";
+    count: number;
+}>;
+export interface ProjectDocumentIngestionReceipt extends WorldFactCommitReceipt {
+    readonly completeness: "complete" | "partial";
+    readonly rejectedFactCount: number;
+    readonly correctedEvidenceCount: number;
+    readonly warnings: readonly ProjectDocumentIngestionWarning[];
+    readonly committedFacts: readonly Readonly<{
+        scopeId: string;
+        factId: string;
+    }>[];
+    readonly rejectionReasons: Readonly<Record<string, number>>;
+    readonly unverifiedChunkCount: number;
+    readonly unverifiedChunkIndexes: readonly number[];
+}
+/**
+ * 把全文抽取、真实 embedding 与 Host authority commit 串成一个作者调用。
+ * 唯一持久化入口是 host.dispatchTool(world_apply)，不得直接写 Ladybug checkpoint。
+ */
+export declare function ingestProjectDocument(host: ProjectDocumentIngestionHost, source: NaturalLanguageSource, capability: ProjectDocumentIngestionCapability): Promise<ProjectDocumentIngestionReceipt>;