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

package/dist/mcp-pipe-internal.js

@@ -0,0 +1,151 @@
+import { execFile } from "node:child_process";
+import { createServer } from "node:net";
+import { promisify } from "node:util";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { runAsyncProjectHostMcp } from "./mcp-async-dispatcher.js";
+import { createBoundedMcpLineQueue } from "./mcp-line-queue.js";
+import { handleProjectHostMcpRequest } from "./mcp.js";
+import { writeBoundedMcpPipeResponse } from "./mcp-pipe-response.js";
+import { LocalProjectHost } from "./project-host.js";
+const PIPE_HANDSHAKE_TIMEOUT_MS = 10_000;
+const PIPE_HELLO_KIND = "project_host_pipe_hello";
+const execFileAsync = promisify(execFile);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isProjectHostPipeHello(value) {
+    return isRecord(value)
+        && value.kind === PIPE_HELLO_KIND
+        && typeof value.windows_sid === "string"
+        && /^[A-Za-z0-9-]{4,256}$/.test(value.windows_sid)
+        && typeof value.project_id === "string"
+        && /^[A-Za-z0-9_-]{1,256}$/.test(value.project_id)
+        && typeof value.challenge === "string"
+        && /^[0-9a-f-]{36}$/i.test(value.challenge);
+}
+async function currentWindowsSid() {
+    if (process.platform !== "win32")
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "desktop pipe 仅支持 Windows");
+    const { stdout } = await execFileAsync("whoami", ["/user", "/fo", "csv", "/nh"], { windowsHide: true });
+    const sid = stdout
+        .split(",")
+        .map((value) => value.trim().replace(/^"|"$/g, ""))
+        .find((value) => /^S-1-[0-9-]+$/i.test(value));
+    if (sid === undefined)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Windows identity 不可用");
+    return sid;
+}
+async function pipeProjectId(cwd) {
+    const host = await LocalProjectHost.open(cwd);
+    try {
+        return (await host.inspect()).project_id;
+    }
+    finally {
+        await host.close();
+    }
+}
+/** T027 的 inherited-capability 内部入口；不由公开 package export 或 CLI 暴露。 */
+export async function runProjectHostMcpPipe(cwd, pipe, challenge, runtime = {}) {
+    if (!/^\\\\\.\\pipe\\worldengine-project-host-[0-9a-f-]{36}$/i.test(pipe) || !/^[0-9a-f-]{36}$/i.test(challenge)) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "desktop pipe 参数无效");
+    }
+    const [windowsSid, projectId] = await Promise.all([currentWindowsSid(), pipeProjectId(cwd)]);
+    return new Promise((resolvePromise, rejectPromise) => {
+        let settled = false;
+        let closeStarted = false;
+        let activeSocket;
+        let timeout;
+        const clearHandshakeTimeout = () => {
+            if (timeout === undefined)
+                return;
+            clearTimeout(timeout);
+            timeout = undefined;
+        };
+        const destroyActiveSocket = () => {
+            activeSocket?.destroy();
+            activeSocket = undefined;
+        };
+        const closeServer = (done) => {
+            if (closeStarted) {
+                done();
+                return;
+            }
+            closeStarted = true;
+            try {
+                server.close(() => done());
+            }
+            catch {
+                done();
+            }
+        };
+        const finish = (code, destroySocket = true) => {
+            if (settled)
+                return;
+            settled = true;
+            clearHandshakeTimeout();
+            if (destroySocket)
+                destroyActiveSocket();
+            closeServer(() => resolvePromise(code));
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearHandshakeTimeout();
+            destroyActiveSocket();
+            closeServer(() => rejectPromise(error));
+        };
+        const server = (runtime.createServer ?? createServer)((socket) => {
+            if (settled) {
+                socket.destroy();
+                return;
+            }
+            activeSocket = socket;
+            const lines = createBoundedMcpLineQueue(socket);
+            const iterator = lines.lines[Symbol.asyncIterator]();
+            void (async () => {
+                try {
+                    const first = await iterator.next();
+                    if (first.done) {
+                        socket.destroy();
+                        finish(1);
+                        return;
+                    }
+                    let hello;
+                    try {
+                        hello = JSON.parse(first.value);
+                    }
+                    catch {
+                        socket.destroy();
+                        finish(1);
+                        return;
+                    }
+                    if (!isProjectHostPipeHello(hello)
+                        || hello.windows_sid !== windowsSid
+                        || hello.project_id !== projectId
+                        || hello.challenge !== challenge) {
+                        socket.destroy();
+                        finish(1);
+                        return;
+                    }
+                    clearHandshakeTimeout();
+                    const rest = { [Symbol.asyncIterator]: () => iterator };
+                    const code = await runAsyncProjectHostMcp(cwd, rest, (line) => writeBoundedMcpPipeResponse(socket, line, lines), () => undefined, undefined, handleProjectHostMcpRequest);
+                    socket.end();
+                    finish(code, false);
+                }
+                catch (error) {
+                    socket.destroy();
+                    fail(error);
+                }
+                finally {
+                    lines.close();
+                }
+            })();
+        });
+        server.maxConnections = 1;
+        server.once("error", fail);
+        timeout = setTimeout(() => finish(1), PIPE_HANDSHAKE_TIMEOUT_MS);
+        server.listen(pipe);
+    });
+}

package/dist/mcp-pipe-response.d.ts

@@ -0,0 +1,14 @@
+type PipeSocket = {
+    readonly write: (line: string) => boolean;
+    readonly once: (event: "drain" | "close" | "error", listener: () => void) => unknown;
+    readonly off: (event: "drain" | "close" | "error", listener: () => void) => unknown;
+    readonly destroy: () => void;
+};
+type PipeInputFlow = {
+    readonly pause: () => void;
+    readonly resume: () => void;
+    readonly close: () => void;
+};
+/** 内部 Desktop pipe 输出边界：JSON payload 不计 transport 追加的 LF delimiter。 */
+export declare function writeBoundedMcpPipeResponse(socket: PipeSocket, line: string, input: PipeInputFlow): Promise<void>;
+export {};

package/dist/mcp-pipe-response.js

@@ -0,0 +1,50 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { MCP_MAX_LINE_BYTES } from "./mcp-line-queue.js";
+const PIPE_DRAIN_TIMEOUT_MS = 10_000;
+function waitForPipeDrain(socket) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            socket.off("drain", onDrain);
+            socket.off("close", onClose);
+            socket.off("error", onError);
+        };
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error === undefined)
+                resolvePromise();
+            else
+                rejectPromise(error);
+        };
+        const onDrain = () => finish();
+        const onClose = () => finish(new AuthoringBridgeError("E_PROJECT_BUSY", "desktop pipe closed during backpressure"));
+        const onError = () => finish(new AuthoringBridgeError("E_PROJECT_BUSY", "desktop pipe failed during backpressure"));
+        const timer = setTimeout(() => finish(new AuthoringBridgeError("E_PROJECT_BUSY", "desktop pipe backpressure timeout")), PIPE_DRAIN_TIMEOUT_MS);
+        socket.once("drain", onDrain);
+        socket.once("close", onClose);
+        socket.once("error", onError);
+    });
+}
+/** 内部 Desktop pipe 输出边界：JSON payload 不计 transport 追加的 LF delimiter。 */
+export async function writeBoundedMcpPipeResponse(socket, line, input) {
+    const payload = line.endsWith("\n") ? line.slice(0, -1) : line;
+    if (Buffer.byteLength(payload, "utf8") > MCP_MAX_LINE_BYTES) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "desktop pipe response exceeds limit");
+    }
+    if (socket.write(line))
+        return;
+    input.pause();
+    try {
+        await waitForPipeDrain(socket);
+        input.resume();
+    }
+    catch (error) {
+        input.close();
+        socket.destroy();
+        throw error;
+    }
+}

package/dist/mcp-stdio-response.d.ts

@@ -0,0 +1,12 @@
+type StdioOutput = {
+    readonly write: (line: string) => boolean;
+    readonly once: (event: "drain" | "close" | "error", listener: () => void) => unknown;
+    readonly off: (event: "drain" | "close" | "error", listener: () => void) => unknown;
+};
+type InputFlow = {
+    readonly pause: () => void;
+    readonly resume: () => void;
+    readonly close: () => void;
+};
+export declare function writeBoundedMcpStdioResponse(output: StdioOutput, line: string, input: InputFlow): Promise<void>;
+export {};

