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(editor): how hard the agent thinks is a setting, not a constant

yhh23022b1b86e5
diff --git a/desktop/electron/agent/anthropic.ts b/desktop/electron/agent/anthropic.ts
index db26b4fd3..97c646906 100644
--- a/desktop/electron/agent/anthropic.ts
+++ b/desktop/electron/agent/anthropic.ts
@@ -25,11 +25,10 @@ import type {
AgentProvider, AgentSession, CatalogTool, StepEvent, ToolOutcome, UserImage,
} from './types';
import {
- DEFAULT_MODEL, DEFAULT_CONTEXT_WINDOW, KEEP_WHOLE_RUNS, shouldCompact,
+ DEFAULT_MODEL, DEFAULT_CONTEXT_WINDOW, DEFAULT_EFFORT, KEEP_WHOLE_RUNS, shouldCompact,
} from '../../src/settings/agentIds';
-/** Agentic work is what `xhigh` is for; it is also the depth Claude Code runs at. */
-export const DEFAULT_EFFORT = 'xhigh';
+
/**
* Which extensions a session may use.
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index b20283ab7..295cba4eb 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -679,7 +679,7 @@ ipcMain.handle('secret:clear', (_e, id: string) => clearSecret(id));
// settings live in its localStorage) and merged, since the two rows fire
// separately; read at session creation, so a change lands on the next
// conversation rather than under the one being read.
-let agentEndpoint: { baseUrl?: string; model?: string; keyId?: string; contextWindow?: number } = {};
+let agentEndpoint: { baseUrl?: string; model?: string; keyId?: string; contextWindow?: number; effort?: string } = {};
const agentHost = createAgentHost({
driver: createSurfaceDriver(() => win),
@@ -696,6 +696,7 @@ const agentHost = createAgentHost({
apiKey,
baseURL: agentEndpoint.baseUrl,
model: agentEndpoint.model,
+ effort: agentEndpoint.effort as Parameters<typeof createAnthropicProvider>[0]['effort'],
contextWindow: agentEndpoint.contextWindow,
});
},
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index 7cfae23ed..5afc7d1a1 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -139,7 +139,7 @@ const api = {
ipcRenderer.invoke('agent:deleteConversation', id),
/** Point the NEXT session at an endpoint/model. Merged, so each settings row
* can push its own field. */
- setEndpoint: (patch: { baseUrl?: string; model?: string; keyId?: string; contextWindow?: number }): Promise<void> =>
+ setEndpoint: (patch: { baseUrl?: string; model?: string; keyId?: string; contextWindow?: number; effort?: string }): Promise<void> =>
ipcRenderer.invoke('agent:setEndpoint', patch),
/** Transcript events + status changes, in the order they happened; returns
* an unsubscribe. One channel because the two must not be reordered. */
diff --git a/desktop/src/components/AgentDrawer.tsx b/desktop/src/components/AgentDrawer.tsx
index 645ab9e4c..27fede5e0 100644
--- a/desktop/src/components/AgentDrawer.tsx
+++ b/desktop/src/components/AgentDrawer.tsx
@@ -31,7 +31,7 @@ import {
} from 'lucide-react';
import { useEditorStore } from '@/store/editorStore';
import {
- useAgent, sendAgentMessage, stopAgentTurn, confirmAgentCall, startNewConversation,
+ useAgent, agentEffort, sendAgentMessage, stopAgentTurn, confirmAgentCall, startNewConversation,
peekEntities, entitiesInInput, effectiveSelection, selectAgentModel, retryAgentTurn, setAgentDraft,
RESUMABLE, openAgentHistory, closeAgentHistory, resumeConversation, forgetConversation,
addAgentAttachments, removeAgentAttachment, latestContext,
@@ -924,6 +924,10 @@ function ModelPicker() {
useSyncExternalStore(subscribeProviders, providersRevision);
const providers = agentProviders();
const current = effectiveSelection();
+ // Subscribed, not read once: changing the depth in Settings has to show here
+ // without reopening the drawer.
+ useSettings((st) => st.getValue('agents.effort'));
+ const effort = agentEffort();
useEffect(() => {
if (!open) return;
@@ -937,6 +941,10 @@ function ModelPicker() {
<div className="ag-picker" onMouseDown={(e) => e.stopPropagation()}>
<button type="button" className="ag-picker-btn" onClick={() => setOpen((o) => !o)}>
{current?.model ?? t('agent.picker.none')}
+ {/* The depth beside the model, because together they are what the next
+ turn will cost. Muted: the model is the choice made here, the depth
+ is a setting this only reports. */}
+ {current && <span className="ag-picker-effort">{effort}</span>}
<ChevronDown size={11} strokeWidth={2} />
</button>
{open && (
diff --git a/desktop/src/i18n/messages/settings.ts b/desktop/src/i18n/messages/settings.ts
index 9dabec017..9d851f474 100644
--- a/desktop/src/i18n/messages/settings.ts
+++ b/desktop/src/i18n/messages/settings.ts
@@ -120,6 +120,11 @@ export const settingsMessages = defineMessages({
zh: '存在系统钥匙串里——不写进项目、不写进设置文件,也不会交回给这个窗口。每个提供方各存各的,切回来不用重输。',
},
'set.group.customProvider': { en: 'Custom Provider', zh: '自定义提供方' },
+ 'set.agents.effort': { en: 'Reasoning depth', zh: '思考深度' },
+ 'set.agents.effort.desc': {
+ en: 'How hard the model is asked to think before it acts. `xhigh` is what agentic work is for and is the default; drop it when a turn costs more or takes longer than the task deserved. Applies to the next conversation.',
+ zh: '模型动手之前被要求思考到什么程度。`xhigh` 是为 agent 类工作准备的,也是默认值;当一次运行的花费或耗时超过这件事本身的价值时,把它调低。对下一次对话生效。',
+ },
'set.agents.customBaseUrl': { en: 'Endpoint', zh: 'API 地址' },
'set.agents.customBaseUrl.desc': {
en: 'An Anthropic-compatible endpoint. Only needed for a provider not in the list — the built-in ones already know their address. The agent then sends only the core Messages format, without extended thinking, prompt caching or automatic fallbacks.',
diff --git a/desktop/src/settings/agentIds.ts b/desktop/src/settings/agentIds.ts
index 0978f99fd..ed60f936a 100644
--- a/desktop/src/settings/agentIds.ts
+++ b/desktop/src/settings/agentIds.ts
@@ -23,6 +23,25 @@ export const DEFAULT_MODEL = 'claude-opus-5';
*/
export const DEFAULT_CONTEXT_WINDOW = 128_000;
+/**
+ * How hard the model is asked to think, and what it costs.
+ *
+ * Agentic work is what `xhigh` is for — it is the depth Claude Code runs at,
+ * and it is the default here for the same reason the model is Opus-tier: this
+ * drives a real project and a wrong edit costs someone their scene. But the
+ * same model is worth running shallower when the ask is "rename these three
+ * entities", and depth is what a person reaches for when a turn cost too much
+ * or took too long. So it is a setting, separate from the model pick.
+ */
+export const AGENT_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'] as const;
+export type AgentEffort = (typeof AGENT_EFFORTS)[number];
+export const DEFAULT_EFFORT: AgentEffort = 'xhigh';
+
+/** A stored value, narrowed — a settings file is a file a person can edit, and
+ * an unknown depth must not reach the wire. */
+export const asEffort = (value: unknown): AgentEffort =>
+ (AGENT_EFFORTS as readonly string[]).includes(String(value)) ? (value as AgentEffort) : DEFAULT_EFFORT;
+
/**
* Fold the oldest runs away once the conversation is this far into its window,
* keeping the last {@link KEEP_WHOLE_RUNS} intact.
diff --git a/desktop/src/settings/editorSettings.ts b/desktop/src/settings/editorSettings.ts
index d05ae31ff..3401867c3 100644
--- a/desktop/src/settings/editorSettings.ts
+++ b/desktop/src/settings/editorSettings.ts
@@ -21,6 +21,7 @@ import { mcpStatus, setMcpEnabled, subscribeMcp } from '@/store/McpStore';
import { secretStatusLine, subscribeSecrets } from '@/store/SecretStore';
import { syncAgentEndpoint } from '@/store/AgentStore';
import { agentProviders, agentKeyId, CUSTOM_PROVIDER } from '@/agent/providers';
+import { AGENT_EFFORTS, DEFAULT_EFFORT } from '@/settings/agentIds';
import { applyUiZoom, UI_SCALE_SETTING, ZOOM_DEFAULT, ZOOM_MIN, ZOOM_MAX } from '@/layout/uiZoom';
import { t, editorLocale, systemDefaultLocale, EDITOR_LOCALES, LANGUAGE_SETTING_ID } from '@/i18n';
@@ -254,6 +255,23 @@ for (const provider of agentProviders()) {
});
}
+// How hard the model is asked to think. Its own setting rather than part of the
+// model pick: the same model is worth running shallower for "rename these
+// three", and depth is what someone reaches for when a turn cost too much or
+// took too long — not when they change provider.
+settingsRegistry.register({
+ id: 'agents.effort',
+ type: 'enum',
+ scope: 'editor',
+ section: 'agents',
+ group: t('set.group.builtinAgent'),
+ label: t('set.agents.effort'),
+ description: t('set.agents.effort.desc'),
+ default: DEFAULT_EFFORT,
+ options: AGENT_EFFORTS.map((value) => ({ value, label: value })),
+ effect: () => syncAgentEndpoint(),
+});
+
// The escape hatch, for a provider we have not heard of — which is exactly the
// one we cannot ship an endpoint or a model list for.
settingsRegistry.register({
diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.ts
index 4106c3e87..18d12162a 100644
--- a/desktop/src/store/AgentStore.ts
+++ b/desktop/src/store/AgentStore.ts
@@ -24,6 +24,7 @@ import {
} from '@/agent/providers';
import { refreshSecret, secretStatus, subscribeSecrets } from '@/store/SecretStore';
import { useSettings } from '@/store/settingsStore';
+import { asEffort, type AgentEffort } from '@/settings/agentIds';
import type { Attachment } from '@/agent/attachments';
import { confirm } from '@/components/confirm';
import { t } from '@/i18n';
@@ -278,6 +279,10 @@ function resolveProvider(id: string) {
};
}
+/** The configured reasoning depth, narrowed. */
+export const agentEffort = (): AgentEffort =>
+ asEffort(useSettings.getState().getValue('agents.effort'));
+
const hasKey = (providerId: string): boolean =>
secretStatus(agentKeyId(providerId))?.configured === true;
@@ -310,6 +315,11 @@ export function syncAgentEndpoint(): void {
// How far the conversation may grow before it is compacted. Travels with the
// endpoint because it is the same piece of knowledge: which provider this is.
contextWindow: def?.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+ // How hard the model is asked to think. A setting rather than part of the
+ // model pick: the same model is worth running at different depths, and the
+ // depth is the one thing a person adjusts because a turn cost too much or
+ // took too long — not because they changed provider.
+ effort: agentEffort(),
});
}
diff --git a/desktop/src/theme/agent.css b/desktop/src/theme/agent.css
index 702806d09..9f0e90f1c 100644
--- a/desktop/src/theme/agent.css
+++ b/desktop/src/theme/agent.css
@@ -1073,3 +1073,11 @@
}
.ag-selchip:hover { background: var(--pressed); color: var(--text-hi); }
.ag-selchip svg { color: var(--text-faint); }
+
+/* The depth beside the model in the picker's button. Muted and smaller: the
+ model is the choice made here, the depth is a setting this only reports. */
+.ag-picker-effort {
+ margin-left: 5px;
+ color: var(--text-faint);
+ font-size: var(--fs-2xs);
+}
diff --git a/desktop/tests/agent-effort.test.ts b/desktop/tests/agent-effort.test.ts
new file mode 100644
index 000000000..96120e0d3
--- /dev/null
+++ b/desktop/tests/agent-effort.test.ts
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file How hard the model is asked to think.
+ *
+ * The plumbing for this existed and nothing ever set it, so every turn ran at
+ * `xhigh` whatever the task. What is worth pinning now that it is settable is
+ * the narrowing: a settings file is a file a person can edit, and an unknown
+ * depth must not reach the wire — a request the endpoint rejects for a value we
+ * passed through is a turn lost to our own trust.
+ */
+import { describe, it, expect } from 'vitest';
+import { AGENT_EFFORTS, DEFAULT_EFFORT, asEffort } from '../src/settings/agentIds';
+import { buildStepRequest } from '../electron/agent/anthropic';
+import type { CatalogTool } from '../electron/agent/types';
+
+describe('the depths on offer', () => {
+ it('are ordered shallow to deep, and default to the agentic one', () => {
+ expect([...AGENT_EFFORTS]).toEqual(['low', 'medium', 'high', 'xhigh', 'max']);
+ expect(DEFAULT_EFFORT).toBe('xhigh');
+ });
+});
+
+describe('asEffort', () => {
+ it.each(AGENT_EFFORTS)('passes %s through', (v) => {
+ expect(asEffort(v)).toBe(v);
+ });
+
+ it('falls back for anything a hand-edited settings file might hold', () => {
+ for (const junk of ['', 'XHIGH', 'highest', 'ultra', 0, 1, null, undefined, {}, []]) {
+ expect(asEffort(junk)).toBe(DEFAULT_EFFORT);
+ }
+ });
+});
+
+describe('the request carries it', () => {
+ const TOOLS: CatalogTool[] = [
+ { name: 'get_scene_tree', description: 'Read the scene.', schema: { type: 'object' }, effect: 'read' },
+ ];
+ const req = (effort: string) => buildStepRequest({
+ dialect: 'anthropic', model: 'm', effort, system: 's', tools: TOOLS, messages: [{ role: 'user', content: 'hi' }],
+ });
+
+ it('puts the chosen depth on the wire', () => {
+ expect(req('low').output_config).toEqual({ effort: 'low' });
+ expect(req('max').output_config).toEqual({ effort: 'max' });
+ });
+
+ it('sends it to a compatible gateway too — it is a hint, not an extension', () => {
+ // Unlike thinking/cache_control/fallbacks, a gateway can ignore effort
+ // without the response changing shape, so it survives the dialect drop.
+ const compatible = buildStepRequest({
+ dialect: 'compatible', model: 'm', effort: 'medium', system: 's', tools: TOOLS,
+ messages: [{ role: 'user', content: 'hi' }],
+ });
+ expect(compatible.output_config).toEqual({ effort: 'medium' });
+ expect(compatible.thinking).toBeUndefined();
+ });
+});