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(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.ts
index 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 module
import { 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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'] },