package/dist/mcp-stdio-response.js

@@ -0,0 +1,27 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+const STDIO_DRAIN_TIMEOUT_MS = 10_000;
+export async function writeBoundedMcpStdioResponse(output, line, input) {
+    if (output.write(line))
+        return;
+    input.pause();
+    await new Promise((resolvePromise, rejectPromise) => {
+        let settled = false;
+        const cleanup = () => { clearTimeout(timer); output.off("drain", drain); output.off("close", fail); output.off("error", fail); };
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error === undefined)
+                resolvePromise();
+            else
+                rejectPromise(error);
+        };
+        const drain = () => finish();
+        const fail = () => finish(new AuthoringBridgeError("E_PROJECT_BUSY", "stdio output backpressure"));
+        const timer = setTimeout(fail, STDIO_DRAIN_TIMEOUT_MS);
+        output.once("drain", drain);
+        output.once("close", fail);
+        output.once("error", fail);
+    }).then(() => input.resume(), (error) => { input.close(); throw error; });
+}

package/dist/mcp.d.ts

@@ -0,0 +1,27 @@
+import type { LocalProjectHost, LocalProjectHostOptions } from "./project-host.js";
+export interface McpRequest {
+    readonly jsonrpc: "2.0";
+    readonly id?: string | number | null;
+    readonly method: string;
+    readonly params?: unknown;
+}
+interface McpSuccess {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly result: Record<string, unknown>;
+}
+interface McpFailure {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+        readonly data?: Record<string, unknown>;
+    };
+}
+export type McpResponse = McpSuccess | McpFailure;
+export declare const MAX_MCP_IMAGE_BYTES: number;
+export declare function handleProjectHostMcpRequest(host: LocalProjectHost, request: unknown): Promise<McpResponse | undefined>;
+export declare function runProjectHostMcp(cwd: string, lines: AsyncIterable<string>, write: (line: string) => void, writeError: (line: string) => void, onReady?: () => void, hostOptions?: LocalProjectHostOptions): Promise<number>;
+export declare function runProjectHostMcpStdio(cwd: string, onReady?: () => void, hostOptions?: LocalProjectHostOptions): Promise<number>;
+export {};

package/dist/mcp.js

@@ -0,0 +1,194 @@
+import { AUTHORING_BRIDGE_TOOLS, AuthoringBridgeError, authoringToolDescriptor, } from "@world-engines/authoring-bridge";
+import { PROJECT_HOST_MCP_INSTRUCTIONS } from "@world-engines/agent-kit";
+import { createBoundedMcpLineQueue } from "./mcp-line-queue.js";
+import { runAsyncProjectHostMcp } from "./mcp-async-dispatcher.js";
+import { writeBoundedMcpStdioResponse } from "./mcp-stdio-response.js";
+import { toPublicError } from "./public-error.js";
+const MCP_PROTOCOL_VERSION = "2025-03-26";
+export const MAX_MCP_IMAGE_BYTES = 4 * 1024 * 1024;
+const MCP_TOOLS = AUTHORING_BRIDGE_TOOLS.map((descriptor) => ({
+    name: descriptor.name,
+    description: `AuthoringBridge registered tool ${descriptor.name}`,
+    annotations: {
+        readOnlyHint: !descriptor.project_effect && descriptor.name !== "ask_user" && descriptor.name !== "preview_interact",
+        destructiveHint: descriptor.project_effect,
+    },
+    inputSchema: descriptor.project_effect
+        ? {
+            ...descriptor.input_schema,
+            required: [...(descriptor.input_schema.required ?? []), "operation_id", "expected_project_revision"],
+            properties: {
+                ...(descriptor.input_schema.properties ?? {}),
+                operation_id: { type: "string", minLength: 1 },
+                expected_project_revision: { type: "integer", minimum: 0 },
+            },
+        }
+        : descriptor.input_schema,
+}));
+function listedTools(host) {
+    return MCP_TOOLS.map((tool) => {
+        const available = host.isToolAvailable(tool.name);
+        return {
+            ...tool,
+            description: available
+                ? tool.description
+                : `${tool.description}; runtime unavailable: no real Desktop/terminal callback transport`,
+            _meta: {
+                "worldengine/toolAvailability": available ? "available" : "unavailable",
+                ...(available ? {} : { "worldengine/unavailableCode": "E_CAPABILITY_UNAVAILABLE" }),
+            },
+        };
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function responseId(request) {
+    return request.id ?? null;
+}
+function success(request, result) {
+    return { jsonrpc: "2.0", id: responseId(request), result };
+}
+function failure(request, code, message, data) {
+    return {
+        jsonrpc: "2.0",
+        id: responseId(request),
+        error: { code, message, ...(data === undefined ? {} : { data }) },
+    };
+}
+function invalidRequest() {
+    return {
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32600, message: "Invalid Request" },
+    };
+}
+function isRequestId(value) {
+    return value === undefined || value === null || typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+}
+function isMcpRequest(value) {
+    return isRecord(value)
+        && value.jsonrpc === "2.0"
+        && typeof value.method === "string"
+        && isRequestId(value.id);
+}
+function asArguments(params) {
+    if (!isRecord(params) || !isRecord(params.arguments)) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "tools/call 必须提供 object arguments");
+    }
+    return params.arguments;
+}
+function toAuthoringToolCall(name, argumentsValue) {
+    const descriptor = authoringToolDescriptor(name);
+    if (!descriptor.project_effect)
+        return { name: name, input: argumentsValue };
+    const { operation_id, expected_project_revision, ...input } = argumentsValue;
+    return {
+        name: name,
+        input,
+        effect_identity: { operation_id: operation_id, expected_project_revision: expected_project_revision },
+    };
+}
+function extractMcpImage(name, value) {
+    if (name !== "preview_inspect" || !isRecord(value) || !isRecord(value.screenshot)) {
+        return { structured: value };
+    }
+    const screenshot = value.screenshot;
+    const mimeType = screenshot.mime_type;
+    const data = screenshot.data_base64;
+    const byteLength = screenshot.byte_length;
+    if ((mimeType !== "image/png" && mimeType !== "image/jpeg" && mimeType !== "image/webp")
+        || typeof data !== "string"
+        || !Number.isSafeInteger(byteLength)
+        || byteLength < 0
+        || byteLength > MAX_MCP_IMAGE_BYTES
+        || data.length > Math.ceil(MAX_MCP_IMAGE_BYTES / 3) * 4 + 4
+        || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(data)) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "preview screenshot 不是受支持的有界图片");
+    }
+    const decoded = Buffer.from(data, "base64");
+    if (decoded.byteLength !== byteLength) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "preview screenshot byte_length 与图片不一致");
+    }
+    const { data_base64: _dataBase64, ...boundedScreenshot } = screenshot;
+    return {
+        structured: { ...value, screenshot: boundedScreenshot },
+        image: { data, mimeType, byteLength },
+    };
+}
+function toolResult(name, value) {
+    const extracted = extractMcpImage(name, value);
+    const serialized = JSON.stringify(extracted.structured);
+    return {
+        content: [
+            { type: "text", text: serialized },
+            ...(extracted.image === undefined
+                ? []
+                : [{ type: "image", data: extracted.image.data, mimeType: extracted.image.mimeType }]),
+        ],
+        structuredContent: extracted.structured,
+    };
+}
+function initializeResult(params) {
+    const requestedVersion = isRecord(params) && typeof params.protocolVersion === "string"
+        ? params.protocolVersion
+        : undefined;
+    return {
+        protocolVersion: requestedVersion === MCP_PROTOCOL_VERSION ? requestedVersion : MCP_PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: {
+            name: "worldengine-project-host",
+            version: "0.1.0-alpha.0",
+        },
+        instructions: PROJECT_HOST_MCP_INSTRUCTIONS,
+    };
+}
+export async function handleProjectHostMcpRequest(host, request) {
+    if (!isMcpRequest(request))
+        return invalidRequest();
+    if (request.id === undefined) {
+        if (request.method === "notifications/initialized")
+            return undefined;
+        return undefined;
+    }
+    try {
+        if (request.method === "initialize")
+            return success(request, initializeResult(request.params));
+        if (request.method === "tools/list")
+            return success(request, { tools: listedTools(host) });
+        if (request.method !== "tools/call")
+            return failure(request, -32601, "Method not found");
+        if (!isRecord(request.params) || typeof request.params.name !== "string") {
+            return failure(request, -32602, "Invalid params");
+        }
+        const params = request.params;
+        const name = params.name;
+        const args = asArguments(params);
+        if (!MCP_TOOLS.some((tool) => tool.name === name))
+            return failure(request, -32602, "Invalid params");
+        return success(request, toolResult(name, await host.dispatchTool(toAuthoringToolCall(name, args))));
+    }
+    catch (error) {
+        const publicError = toPublicError(error);
+        return failure(request, error instanceof AuthoringBridgeError ? -32602 : -32603, "Request failed", {
+            code: publicError.code,
+            details: publicError.details,
+        });
+    }
+}
+async function runProjectHostMcpWithAsyncWriter(cwd, lines, write, writeError, onReady, hostOptions = {}) {
+    return runAsyncProjectHostMcp(cwd, lines, write, writeError, onReady, handleProjectHostMcpRequest, hostOptions);
+}
+export async function runProjectHostMcp(cwd, lines, write, writeError, onReady, hostOptions = {}) {
+    return runProjectHostMcpWithAsyncWriter(cwd, lines, async (line) => { write(line); }, writeError, onReady, hostOptions);
+}
+export async function runProjectHostMcpStdio(cwd, onReady, hostOptions = {}) {
+    // 首帧可能在项目 authority 打开完成前到达；必须立即订阅并缓存，不能等 async iterator 首次消费。
+    const stdio = createBoundedMcpLineQueue(process.stdin);
+    try {
+        return await runProjectHostMcpWithAsyncWriter(cwd, stdio.lines, (line) => writeBoundedMcpStdioResponse(process.stdout, line, stdio), (line) => process.stderr.write(line), onReady, hostOptions);
+    }
+    finally {
+        stdio.close();
+    }
+}

