A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(editor): the agents setting opened an endpoint against a window with no hook
esenginef5b229a9c0d4
diff --git a/desktop/src/engine/automationGate.ts b/desktop/src/engine/automationGate.tsnew file mode 100644index 000000000..5ddd8c045--- /dev/null+++ b/desktop/src/engine/automationGate.ts@@ -0,0 +1,51 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file automationGate.ts+ * @brief When the editor's automation hook may exist — the one rule, in one+ * place, testable on its own.+ *+ * The hook (`window.__estellaEditor`) is the UNCURATED door: project, asset,+ * play, document and command operations, next to the scene surface. Plugin code+ * shares that realm and is deliberately handed a curated subset instead+ * (src/plugins/types.ts), so publishing the hook unconditionally would quietly+ * widen what a plugin can reach. It is therefore published only while a driver+ * is actually authorized.+ *+ * Two authorizations, arriving differently: a launch flag (ESTELLA_SHOT /+ * --mcp), which is in the URL before the first paint and holds for the session,+ * and the editor setting, which can open the endpoint at any later moment — a+ * boot replay, or a click — and can close it again.+ *+ * Kept free of `window` on purpose. The renderer supplies publish/retract, so+ * the rule is exercised in the pure-node suite rather than only in an editor+ * nobody can boot from a test — which is exactly how a listening endpoint once+ * came up against a window that had never published the hook at all.+ */++/**+ * Publish the hook exactly while `authorized()` is true, re-checking whenever+ * `subscribe` fires. Transitions only: repeated notifications with an unchanged+ * answer do nothing, so a status bump does not rebuild the hook under a driver+ * that is mid-call.+ *+ * @returns an unsubscribe, for a realm that is torn down (a popped-out window).+ */+export function guardAutomationHook(+ authorized: () => boolean,+ subscribe: (fn: () => void) => () => void,+ publish: () => void,+ retract: () => void,+): () => void {+ let published = false;+ const sync = (): void => {+ const want = authorized();+ if (want === published) return;+ published = want;+ if (want) publish();+ else retract();+ };+ const stop = subscribe(sync);+ sync();+ return stop;+}diff --git a/desktop/src/main.tsx b/desktop/src/main.tsxindex 6f74646c9..3d4dd5598 100644--- a/desktop/src/main.tsx+++ b/desktop/src/main.tsx@@ -66,6 +66,8 @@ import { initPlugins } from './plugins/init';import { openAssetOfType, opensInEditor } from './project/assetOpen';import { DirtyRegistry } from './document/DirtyRegistry';import { initBackgroundThrottle } from './engine/backgroundThrottle';+import { mcpStatus, subscribeMcp } from './store/McpStore';+import { guardAutomationHook } from './engine/automationGate';// Register the built-in settings (side effect) and replay persisted ones.import './settings';import { applySettings } from './store/settingsStore';@@ -120,11 +122,14 @@ function requireInstance(entity: number): void {}}-// Automation hook (screenshots / visual-regression): with `?automation=1`, expose the-// minimum to drive the launcher→editor flow from a headless driver. Gated so the normal-// editor never carries it; mirrors the headless render host's `window.__estellaHeadless`.-if (new URLSearchParams(location.search).has('automation')) {- (window as unknown as { __estellaEditor?: unknown }).__estellaEditor = {+/**+ * The automation hook's contents — the project / asset / play / document doors a+ * driver reaches through surfaceDriver, alongside the scene surface. Mirrors the+ * headless render host's `window.__estellaHeadless`. When it may be published is+ * automationGate.ts's decision, not this function's.+ */+function buildEditorAutomation(): unknown {+ return {/*** The whole launcher → editor → scene-ready sequence, or a throw saying* which step failed.@@ -477,6 +482,18 @@ if (new URLSearchParams(location.search).has('automation')) {};}+// The launch flag holds for the session; the setting can open and close the+// endpoint at any moment, including a boot replay that lands after this module+// ran. McpStore already mirrors what main is doing, so watching it is enough —+// this needs no channel of its own.+const LAUNCH_AUTOMATION = new URLSearchParams(location.search).has('automation');+guardAutomationHook(+ () => LAUNCH_AUTOMATION || mcpStatus().running,+ subscribeMcp,+ () => { (window as unknown as { __estellaEditor?: unknown }).__estellaEditor = buildEditorAutomation(); },+ () => { delete (window as unknown as { __estellaEditor?: unknown }).__estellaEditor; },+);+// Tag the OS so the title bar renders the right chrome on first paint (macOS// reserves space for the native traffic lights; Windows/Linux draw our controls).const plat = window.estella?.platform;diff --git a/desktop/tests/automation-gate.test.ts b/desktop/tests/automation-gate.test.tsnew file mode 100644index 000000000..c01ac0884--- /dev/null+++ b/desktop/tests/automation-gate.test.ts@@ -0,0 +1,97 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file When the uncurated automation hook may be published. The regression+ * this exists for: the endpoint can be opened by a SETTING, long after+ * the window loaded and with no launch flag in its URL, and the hook has+ * to appear then too — a listening endpoint against a window that never+ * published it answers every tool call with a TypeError.+ */+import { describe, it, expect, beforeEach, vi } from 'vitest';+import { guardAutomationHook } from '@/engine/automationGate';++describe('the automation hook gate', () => {+ let publish: ReturnType<typeof vi.fn>;+ let retract: ReturnType<typeof vi.fn>;+ let listeners: Array<() => void>;+ let running: boolean;+ let launchFlag: boolean;++ /** Stands in for McpStore: notify, and the gate re-reads. */+ const subscribe = (fn: () => void) => {+ listeners.push(fn);+ return () => { listeners = listeners.filter((l) => l !== fn); };+ };+ const notify = () => listeners.forEach((l) => l());+ const guard = () => guardAutomationHook(+ () => launchFlag || running, subscribe, publish, retract,+ );++ beforeEach(() => {+ publish = vi.fn();+ retract = vi.fn();+ listeners = [];+ running = false;+ launchFlag = false;+ });++ it('publishes nothing for an ordinary editor', () => {+ guard();+ expect(publish).not.toHaveBeenCalled();+ });++ it('publishes at once when the window was launched for automation', () => {+ launchFlag = true;+ guard();+ expect(publish).toHaveBeenCalledTimes(1);+ });++ it('publishes when the SETTING opens the endpoint later', () => {+ guard();+ expect(publish).not.toHaveBeenCalled();+ running = true;+ notify();+ expect(publish).toHaveBeenCalledTimes(1);+ });++ it('publishes when the endpoint is already up before the gate runs', () => {+ // A boot replay of the setting can land before this module evaluates; the+ // gate reads the current answer rather than waiting for the next change.+ running = true;+ guard();+ expect(publish).toHaveBeenCalledTimes(1);+ });++ it('retracts the hook when the user revokes permission', () => {+ running = true;+ guard();+ running = false;+ notify();+ expect(retract).toHaveBeenCalledTimes(1);+ });++ it('keeps the launch-flag hook published even with no endpoint', () => {+ // Shot mode drives the hook directly and never opens an endpoint at all.+ launchFlag = true;+ guard();+ notify();+ expect(retract).not.toHaveBeenCalled();+ });++ it('acts on transitions only, so a status bump never rebuilds it mid-call', () => {+ running = true;+ guard();+ notify();+ notify();+ expect(publish).toHaveBeenCalledTimes(1);+ expect(retract).not.toHaveBeenCalled();+ });++ it('stops watching when the realm is torn down', () => {+ const stop = guard();+ stop();+ running = true;+ notify();+ expect(publish).not.toHaveBeenCalled();+ });+});