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
feat(agent): capabilities — a layer of intent above the tool catalog
yhh83bf13eebb0a
diff --git a/desktop/package.json b/desktop/package.jsonindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.tsnew file mode 100644index 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.tsindex 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.mjsnew file mode 100644index 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.mjsindex 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' },