Skip to content

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.

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.ts
new file mode 100644
index 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.tsx
index 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.ts
new file mode 100644
index 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();
+ });
+});