package/dist/prepared-embedding-cache.d.ts

@@ -0,0 +1,38 @@
+import { type FrozenArtifactEmbeddingBatch } from "@world-engines/scenario-review-snapshot";
+import type { AuthoringEmbeddingPort } from "./authoring-model-connection.js";
+import { type GraphProjectionReadback, type PreparedAuthoringRecallSnapshot } from "./desktop-authoring-runtime.js";
+import type { ScenarioSourceReadback } from "./scenario-writer.js";
+/** 仅由显式 frozen-review embed 步骤写入；普通 search 不会生成 corpus vector。 */
+export declare function persistPreparedFrozenEmbeddingBatch(options: Readonly<{
+    projectRoot: string;
+    projectId: string;
+    runBatch: FrozenArtifactEmbeddingBatch;
+}>): FrozenArtifactEmbeddingBatch;
+export interface LocalRecallPreparationHost {
+    readonly root: string;
+    readSourceReadback(): Promise<ScenarioSourceReadback>;
+    readGraphProjectionReadback(): Promise<GraphProjectionReadback>;
+}
+/**
+ * 只消费本地 WESP 的当前只读图投影并准备 corpus 向量；不依赖 review capture、远端
+ * source-ready 或结构化模型。写入前后的 revision/source CAS 仍由同一持久化模块检查。
+ */
+export declare function prepareLocalRecallSnapshot(host: LocalRecallPreparationHost, embedding: AuthoringEmbeddingPort & Readonly<{
+    origin: string;
+    assertCurrentAccount?: () => Promise<void>;
+}>, options?: Readonly<{
+    scopeId?: string;
+    signal?: AbortSignal;
+    assertCurrentAccount?: () => Promise<void>;
+}>): Promise<PreparedAuthoringRecallSnapshot>;
+/** 从 review prepare 已写入的 metadata + embedding cache 只读重建 formal snapshot。 */
+export declare function createPreparedEmbeddingSnapshotReader(options: Readonly<{
+    projectRoot: string;
+    projectId: string;
+    embedding: AuthoringEmbeddingPort & Readonly<{
+        origin?: string;
+        assertCurrentAccount?: () => Promise<void>;
+    }>;
+    origin: string;
+    assertCurrentAccount?: () => Promise<void>;
+}>): NonNullable<import("./desktop-authoring-runtime.js").DesktopAuthoringCapabilities["get_prepared_embedding_snapshot"]>;