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.

feat(agent): capabilities — a layer of intent above the tool catalog

yhh83bf13eebb0a
diff --git a/desktop/package.json b/desktop/package.json
index 8d529f96a..93247c34c 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -23,6 +23,7 @@
"editor:mcp:build": "vite build && node scripts/editor-mcp.mjs",
"editor:mcp:e2e": "vite build && node scripts/editor-mcp-e2e.mjs",
"editor:mcp:editor-e2e": "vite build && node scripts/editor-mcp-editor-e2e.mjs",
+ "editor:capabilities-e2e": "vite build && node scripts/editor-capabilities-e2e.mjs",
"editor:shot": "vite build && electron .",
"verify:render:spine": "node ../tools/verify-render.mjs --only spine",
"verify:render:particles": "node ../tools/verify-render.mjs --only particles",
diff --git a/desktop/scripts/editor-capabilities-e2e.mjs b/desktop/scripts/editor-capabilities-e2e.mjs
new file mode 100644
index 000000000..5a1efcbad
--- /dev/null
+++ b/desktop/scripts/editor-capabilities-e2e.mjs
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file editor-capabilities-e2e.mjs — a capability does on a real editor what
+ * its unit tests say it dispatches.
+ *
+ * The unit tests drive a fake driver: they prove a capability calls the
+ * tools it means to, in order, and inherits their gates. What they cannot
+ * prove is that those calls do the intended thing to a scene — that
+ * `RigidBody.bodyType` is a field that exists, that an enum arrives as a
+ * name and lands as the right member, that a subtree built by one step is
+ * addressable by the next. Every bug this repo has had in the automation
+ * surface was of that shape: the call succeeded and the scene disagreed.
+ *
+ * Run from desktop/: node scripts/editor-capabilities-e2e.mjs
+ */
+import { cp, mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { withEditor, checker } from './lib/editorDriver.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const EXAMPLE = path.resolve(HERE, '..', '..', 'examples', 'space-shooter');
+
+// A throwaway copy: these capabilities write prefabs and scripts into the
+// project, and an e2e that dirties a shipped example is one nobody reruns.
+const tmpRoot = await mkdtemp(path.join(os.tmpdir(), 'estella-cap-e2e-'));
+const project = path.join(tmpRoot, 'game');
+await cp(EXAMPLE, project, {
+ recursive: true,
+ filter: (src) => !/[/\\](\.esengine|node_modules|dist)([/\\]|$)/.test(src),
+});
+
+const json = (reply) => {
+ const text = reply?.text ?? reply;
+ try { return JSON.parse(text); } catch { return text; }
+};
+
+const failures = await withEditor(async (ed) => {
+ const check = checker();
+
+ const tools = (await ed.rpc('tools/list', {}, 30000)).result?.tools ?? [];
+ const names = tools.map((t) => t.name);
+ for (const cap of ['create_prefab', 'configure_physics_body', 'wire_ui_event', 'create_behavior']) {
+ check(names.includes(cap), `tools/list is missing the capability ${cap}`);
+ }
+ console.log(`tools/list OK — ${names.length} entries, capabilities among them`);
+
+ await ed.call('open_project', { root: project }, 180_000);
+ console.log('open_project OK');
+
+ // — configure_physics_body: two components and their fields, from one call —
+ const built = json(await ed.call('apply_scene_ops', {
+ ops: [{ op: 'create', ref: 'body', name: 'CapBody', components: ['Transform'], x: 0, y: 0 }],
+ }, 30000));
+ const entity = built?.refs?.body;
+ check(typeof entity === 'number', `apply_scene_ops gave no entity: ${JSON.stringify(built)}`);
+
+ const physics = json(await ed.call('configure_physics_body', {
+ entity, body: 'kinematic', shape: 'circle', size: 2.5, sensor: true, gravityScale: 0,
+ }, 30000));
+ check(physics?.collider === 'CircleCollider', `configure_physics_body: ${JSON.stringify(physics)}`);
+
+ const after = json(await ed.call('get_inspector', { entity }, 30000));
+ const components = new Map((after?.components ?? []).map((c) => [c.type, c]));
+ check(components.has('RigidBody'), 'configure_physics_body left no RigidBody');
+ check(components.has('CircleCollider'), 'configure_physics_body left no CircleCollider');
+
+ const field = (type, key) => (components.get(type)?.fields ?? []).find((f) => f.key === key)?.value;
+ // The enum went over as the NAME "kinematic"; what matters is the member it landed on.
+ check(String(field('RigidBody', 'bodyType')).toLowerCase().includes('kinematic')
+ || field('RigidBody', 'bodyType') === 1,
+ `bodyType did not become kinematic: ${JSON.stringify(field('RigidBody', 'bodyType'))}`);
+ check(field('RigidBody', 'gravityScale') === 0, `gravityScale: ${field('RigidBody', 'gravityScale')}`);
+ check(field('CircleCollider', 'radius') === 2.5, `radius: ${field('CircleCollider', 'radius')}`);
+ check(field('CircleCollider', 'isSensor') === true, `isSensor: ${field('CircleCollider', 'isSensor')}`);
+ console.log('configure_physics_body OK — RigidBody + CircleCollider, fields as asked');
+
+ // Idempotent: running it again must not add a second RigidBody.
+ await ed.call('configure_physics_body', { entity, body: 'dynamic' }, 30000);
+ const twice = json(await ed.call('get_inspector', { entity }, 30000));
+ const bodies = (twice?.components ?? []).filter((c) => c.type === 'RigidBody').length;
+ check(bodies === 1, `running it twice left ${bodies} RigidBody components`);
+ console.log('configure_physics_body OK — repeatable, still one body');
+
+ // — create_prefab: subtree in, reusable asset out —
+ const prefab = json(await ed.call('create_prefab', {
+ name: 'CapCoin',
+ replace: true,
+ ops: [
+ { op: 'create', ref: 'root', name: 'temp', components: ['Transform'] },
+ { op: 'create', ref: 'child', name: 'Face', parent: '$root', components: ['Transform'] },
+ ],
+ }, 60000));
+ check(typeof prefab?.entity === 'number', `create_prefab gave no entity: ${JSON.stringify(prefab)}`);
+ check(String(prefab?.prefab ?? '').startsWith('@uuid:'), `create_prefab gave no uuid ref: ${JSON.stringify(prefab)}`);
+
+ const templates = json(await ed.call('list_entity_templates', {}, 30000));
+ const ids = (Array.isArray(templates) ? templates : templates?.templates ?? []).map((t) => t.id ?? t);
+ check(ids.includes(prefab.template), `the extracted prefab is not offered as ${prefab.template}`);
+ console.log(`create_prefab OK — ${prefab.template} is instantiable`);
+
+ // — wire_ui_event: adds rather than replaces —
+ const wired1 = json(await ed.call('wire_ui_event', {
+ entity, event: 'click', action: 'ui.setVisible', params: { visible: false },
+ }, 30000));
+ check(wired1?.rows === 1, `first wire: ${JSON.stringify(wired1)}`);
+ const wired2 = json(await ed.call('wire_ui_event', { entity, event: 'click', action: 'fsm.fire' }, 30000));
+ check(wired2?.rows === 2, `second wire did not ADD to the first: ${JSON.stringify(wired2)}`);
+ const rows = json(await ed.call('get_event_bindings', { entity }, 30000));
+ check(Array.isArray(rows) && rows.length === 2, `bindings read back: ${JSON.stringify(rows)}`);
+ console.log('wire_ui_event OK — two wires, neither dropped');
+
+ // A capability's failure names the step, not just the message.
+ const bad = await ed.call('configure_physics_body', { entity: 999999, body: 'dynamic' }, 30000).catch((e) => ({ text: String(e) }));
+ check(/step /.test(String(bad?.text ?? '')), `a failing capability did not name its step: ${JSON.stringify(bad)}`);
+ console.log('capability failures name their step');
+
+ return check.failures;
+});
+
+await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+process.exit(failures > 0 ? 1 : 0);
diff --git a/desktop/shared/capabilityCatalog.mjs b/desktop/shared/capabilityCatalog.mjs
new file mode 100644
index 000000000..ed47d705b
--- /dev/null
+++ b/desktop/shared/capabilityCatalog.mjs
@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file capabilityCatalog.mjs
+ * Semantic capabilities — the layer above the tool catalog.
+ *
+ * A tool is an atom: set_field, add_component, create_entity. A model
+ * reasoning in atoms spends its reasoning on assembly. A CAPABILITY is
+ * the thing a person would ask for — "make this a physics body", "wire
+ * this button" — named once, so the model reasons about the game instead.
+ *
+ * THE CONSTRAINT THAT MAKES THIS SAFE: a capability is a program over
+ * DECLARED TOOLS and nothing else. Its `run` receives one argument it can
+ * act through — `call(tool, input)` — and no editor surface, no imports,
+ * no store. So a capability cannot add editing truth, cannot skip
+ * validation, and cannot behave differently from the UI doing the same
+ * thing; it can only sequence what already exists.
+ *
+ * That is not a style rule. The last time two doors reached the same
+ * operation by different routes, one of them silently created prefab
+ * COPIES while reporting success (see sceneOps.ts). A capability layer
+ * implemented as "helper functions that call the surface" would be that
+ * bug with a bigger surface area; `check-capabilities.mjs` holds the line
+ * by refusing a step that names a tool the catalog does not have.
+ *
+ * UI, Agent and MCP therefore stay one path:
+ *
+ * Capabilities → Tools → EditorControlSurface
+ * ↑ ↑
+ * UI/Agent/MCP UI/Agent/MCP
+ */
+
+const obj = (properties, required = []) => ({ type: 'object', properties, required });
+
+/**
+ * Every capability, in the order a model should meet them.
+ *
+ * `effect` follows the same tiers as tools and must be the WORST of the steps it
+ * runs: a capability that writes a file is irreversible however undoable its
+ * other steps are, because that is the one an undo cannot rescue.
+ */
+export const CAPABILITIES = [
+ {
+ name: 'create_prefab',
+ effect: 'irreversible',
+ description:
+ 'Build an entity subtree and extract it as a reusable `.esprefab` in one step — the whole point being that '
+ + 'what you build once becomes an INSTANCE everywhere else (the scene stores a delta, not a copy). '
+ + '`ops` is an apply_scene_ops program; name its root with `ref: "root"` (or pass `rootRef`). '
+ + 'Returns the prefab ref and the template id to create instances with.',
+ schema: obj({
+ name: { type: 'string', description: 'the prefab asset name — also the root entity name' },
+ ops: { type: 'object', description: 'apply_scene_ops program building the subtree' },
+ rootRef: { type: 'string', description: 'which ref is the subtree root (default "root")' },
+ replace: { type: 'boolean', description: 'overwrite an existing prefab of this name, keeping its uuid' },
+ }, ['name', 'ops']),
+ async run(input, call) {
+ const rootRef = input.rootRef ?? 'root';
+ const built = await call('apply_scene_ops', { ops: input.ops });
+ const root = built?.refs?.[rootRef];
+ if (root == null) {
+ throw new Error(
+ `create_prefab: the program defined no ref "${rootRef}" — give the root op \`ref: "${rootRef}"\``
+ + `${built?.refs ? ` (it defined: ${Object.keys(built.refs).join(', ') || 'none'})` : ''}`,
+ );
+ }
+ await call('rename_entity', { id: root, name: input.name });
+ const prefab = await call('create_prefab_from_entity', { entity: root, replace: input.replace === true });
+ return { entity: root, prefab, template: `prefab:assets/prefabs/${input.name}.esprefab`, refs: built.refs };
+ },
+ },
+
+ {
+ name: 'configure_physics_body',
+ effect: 'undoable',
+ description:
+ 'Make an entity a physics body with a collider, in the terms physics is discussed in rather than in component '
+ + 'fields: `body` is "dynamic" | "kinematic" | "static", `shape` is "box" | "circle". Adds RigidBody and the '
+ + 'collider if absent and sets them together, so an entity is never left half-configured — a body with no '
+ + 'collider falls through the world, which looks like a physics bug and is a missing second component.',
+ schema: obj({
+ entity: { type: 'number' },
+ body: { type: 'string', description: 'dynamic | kinematic | static (default dynamic)' },
+ shape: { type: 'string', description: 'box | circle (default box)' },
+ size: { type: ['number', 'array'], description: 'box half-extents [w, h], or a circle radius' },
+ sensor: { type: 'boolean', description: 'a trigger: reports contacts, blocks nothing' },
+ gravityScale: { type: 'number' },
+ fixedRotation: { type: 'boolean' },
+ }, ['entity']),
+ async run(input, call) {
+ // The body type goes over as its NAME. set_field resolves an enum by label
+ // already, so an ordinal table here would be a second copy of the enum —
+ // right until someone inserts a member and only this file still says 2.
+ const BODIES = ['static', 'kinematic', 'dynamic'];
+ const body = input.body ?? 'dynamic';
+ if (!BODIES.includes(body)) throw new Error(`configure_physics_body: body must be one of ${BODIES.join(', ')}`);
+ const shape = input.shape ?? 'box';
+ const collider = shape === 'circle' ? 'CircleCollider' : shape === 'box' ? 'BoxCollider' : null;
+ if (!collider) throw new Error('configure_physics_body: shape must be "box" or "circle"');
+
+ const before = await call('get_entity', { id: input.entity });
+ const has = (type) => Array.isArray(before?.components) && before.components.some((c) => (c.type ?? c) === type);
+
+ const ops = [];
+ if (!has('RigidBody')) ops.push({ op: 'add_component', entity: input.entity, component: 'RigidBody' });
+ if (!has(collider)) ops.push({ op: 'add_component', entity: input.entity, component: collider });
+
+ const fields = { 'RigidBody.bodyType': body };
+ if (input.gravityScale !== undefined) fields['RigidBody.gravityScale'] = input.gravityScale;
+ if (input.fixedRotation !== undefined) fields['RigidBody.fixedRotation'] = input.fixedRotation;
+ if (input.sensor !== undefined) fields[`${collider}.isSensor`] = input.sensor;
+ if (input.size !== undefined) {
+ if (shape === 'circle') fields['CircleCollider.radius'] = input.size;
+ else fields['BoxCollider.halfExtents'] = input.size;
+ }
+ ops.push({ op: 'set', entity: input.entity, fields });
+
+ await call('apply_scene_ops', { ops });
+ return { entity: input.entity, body, collider };
+ },
+ },
+
+ {
+ name: 'wire_ui_event',
+ effect: 'undoable',
+ description:
+ 'Give an entity behaviour without code by wiring one event to one action, ADDING to what it already has rather '
+ + 'than replacing it — which is the difference from set_event_bindings, whose whole-list semantics silently drop '
+ + 'the wires you did not resend. `event` is "click", "pointerEnter", … and `action` is any name in the action '
+ + 'registry (property.set, ui.setVisible, fsm.fire, or one the project registered). Pass `replace` to mean the '
+ + 'old behaviour deliberately.',
+ schema: obj({
+ entity: { type: 'number' },
+ event: { type: 'string' },
+ action: { type: 'string' },
+ params: { type: 'object' },
+ target: { type: 'string', description: 'another entity by name to run the action on' },
+ replace: { type: 'boolean', description: 'drop the existing wires instead of adding to them' },
+ }, ['entity', 'event', 'action']),
+ async run(input, call) {
+ const existing = input.replace === true ? [] : (await call('get_event_bindings', { entity: input.entity })) ?? [];
+ const rows = Array.isArray(existing) ? [...existing] : [];
+ rows.push({
+ event: input.event,
+ action: input.action,
+ ...(input.params ? { params: input.params } : {}),
+ ...(input.target ? { target: input.target } : {}),
+ });
+ await call('set_event_bindings', { entity: input.entity, rows });
+ return { entity: input.entity, rows: rows.length };
+ },
+ },
+
+ {
+ name: 'create_behavior',
+ effect: 'irreversible',
+ description:
+ 'Author a gameplay behaviour and attach it. A behaviour is a component plus its update loop, and getting one into '
+ + 'a project is three steps that each look complete on their own: create_script makes the file AND wires it into '
+ + "the project's declaration entry (a .ts file nothing imports is a file the editor never sees), write_project_file "
+ + 'puts your logic in it, and the component still has to be ADDED to something. Doing one or two of those is how a '
+ + 'behaviour ends up existing and doing nothing. Returns the path and the TypeScript errors in it.',
+ schema: obj({
+ name: { type: 'string', description: 'behaviour name, e.g. "EnemyChase" — also the component name' },
+ state: { type: 'object', description: 'per-entity tunable state, as a default-valued object literal' },
+ update: { type: 'string', description: 'the body of update(ctx, dt) — TypeScript source' },
+ attachTo: { type: 'object', description: 'entity ids to put the behaviour on' },
+ }, ['name', 'update']),
+ async run(input, call) {
+ const state = JSON.stringify(input.state ?? {}, null, 4).replace(/\n/g, '\n ');
+ const source = [
+ `import { defineBehavior } from 'esengine';`,
+ '',
+ `export const ${input.name} = defineBehavior('${input.name}', {`,
+ ` state: ${state},`,
+ ' update(ctx, dt) {',
+ ...String(input.update).split('\n').map((line) => ` ${line}`),
+ ' },',
+ '});',
+ '',
+ ].join('\n');
+
+ // create_script FIRST, for its wiring: it registers the module in the
+ // project's declaration entry, which is what makes the component addable
+ // at all. write_project_file then replaces the scaffold it wrote.
+ const made = await call('create_script', { kind: 'component', name: input.name });
+ if (!made?.ok || !made.path) {
+ throw new Error(`create_behavior: ${made?.error ?? 'create_script did not report a path'}`);
+ }
+ const written = await call('write_project_file', { path: made.path, content: source });
+
+ const attach = Array.isArray(input.attachTo) ? input.attachTo : [];
+ if (attach.length > 0) {
+ await call('apply_scene_ops', {
+ ops: attach.map((entity) => ({ op: 'add_component', entity, component: input.name })),
+ });
+ }
+ return {
+ name: input.name,
+ path: made.path,
+ wiredInto: made.wiredInto,
+ errors: written?.errors ?? [],
+ attached: attach.length,
+ };
+ },
+ },
+];
+
+export const capabilityByName = (name) => CAPABILITIES.find((c) => c.name === name);
+
+/** Same shape `listTools` produces, so a front serves both from one list. */
+export function listCapabilities(allowWrites = false) {
+ return CAPABILITIES.filter((c) => allowWrites || (c.effect ?? 'read') === 'read')
+ .map((c) => ({ name: c.name, description: c.description, inputSchema: c.schema }));
+}
+
+/**
+ * The tools each capability calls, read off its own source rather than declared
+ * beside it — a declaration is a second thing to keep in sync. The gate proves
+ * each name exists and that `effect` is no gentler than the steps.
+ */
+export function capabilityStepNames() {
+ return CAPABILITIES.map((cap) => ({
+ name: cap.name,
+ effect: cap.effect ?? 'read',
+ steps: [...new Set([...String(cap.run).matchAll(/call\(\s*'([a-z_]+)'/g)].map((m) => m[1]))].sort(),
+ }));
+}
diff --git a/desktop/shared/toolCatalog.mjs b/desktop/shared/toolCatalog.mjs
index fc2a00963..5bbc6789d 100644
--- a/desktop/shared/toolCatalog.mjs
+++ b/desktop/shared/toolCatalog.mjs
@@ -46,6 +46,8 @@
* silently rewrite a scene or a project.
*/
+import { CAPABILITIES } from './capabilityCatalog.mjs';
+
const obj = (properties, required = []) => ({ type: 'object', properties, required });
/** Whether `tool` mutates anything — the remote gate's question. Absent `effect`
@@ -75,7 +77,7 @@ const CAPTURE_PNG_JS = `(() => {
})()`;
/** name → { description, schema (JSON Schema), method (surface), args(input)→[] }. */
-export const TOOLS = [
+const ATOMS = [
{ name: 'load_scene',
description: 'FIXTURES ONLY: fetch a scene by URL into the headless World; returns the spawned entity count. '
+ 'With a project open this is the wrong door — a project path is not a URL and the fetch 404s: use open_scene, '
@@ -620,6 +622,16 @@ export const TOOLS = [
})})` },
];
+/**
+ * What every front serves: the atoms, then the capabilities above them. One list
+ * rather than two registries — a second would be a second place for a front to
+ * forget. A capability carries `run` instead of `method` / `js` / `op`.
+ */
+export const TOOLS = [...ATOMS, ...CAPABILITIES];
+
+/** Just the atoms — for anything reasoning about the primitive surface itself. */
+export { ATOMS };
+
/** MCP resources — read-only surface views an MCP client can subscribe to. */
export const RESOURCES = [
{ uri: 'editor://scene/tree', name: 'Scene tree', mimeType: 'application/json', method: 'getSceneTree' },
@@ -695,31 +707,47 @@ function validate(schema, raw) {
* `driver.op(op)`. A gated write without permission, a validation failure, or a
* driver throw becomes an `isError` result rather than a crash.
*/
+async function invokeTool(tool, driver, rawInput, allowWrites) {
+ if (mutates(tool) && !allowWrites) {
+ throw new Error(`tool ${tool.name} mutates the scene — start the server with ESTELLA_MCP_ALLOW_WRITES=1`);
+ }
+ const input = validate(tool.schema, rawInput);
+
+ // A CAPABILITY is a program over declared tools: handed `call` and nothing
+ // else, so every step goes back through this function — same validation, same
+ // write gate. It is not a way past a gate the client was refused.
+ if (tool.run) {
+ const call = async (name, stepInput) => {
+ const step = TOOLS.find((t) => t.name === name);
+ if (!step) throw new Error(`no such tool "${name}"`);
+ try {
+ return (await invokeTool(step, driver, stepInput, allowWrites)).data;
+ } catch (err) {
+ // Name the step. A capability is several calls deep and "component X is
+ // not on entity 12" otherwise says nothing about which part failed.
+ throw new Error(`step ${name}: ${err?.message ?? String(err)}`);
+ }
+ };
+ return { input, data: await tool.run(input, call) };
+ }
+
+ if (tool.op) return { input, data: await driver.op(tool.op, input) };
+ // A js template may DECLINE (return null) for inputs it has nothing special
+ // to do with, leaving the tool's typed `method` door to handle them — which
+ // is how a tool grows one alternate path without every call losing the door.
+ const js = tool.js ? tool.js(input) : null;
+ if (js) return { input, data: await driver.js(js) };
+ return { input, data: await driver(tool.method, tool.args(input), tool.root) };
+}
+
export async function runTool(tool, driver, rawInput, allowWrites = true) {
try {
- if (mutates(tool) && !allowWrites) {
- throw new Error(`tool ${tool.name} mutates the scene — start the server with ESTELLA_MCP_ALLOW_WRITES=1`);
- }
- const input = validate(tool.schema, rawInput);
+ const { input, data } = await invokeTool(tool, driver, rawInput, allowWrites);
// `image` may be a PREDICATE: one tool answers with a picture or with text
// depending on what the caller asked for (screenshot's `format: 'grid'`).
const wantsImage = typeof tool.image === 'function' ? tool.image(input) : tool.image;
- if (tool.op) {
- const data = await driver.op(tool.op, input);
- if (wantsImage) return { content: [{ type: 'image', data, mimeType: 'image/png' }] };
- return { content: [{ type: 'text', text: data === undefined ? 'ok' : JSON.stringify(data) }] };
- }
- // A js template may DECLINE (return null) for inputs it has nothing special
- // to do with, leaving the tool's typed `method` door to handle them — which
- // is how a tool grows one alternate path without every call losing the door.
- const js = tool.js ? tool.js(input) : null;
- if (js) {
- const data = await driver.js(js);
- if (wantsImage) return { content: [{ type: 'image', data, mimeType: 'image/png' }] };
- return { content: [{ type: 'text', text: data === undefined ? 'ok' : JSON.stringify(data) }] };
- }
- const result = await driver(tool.method, tool.args(input), tool.root);
- return { content: [{ type: 'text', text: result === undefined ? 'ok' : JSON.stringify(result) }] };
+ if (wantsImage) return { content: [{ type: 'image', data, mimeType: 'image/png' }] };
+ return { content: [{ type: 'text', text: data === undefined ? 'ok' : JSON.stringify(data) }] };
} catch (err) {
return { content: [{ type: 'text', text: `error: ${err?.message ?? String(err)}` }], isError: true };
}
diff --git a/desktop/tests/capabilities.test.ts b/desktop/tests/capabilities.test.ts
new file mode 100644
index 000000000..5e6071ffd
--- /dev/null
+++ b/desktop/tests/capabilities.test.ts
@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file capabilities.test.ts — a capability is a program over declared tools,
+ * dispatched by the same runTool every front already uses.
+ *
+ * The property under test is the one that keeps UI, Agent and MCP on one path:
+ * a capability reaches the editor ONLY through tools, so it inherits their
+ * validation and their write gate and cannot behave differently from the UI.
+ */
+import { describe, it, expect, vi } from 'vitest';
+// @ts-expect-error — plain-.mjs registries shared with the Electron MCP entry.
+import { TOOLS, ATOMS, runTool, listTools } from '../shared/toolCatalog.mjs';
+// @ts-expect-error — same.
+import { CAPABILITIES, capabilityStepNames } from '../shared/capabilityCatalog.mjs';
+
+interface Tool { name: string; effect?: string; run?: unknown; schema?: unknown; description?: string }
+
+const capability = (name: string): Tool => (TOOLS as Tool[]).find((t) => t.name === name)!;
+const text = (res: { content: Array<{ text: string }> }) => res.content[0].text;
+
+/** A driver that records every surface call and answers each method a script needs. */
+function fakeDriver(answers: Record<string, unknown> = {}) {
+ const calls: Array<{ method: string; args: unknown[] }> = [];
+ const driver = vi.fn(async (method: string, args: unknown[]) => {
+ calls.push({ method, args });
+ return answers[method];
+ }) as unknown as ((m: string, a: unknown[], r?: string) => Promise<unknown>) & {
+ js: ReturnType<typeof vi.fn>;
+ op: ReturnType<typeof vi.fn>;
+ };
+ driver.js = vi.fn(async (code: string) => {
+ calls.push({ method: 'js', args: [code] });
+ return answers.js;
+ });
+ driver.op = vi.fn(async (op: string, input: unknown) => {
+ calls.push({ method: op, args: [input] });
+ return answers[op];
+ });
+ return { driver, calls };
+}
+
+describe('the capability catalog', () => {
+ it('serves capabilities from the same list every front already reads', () => {
+ for (const cap of CAPABILITIES as Tool[]) {
+ expect((TOOLS as Tool[]).some((t) => t.name === cap.name)).toBe(true);
+ }
+ expect((TOOLS as Tool[]).length).toBe((ATOMS as Tool[]).length + (CAPABILITIES as Tool[]).length);
+ });
+
+ it('never shadows an atomic tool', () => {
+ const atoms = new Set((ATOMS as Tool[]).map((t) => t.name));
+ for (const cap of CAPABILITIES as Tool[]) expect(atoms.has(cap.name)).toBe(false);
+ });
+
+ it('hides mutating capabilities from a read-only client, as it does tools', () => {
+ const readOnly = new Set(listTools(false).map((t: { name: string }) => t.name));
+ for (const cap of CAPABILITIES as Tool[]) {
+ if ((cap.effect ?? 'read') !== 'read') expect(readOnly.has(cap.name)).toBe(false);
+ }
+ });
+
+ it('declares an effect no gentler than the steps it runs', () => {
+ const severity: Record<string, number> = { read: 0, undoable: 1, irreversible: 2 };
+ const byName = new Map((ATOMS as Tool[]).map((t) => [t.name, t]));
+ for (const { name, effect, steps } of capabilityStepNames() as Array<{ name: string; effect: string; steps: string[] }>) {
+ for (const step of steps) {
+ const tool = byName.get(step);
+ expect(tool, `${name} calls unknown tool ${step}`).toBeTruthy();
+ expect(severity[tool!.effect ?? 'read']).toBeLessThanOrEqual(severity[effect]);
+ }
+ }
+ });
+});
+
+describe('capability dispatch', () => {
+ it('reaches the editor only through tools, so the surface sees ordinary calls', async () => {
+ const { driver, calls } = fakeDriver({ applyOps: { refs: { root: 7 }, created: [7], applied: 1 } });
+ const res = await runTool(capability('configure_physics_body'), driver, { entity: 7, body: 'dynamic' });
+
+ expect(res.isError).toBeFalsy();
+ // get_entity then apply_scene_ops — both atoms, nothing else touched.
+ expect(calls.map((c) => c.method)).toEqual(['getEntity', 'applyOps']);
+ });
+
+ it('validates its own input the way any tool does', async () => {
+ const { driver } = fakeDriver();
+ const res = await runTool(capability('configure_physics_body'), driver, { entity: 1, shape: 'triangle' });
+ expect(res.isError).toBe(true);
+ expect(text(res)).toMatch(/shape must be/);
+ });
+
+ it('refuses an argument nobody declared rather than dropping it', async () => {
+ const { driver } = fakeDriver();
+ const res = await runTool(capability('wire_ui_event'), driver, {
+ entity: 1, event: 'click', action: 'ui.setVisible', bogus: 1,
+ });
+ expect(res.isError).toBe(true);
+ expect(text(res)).toMatch(/unknown argument/);
+ });
+
+ it('is not a way past the write gate a client was refused', async () => {
+ const { driver, calls } = fakeDriver();
+ const res = await runTool(capability('wire_ui_event'), driver, { entity: 1, event: 'click', action: 'x' }, false);
+ expect(res.isError).toBe(true);
+ expect(text(res)).toMatch(/mutates the scene/);
+ expect(calls).toEqual([]);
+ });
+
+ it('names the step that failed, not just the failure', async () => {
+ const driver = vi.fn(async (method: string) => {
+ if (method === 'applyOps') throw new Error('component X is not on entity 12');
+ return undefined;
+ }) as never;
+ const res = await runTool(capability('configure_physics_body'), driver, { entity: 12 });
+ expect(res.isError).toBe(true);
+ expect(text(res)).toMatch(/step apply_scene_ops: component X is not on entity 12/);
+ });
+});
+
+describe('create_prefab', () => {
+ it('builds the subtree, names it and extracts it — one call for what was three', async () => {
+ const { driver, calls } = fakeDriver({
+ applyOps: { refs: { root: 4 }, created: [4, 5], applied: 2 },
+ js: '@uuid:abc',
+ });
+ const res = await runTool(capability('create_prefab'), driver, {
+ name: 'Coin',
+ ops: [{ op: 'create', ref: 'root', components: ['Transform', 'Sprite'] }],
+ });
+
+ expect(res.isError).toBeFalsy();
+ expect(calls.map((c) => c.method)).toEqual(['applyOps', 'renameEntity', 'js']);
+ expect(JSON.parse(text(res))).toMatchObject({
+ entity: 4,
+ template: 'prefab:assets/prefabs/Coin.esprefab',
+ });
+ });
+
+ it('says which ref it wanted when the program never defined a root', async () => {
+ const { driver } = fakeDriver({ applyOps: { refs: { body: 4 }, created: [4], applied: 1 } });
+ const res = await runTool(capability('create_prefab'), driver, { name: 'Coin', ops: [] });
+
+ expect(res.isError).toBe(true);
+ expect(text(res)).toMatch(/defined no ref "root"/);
+ expect(text(res)).toMatch(/it defined: body/);
+ });
+});
+
+describe('wire_ui_event', () => {
+ it('adds to the wires an entity already has', async () => {
+ const { driver, calls } = fakeDriver({ getEventBindings: [{ event: 'click', action: 'old.action' }] });
+ await runTool(capability('wire_ui_event'), driver, { entity: 3, event: 'click', action: 'ui.setVisible' });
+
+ const set = calls.find((c) => c.method === 'setEventBindings')!;
+ expect(set.args[1]).toEqual([
+ { event: 'click', action: 'old.action' },
+ { event: 'click', action: 'ui.setVisible' },
+ ]);
+ });
+
+ it('drops them only when asked to, and does not even read them first', async () => {
+ const { driver, calls } = fakeDriver({ getEventBindings: [{ event: 'click', action: 'old.action' }] });
+ await runTool(capability('wire_ui_event'), driver, {
+ entity: 3, event: 'click', action: 'ui.setVisible', replace: true,
+ });
+
+ expect(calls.map((c) => c.method)).toEqual(['setEventBindings']);
+ expect(calls[0].args[1]).toEqual([{ event: 'click', action: 'ui.setVisible' }]);
+ });
+});
+
+describe('create_behavior', () => {
+ it('writes a defineBehavior script and attaches the component it defines', async () => {
+ const { driver, calls } = fakeDriver({
+ js: { ok: true, path: 'src/EnemyChase.ts', wiredInto: 'src/components.ts' },
+ write_project_file: { ok: true, path: 'src/EnemyChase.ts', errors: [] },
+ });
+ const res = await runTool(capability('create_behavior'), driver, {
+ name: 'EnemyChase',
+ state: { speed: 120 },
+ update: 'ctx.self.speed += dt;',
+ attachTo: [4, 5],
+ });
+
+ expect(res.isError).toBeFalsy();
+ const write = calls.find((c) => c.method === 'write_project_file')!;
+ const source = String((write.args[0] as { content: string }).content);
+ expect(source).toContain("defineBehavior('EnemyChase'");
+ expect(source).toContain('"speed": 120');
+ expect(source).toContain('ctx.self.speed += dt;');
+
+ const ops = calls.find((c) => c.method === 'applyOps')!;
+ expect(ops.args[0]).toEqual([
+ { op: 'add_component', entity: 4, component: 'EnemyChase' },
+ { op: 'add_component', entity: 5, component: 'EnemyChase' },
+ ]);
+ expect(JSON.parse(text(res))).toMatchObject({ name: 'EnemyChase', attached: 2 });
+ });
+
+ it('writes the script even with nothing to attach it to', async () => {
+ const { driver, calls } = fakeDriver({
+ js: { ok: true, path: 'src/Idle.ts' },
+ write_project_file: { ok: true, errors: [] },
+ });
+ await runTool(capability('create_behavior'), driver, { name: 'Idle', update: '' });
+
+ expect(calls.map((c) => c.method)).toEqual(['js', 'write_project_file']);
+ });
+
+ it('refuses to write logic into a script that was never wired in', async () => {
+ const { driver, calls } = fakeDriver({ js: { ok: false, error: 'name already taken' } });
+ const res = await runTool(capability('create_behavior'), driver, { name: 'Dup', update: '' });
+
+ expect(res.isError).toBe(true);
+ expect(text(res)).toMatch(/name already taken/);
+ expect(calls.map((c) => c.method)).toEqual(['js']);
+ });
+});
diff --git a/desktop/tests/editor-mcp-tools.test.ts b/desktop/tests/editor-mcp-tools.test.ts
index 184fc7cd6..b30f35580 100644
--- a/desktop/tests/editor-mcp-tools.test.ts
+++ b/desktop/tests/editor-mcp-tools.test.ts
@@ -12,8 +12,10 @@ const toolNamed = (name: string) => TOOLS.find((t: { name: string }) => t.name =
describe('editor MCP tool registry', () => {
it('every tool has a unique name and a surface method, renderer code, or host op', () => {
const names = new Set<string>();
- for (const t of TOOLS as Array<{ name: string; method?: string; args?: unknown; js?: unknown; op?: unknown }>) {
- if (t.js) expect(typeof t.js).toBe('function');
+ for (const t of TOOLS as Array<{ name: string; method?: string; args?: unknown; js?: unknown; op?: unknown; run?: unknown }>) {
+ // A capability carries `run` instead: a program over the atoms below it.
+ if (t.run) expect(typeof t.run).toBe('function');
+ else if (t.js) expect(typeof t.js).toBe('function');
else if (t.op) expect(typeof t.op).toBe('string');
else {
expect(typeof t.method).toBe('string');
diff --git a/tools/check-capabilities.mjs b/tools/check-capabilities.mjs
new file mode 100644
index 000000000..ecc2cfa6d
--- /dev/null
+++ b/tools/check-capabilities.mjs
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-capabilities.mjs — a capability composes tools, and says how bad
+ * it is honestly.
+ *
+ * A capability exists to raise what a model reasons about: `configure_physics_body`
+ * rather than four `add_component` / `set_field` calls. The whole reason that is
+ * safe is that it composes DECLARED TOOLS and adds no editing truth of its own —
+ * so it cannot drift from what the UI does, the way a second implementation of
+ * the same operation always eventually does.
+ *
+ * Two things have to hold for that, and neither is visible at a glance:
+ *
+ * Every tool a capability names must exist. Nothing else checks: a step is a
+ * string looked up at call time, so a renamed tool leaves a capability that
+ * fails only when a model finally reaches for it — mid-conversation, having
+ * already half-built something.
+ *
+ * A capability's declared `effect` must be no gentler than its steps'. The tiers
+ * are drawn where undo stops working, and the built-in agent confirms exactly
+ * the irreversible ones. A capability that runs `create_script` while calling
+ * itself `undoable` walks a model straight past that prompt, and the file it
+ * wrote is not coming back.
+ */
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SHARED = path.join(ROOT, 'desktop', 'shared');
+
+const { ATOMS } = await import(pathToFileURL(path.join(SHARED, 'toolCatalog.mjs')).href);
+const { CAPABILITIES, capabilityStepNames } = await import(
+ pathToFileURL(path.join(SHARED, 'capabilityCatalog.mjs')).href
+);
+
+const SEVERITY = { read: 0, undoable: 1, irreversible: 2 };
+const atomByName = new Map(ATOMS.map((t) => [t.name, t]));
+const problems = [];
+
+for (const cap of CAPABILITIES) {
+ if (typeof cap.run !== 'function') problems.push(`${cap.name}: a capability needs a \`run(input, call)\``);
+ if (!cap.description) problems.push(`${cap.name}: needs a description — it is what the model reads to choose it`);
+ if (!cap.schema) problems.push(`${cap.name}: needs a schema`);
+ if (atomByName.has(cap.name)) problems.push(`${cap.name}: shadows an atomic tool of the same name`);
+}
+
+let checked = 0;
+for (const { name, effect, steps } of capabilityStepNames()) {
+ if (steps.length === 0) {
+ problems.push(`${name}: calls no tool — a capability that composes nothing is a tool, not a capability`);
+ }
+ for (const step of steps) {
+ checked++;
+ const tool = atomByName.get(step);
+ if (!tool) {
+ problems.push(`${name}: calls \`${step}\`, which the catalog does not have`);
+ continue;
+ }
+ const stepEffect = tool.effect ?? 'read';
+ if (SEVERITY[stepEffect] > SEVERITY[effect]) {
+ problems.push(
+ `${name}: declared \`${effect}\` but calls \`${step}\`, which is \`${stepEffect}\``
+ + ' — the confirm gate reads the capability, not its steps',
+ );
+ }
+ }
+}
+
+if (problems.length > 0) {
+ console.log(`check-capabilities: ${problems.length} problem(s):`);
+ for (const p of problems) console.log(` ${p}`);
+ process.exit(1);
+}
+
+console.log(
+ `check-capabilities: ${CAPABILITIES.length} capabilities over ${checked} tool call(s) — every name exists, `
+ + 'every effect is honest.',
+);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index dd7ae3efd..c7074f552 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -54,6 +54,7 @@ export const GATES = [
{ id: 'project-settings', run: 'node tools/check-project-settings.mjs' },
{ id: 'workflows', run: 'node tools/check-workflows.mjs' },
{ id: 'tool-calls', run: 'node tools/check-tool-calls.mjs' },
+ { id: 'capabilities', run: 'node tools/check-capabilities.mjs' },
{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs' },
{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs' },
{ id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },