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(agent): a plugin's tool is named the way the wire can address it
esenginefcad90cbabc2
diff --git a/desktop/electron/agent/kernel.ts b/desktop/electron/agent/kernel.tsindex b7bd39bca..76bca2a96 100644--- a/desktop/electron/agent/kernel.ts+++ b/desktop/electron/agent/kernel.ts@@ -19,6 +19,7 @@ import {criteriaProblem, evaluate, failureReport, markBaseline,type Acceptance, type Criterion, type DeclaredCriterion,} from './acceptance';+import { isWireToolName } from '../../src/agent/toolName';// Plain .mjs, shared with the MCP fronts — esbuild bundles it into main.// @ts-expect-error untyped shared moduleimport { TOOLS, runTool, mutates, irreversible, journaled } from '../../shared/toolCatalog.mjs';@@ -57,6 +58,10 @@ export function agentTools(contributed: readonly ContributedTool[] = []): readon// did not choose is a tool whose own docs are wrong, and shadowing a// built-in would let a plugin quietly redefine `delete_entity`.if (taken.has(tool.name)) continue;+ // An endpoint answers an illegal NAME by refusing the whole request, so one+ // such tool leaves the agent unusable. Registration refuses them too; a+ // plugin installed before that rule still reaches here.+ if (!isWireToolName(tool.name)) continue;taken.add(tool.name);out.push({name: tool.name,diff --git a/desktop/src/agent/toolName.ts b/desktop/src/agent/toolName.tsnew file mode 100644index 000000000..d559341a7--- /dev/null+++ b/desktop/src/agent/toolName.ts@@ -0,0 +1,31 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file toolName.ts+ * @brief What a tool may be CALLED, on the wire — the one rule both protocols+ * impose, in the one place that decides it.+ *+ * Anthropic takes `^[a-zA-Z0-9_-]{1,128}$` and Chat Completions `^[a-zA-Z0-9_-]{1,64}$`.+ * Neither accepts a dot. A name outside that is not a tool the endpoint quietly+ * ignores: it refuses the whole REQUEST with a 400 naming an index, so one+ * plugin's tool takes every conversation down with it and the message says+ * nothing about plugins.+ *+ * Lives under src/ and is read from main as well, because the rule has to be one+ * rule — it was two (a validator that required dots, a wire that forbids them),+ * and each half looked right on its own.+ */++/** The intersection of what both protocols accept. */+export const WIRE_TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;++export const isWireToolName = (name: string): boolean => WIRE_TOOL_NAME.test(name);++/**+ * A plugin id as a tool-name prefix.+ *+ * Ids are dotted by convention (`estella.ldtk`) and tool names cannot be, so the+ * namespace is the id with everything illegal folded to `_`. Derived, not+ * declared: a plugin picking its own prefix could pick another plugin's id.+ */+export const toolNamespace = (pluginId: string): string => pluginId.replace(/[^a-zA-Z0-9_-]+/g, '_');diff --git a/desktop/src/plugins/agentTools.ts b/desktop/src/plugins/agentTools.tsindex 64b08ddea..9092b42a3 100644--- a/desktop/src/plugins/agentTools.ts+++ b/desktop/src/plugins/agentTools.ts@@ -22,6 +22,7 @@* is the CONFIRM GATE working correctly for an honest plugin.*/import { ContributionRegistry, type Owner, type Disposable } from '@/contrib/ContributionRegistry';+import { isWireToolName, toolNamespace } from '@/agent/toolName';import type { AgentToolContribution } from './types';/** The registry keys by `id`; a tool's id IS its name — the model addresses it@@ -40,12 +41,13 @@ const registry = new ContributionRegistry<RegisteredTool>('agent tool');*/export function agentToolProblem(pluginId: string, tool: AgentToolContribution): string | null {if (!tool.name) return 'an agent tool needs a `name`';- if (!tool.name.startsWith(`${pluginId}.`)) {- return `\`name\` must start with "${pluginId}." — an un-namespaced tool can shadow a built-in one`;+ const prefix = `${toolNamespace(pluginId)}_`;+ if (!tool.name.startsWith(prefix)) {+ return `\`name\` must start with "${prefix}" — an un-namespaced tool can shadow a built-in one`;}- // The model addresses tools by name on the wire; the API's own constraint.- if (!/^[a-z0-9][a-z0-9_.-]*$/i.test(tool.name)) {- return '`name` may contain only letters, digits, `_`, `.` and `-`';+ if (!isWireToolName(tool.name)) {+ return '`name` may contain only letters, digits, `_` and `-`, up to 64 of them — '+ + 'a name outside that makes the endpoint refuse every request of the conversation';}if (!tool.description) {return 'an agent tool needs a `description` — it is the only thing the model reads to decide whether to call it';diff --git a/desktop/src/plugins/types.ts b/desktop/src/plugins/types.tsindex 6aaed6b2a..edd356539 100644--- a/desktop/src/plugins/types.ts+++ b/desktop/src/plugins/types.ts@@ -413,7 +413,12 @@ export interface ContextMenuTarget {* for it, in a sentence.*/export interface AgentToolContribution {- /** Namespaced with your plugin id, e.g. `acme.bake-occlusion`. */+ /**+ * Namespaced with your plugin id, with every dot in it as `_` — plugin+ * `acme.tools` offers `acme_tools_bake-occlusion`. Letters, digits, `_` and+ * `-` only: this is what the model addresses on the wire, and an endpoint+ * answers a name outside that by refusing the whole conversation.+ */name: string;/** What it does and when to use it — written for the model, not for a menu. */description: string;diff --git a/desktop/tests/agent-plugin-tools.test.ts b/desktop/tests/agent-plugin-tools.test.tsindex c69d7182c..7a71a241f 100644--- a/desktop/tests/agent-plugin-tools.test.ts+++ b/desktop/tests/agent-plugin-tools.test.ts@@ -10,12 +10,16 @@* believes it knows what that does.*/import { describe, it, expect } from 'vitest';+import { readdirSync, readFileSync, existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';import { agentTools, type ContributedTool } from '../electron/agent/kernel';import { agentToolProblem } from '../src/plugins/agentTools';+import { isWireToolName } from '../src/agent/toolName';import type { AgentToolContribution } from '../src/plugins/types';const tool = (over: Partial<ContributedTool> = {}): ContributedTool => ({- name: 'acme.bake',+ name: 'acme_bake',description: 'Bake the thing.',schema: { type: 'object' },effect: 'undoable',@@ -42,7 +46,7 @@ describe('the catalog a session is given', () => {it('appends what plugins offered, after the built-ins', () => {const merged = agentTools([tool()]);expect(merged).toHaveLength(agentTools().length + 1);- expect(merged.at(-1)).toMatchObject({ name: 'acme.bake', effect: 'undoable' });+ expect(merged.at(-1)).toMatchObject({ name: 'acme_bake', effect: 'undoable' });});it('keeps the built-in when a plugin claims its name', () => {@@ -55,8 +59,8 @@ describe('the catalog a session is given', () => {it('keeps the first of two plugins claiming one name', () => {const merged = agentTools([tool({ description: 'first' }), tool({ description: 'second' })]);- expect(merged.filter((t) => t.name === 'acme.bake')).toHaveLength(1);- expect(merged.find((t) => t.name === 'acme.bake')?.description).toBe('first');+ expect(merged.filter((t) => t.name === 'acme_bake')).toHaveLength(1);+ expect(merged.find((t) => t.name === 'acme_bake')?.description).toBe('first');});it('routes every contributed tool through the one door, carrying its own name', () => {@@ -67,14 +71,27 @@ describe('the catalog a session is given', () => {expect(entry.method).toBe('runPluginTool');// The name goes with the call — main knows only metadata, so the window// has to be told which handler this is.- expect(entry.args({ a: 1 })).toEqual(['acme.bake', { a: 1 }]);+ expect(entry.args({ a: 1 })).toEqual(['acme_bake', { a: 1 }]);});it('carries the declared effect, which is what the confirm gate reads', () => {- const irreversible = agentTools([tool({ name: 'acme.wipe', effect: 'irreversible' })]).at(-1);+ const irreversible = agentTools([tool({ name: 'acme_wipe', effect: 'irreversible' })]).at(-1);expect(irreversible?.effect).toBe('irreversible');});+ // What actually went wrong: an endpoint answers an illegal tool NAME by+ // refusing the whole request, so one tool from one plugin was the difference+ // between a working agent and a 400 on every message.+ it('drops a contributed tool the wire cannot address', () => {+ const merged = agentTools([tool({ name: 'acme.bake' }), tool({ name: 'acme_bake' })]);+ expect(merged.map((t) => t.name)).not.toContain('acme.bake');+ expect(merged.at(-1)?.name).toBe('acme_bake');+ });++ it('offers nothing a protocol would refuse to be handed', () => {+ for (const t of agentTools([tool()])) expect(isWireToolName(t.name)).toBe(true);+ });+it('does not mutate the built-in catalog', () => {const before = agentTools().length;agentTools([tool()]);@@ -83,20 +100,29 @@ describe('the catalog a session is given', () => {});describe('what a plugin may offer', () => {- const ok: AgentToolContribution = { name: 'acme.bake', description: 'Bake it.', run: () => 1 };+ const ok: AgentToolContribution = { name: 'acme_bake', description: 'Bake it.', run: () => 1 };it('accepts a namespaced, described tool with a handler', () => {expect(agentToolProblem('acme', ok)).toBeNull();});it('refuses a name that is not namespaced with the plugin id', () => {- expect(agentToolProblem('acme', { ...ok, name: 'bake' })).toMatch(/must start with "acme\."/);+ expect(agentToolProblem('acme', { ...ok, name: 'bake' })).toMatch(/must start with "acme_"/);// Someone else's namespace is just as much a shadow.- expect(agentToolProblem('acme', { ...ok, name: 'other.bake' })).toMatch(/must start with/);+ expect(agentToolProblem('acme', { ...ok, name: 'other_bake' })).toMatch(/must start with/);});it('refuses a name the wire cannot address', () => {- expect(agentToolProblem('acme', { ...ok, name: 'acme.bake it' })).toMatch(/only letters/);+ expect(agentToolProblem('acme', { ...ok, name: 'acme_bake it' })).toMatch(/only letters/);+ });++ // The namespace a dotted plugin id asks for is not a legal tool name, and+ // requiring it made every conversation fail with a 400 naming a tool INDEX:+ // no endpoint accepts a dot, and it refuses the request rather than the tool.+ it('namespaces a dotted plugin id without asking for a dot', () => {+ expect(agentToolProblem('estella.ldtk', { ...ok, name: 'estella_ldtk_import' })).toBeNull();+ expect(agentToolProblem('estella.ldtk', { ...ok, name: 'estella.ldtk.import' }))+ .toMatch(/must start with "estella_ldtk_"/);});it('refuses a tool with no description — that is all the model reads', () => {@@ -111,3 +137,32 @@ describe('what a plugin may offer', () => {expect(agentToolProblem('acme', { ...ok, name: '' })).toMatch(/needs a `name`/);});});++/**+ * The rule above is only enforced at registration, where a violation is a line+ * in the log nobody reads — and the plugin that broke it shipped WITH the editor.+ * Read from source rather than by loading them: the point is to fail here, in a+ * test, and not in a user's conversation.+ */+describe('the plugins that ship with the editor', () => {+ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../plugins');++ const sources = (dir: string): string[] => readdirSync(dir, { withFileTypes: true })+ .flatMap((e) => (e.isDirectory()+ ? sources(path.join(dir, e.name))+ : e.name.endsWith('.ts') ? [path.join(dir, e.name)] : []));++ const declared = readdirSync(root, { withFileTypes: true })+ .filter((e) => e.isDirectory() && existsSync(path.join(root, e.name, 'plugin.json')))+ .flatMap((e) => {+ const id = (JSON.parse(readFileSync(path.join(root, e.name, 'plugin.json'), 'utf8')) as { id: string }).id;+ return sources(path.join(root, e.name))+ .flatMap((file) => [...readFileSync(file, 'utf8')+ .matchAll(/agentTools\.register\(\{[\s\S]{0,200}?name:\s*'([^']+)'/g)]+ .map((m) => ({ id, name: m[1], file })));+ });++ it.each(declared)('$id offers $name under a name the wire accepts', ({ id, name }) => {+ expect(agentToolProblem(id, { name, description: 'x', run: () => 1 })).toBeNull();+ });+});diff --git a/plugins/ldtk/src/editor.ts b/plugins/ldtk/src/editor.tsindex d7bf769b7..61a1c362d 100644--- a/plugins/ldtk/src/editor.ts+++ b/plugins/ldtk/src/editor.ts@@ -24,7 +24,7 @@ export default definePlugin({});ctx.agentTools.register({- name: 'estella.ldtk.import',+ name: 'estella_ldtk_import',description: 'Convert an LDtk project (.ldtk) into Tiled maps the engine loads. '+ 'Use after adding or editing a .ldtk file; the maps land in a folder named after it.',schema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },