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): the agent reads in parallel and asks once per run, not once per call

esenginee344d0087aff
diff --git a/desktop/electron/agent/host.ts b/desktop/electron/agent/host.ts
index 758aee84a..4a21976ee 100644
--- a/desktop/electron/agent/host.ts
+++ b/desktop/electron/agent/host.ts
@@ -23,7 +23,7 @@
*/
import { runTurn, agentTools } from './kernel';
import { SYSTEM_PROMPT, editorContext } from './prompt';
-import type { AgentEvent, AgentProvider, AgentSession, ConfirmRequest } from './types';
+import type { AgentEvent, AgentProvider, AgentSession, ConfirmAnswer, ConfirmRequest } from './types';
import type { SurfaceDriver } from '../surfaceDriver';
export type AgentPhase = 'idle' | 'running' | 'awaiting_confirm';
@@ -66,7 +66,7 @@ export interface AgentHost {
stop(): void;
/** Answer a pending confirmation. Unknown ids are ignored — the turn it
* belonged to may have been aborted between the ask and the click. */
- confirm(callId: string, allow: boolean): void;
+ confirm(callId: string, answer: ConfirmAnswer): void;
/** Drop the conversation and start over; the next turn re-reads the key. */
reset(): AgentStatus;
/**
@@ -101,7 +101,7 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
let phase: AgentPhase = 'idle';
let error: string | null = null;
let running: AbortController | null = null;
- const pending = new Map<string, (allow: boolean) => void>();
+ const pending = new Map<string, (answer: ConfirmAnswer) => void>();
const status = (): AgentStatus => ({
ready: deps.ready(),
@@ -141,12 +141,12 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
/** Settle every outstanding ask as declined. See invariant 2. */
const settlePending = (): void => {
- for (const resolve of pending.values()) resolve(false);
+ for (const resolve of pending.values()) resolve('no');
pending.clear();
};
- const confirm = (request: ConfirmRequest): Promise<boolean> =>
- new Promise<boolean>((resolve) => {
+ const confirm = (request: ConfirmRequest): Promise<ConfirmAnswer> =>
+ new Promise<ConfirmAnswer>((resolve) => {
pending.set(request.callId, resolve);
phase = 'awaiting_confirm';
pushStatus();
@@ -227,11 +227,11 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
// not interrupt — it is waiting on us, not on the model.
settlePending();
},
- confirm: (callId, allow) => {
+ confirm: (callId, answer) => {
const resolve = pending.get(callId);
if (!resolve) return;
pending.delete(callId);
- resolve(allow);
+ resolve(answer);
if (pending.size === 0 && phase === 'awaiting_confirm') {
phase = 'running';
pushStatus();
diff --git a/desktop/electron/agent/kernel.ts b/desktop/electron/agent/kernel.ts
index bb51878a6..2ff58e50a 100644
--- a/desktop/electron/agent/kernel.ts
+++ b/desktop/electron/agent/kernel.ts
@@ -111,6 +111,10 @@ export async function runTurn(
emit({ type: 'turn_start', prompt: text, model, index: session.turnIndex });
let reason: Extract<AgentEvent, { type: 'turn_end' }>['reason'] = 'end_turn';
+ // Tools the person has waved through for the REST OF THIS RUN. Not persisted:
+ // an "always" that outlives the run is a permission switch nobody remembers
+ // flipping, which is the thing the gate exists to prevent.
+ const allowed = new Set<string>();
try {
if (context) session.pushContext(context);
session.pushUser(text);
@@ -130,13 +134,24 @@ export async function runTurn(
if (refused) { reason = 'refusal'; break; }
if (calls.length === 0) break;
+ // Reads have no side effects and no order among themselves, so a run of
+ // them goes out together — three lookups become one wait instead of three.
+ // Order is still respected ACROSS the boundary: a read the model asked for
+ // after a write means "tell me what that did", and answering it from
+ // before the write would be a lie it then reasons from.
const outcomes: ToolOutcome[] = [];
let wrote = false;
- for (const call of calls) {
- if (signal.aborted) break;
- const { outcome, mutated } = await execute(deps, call);
- outcomes.push(outcome);
- wrote ||= mutated;
+ for (let i = 0; i < calls.length && !signal.aborted;) {
+ let end = i;
+ while (end < calls.length && isRead(calls[end])) end++;
+ const batch = end - i > 1
+ ? await Promise.all(calls.slice(i, end).map((c) => execute(deps, c, allowed)))
+ : [await execute(deps, calls[i], allowed)];
+ for (const done of batch) {
+ outcomes.push(done.outcome);
+ wrote ||= done.mutated;
+ }
+ i += batch.length;
}
if (signal.aborted) break;
@@ -164,10 +179,17 @@ export async function runTurn(
const MAX_ROUNDS = 48;
+/** True when a call cannot change anything, so it may run alongside others. */
+function isRead(call: ToolCall): boolean {
+ const tool = byName.get(call.name);
+ return !!tool && (tool.effect ?? 'read') === 'read';
+}
+
/** Run one call: gate it, dispatch it, and report both ways. */
async function execute(
deps: KernelDeps,
call: ToolCall,
+ allowed: Set<string>,
): Promise<{ outcome: ToolOutcome; mutated: boolean }> {
const { emit, driver, confirm } = deps;
const tool = byName.get(call.name);
@@ -185,15 +207,18 @@ async function execute(
// the approval, and a prompt per setField would make the agent unusable.
// `irreversible` is where undo stops being an answer, so it is where the
// person has to be.
- if (irreversible(tool)) {
+ // Already waved through for the rest of this run — see ConfirmAnswer.
+ if (irreversible(tool) && !allowed.has(call.name)) {
const request = { callId: call.id, tool: call.name, reason: confirmReason(tool), input: call.input };
emit({ type: 'awaiting_confirm', request });
- if (!await confirm(request)) {
+ const answer = await confirm(request);
+ if (answer === 'no') {
const content = `the user declined to run ${call.name}. Do not retry it; `
+ 'continue with what you can do without it, or say what you need.';
emit({ type: 'tool_end', id: call.id, ok: false, summary: 'declined' });
return { outcome: { id: call.id, content, isError: false }, mutated: false };
}
+ if (answer === 'turn') allowed.add(call.name);
}
const result = await runTool(tool, driver, call.input, true) as {
diff --git a/desktop/electron/agent/types.ts b/desktop/electron/agent/types.ts
index e5a128518..f84d36a96 100644
--- a/desktop/electron/agent/types.ts
+++ b/desktop/electron/agent/types.ts
@@ -133,6 +133,17 @@ export interface ConfirmRequest {
input: Record<string, unknown>;
}
+/**
+ * How one of those was answered.
+ *
+ * `turn` also covers every later call of the SAME tool in this run — a task that
+ * saves eleven files should be one decision, not eleven identical ones, and a
+ * gate that interrupts that often is one people learn to click through without
+ * reading. It expires with the run on purpose: an "always" that outlives it is a
+ * permission switch nobody remembers flipping, which is what the gate is for.
+ */
+export type ConfirmAnswer = 'once' | 'turn' | 'no';
+
/**
* What the editor renders. A superset of what the provider emitted.
*
@@ -169,8 +180,8 @@ export interface KernelDeps {
/** What is behind `session`, for the transcript. The session abstraction has
* no name for itself, and the host is where that name is known. */
model: string;
- /** Ask the person. Resolving false means "declined", which the model is told. */
- confirm(request: ConfirmRequest): Promise<boolean>;
+ /** Ask the person. `no` is declined, which the model is told about. */
+ confirm(request: ConfirmRequest): Promise<ConfirmAnswer>;
emit(event: AgentEvent): void;
}
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 4bcb8b540..c71ab0400 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -47,6 +47,7 @@ import { mcpMode, startMcpEndpoint, stopMcpEndpoint, mcpEndpointStatus } from '.
import { secretStatus, setSecret, clearSecret, readSecret } from './secrets';
import { createSurfaceDriver } from './surfaceDriver';
import { createAgentHost } from './agent/host';
+import type { ConfirmAnswer } from './agent/types';
import { createAnthropicProvider } from './agent/anthropic';
import {
@@ -700,7 +701,7 @@ ipcMain.handle('agent:status', () => agentHost.status());
ipcMain.handle('agent:transcript', () => agentHost.transcript());
ipcMain.handle('agent:send', (_e, text: string) => agentHost.send(text));
ipcMain.handle('agent:stop', () => agentHost.stop());
-ipcMain.handle('agent:confirm', (_e, callId: string, allow: boolean) => agentHost.confirm(callId, allow));
+ipcMain.handle('agent:confirm', (_e, callId: string, answer: ConfirmAnswer) => agentHost.confirm(callId, answer));
ipcMain.handle('agent:reset', () => agentHost.reset());
ipcMain.handle('agent:retry', (_e, n: number, text: string) => agentHost.retry(n, text));
ipcMain.handle('agent:setEndpoint', (_e, patch: { baseUrl?: string; model?: string; keyId?: string; contextWindow?: number }) => {
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index 7b81a6b20..e3dcf0e26 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -22,7 +22,7 @@ import type { NativeTemplateEntry, InstallResult } from './nativeTemplates';
import type { McpEndpointStatus } from './mcpEndpoint';
import type { SecretStatus } from './secrets';
import type { AgentStatus, AgentMessage } from './agent/host';
-import type { AgentEvent } from './agent/types';
+import type { AgentEvent, ConfirmAnswer } from './agent/types';
// The privileged bridge the renderer is allowed to touch. Keep this surface small
// and explicit — anything the editor needs from the OS or Node goes through here.
@@ -120,8 +120,8 @@ const api = {
send: (text: string): Promise<AgentStatus> => ipcRenderer.invoke('agent:send', text),
stop: (): Promise<void> => ipcRenderer.invoke('agent:stop'),
/** Answer the pending confirmation for an irreversible tool. */
- confirm: (callId: string, allow: boolean): Promise<void> =>
- ipcRenderer.invoke('agent:confirm', callId, allow),
+ confirm: (callId: string, answer: ConfirmAnswer): Promise<void> =>
+ ipcRenderer.invoke('agent:confirm', callId, answer),
/** Drop the conversation and start a new one. */
reset: (): Promise<AgentStatus> => ipcRenderer.invoke('agent:reset'),
/** Ask the n-th turn again, discarding it and everything after it. */
diff --git a/desktop/src/components/AgentDrawer.tsx b/desktop/src/components/AgentDrawer.tsx
index 8752d8a9b..cc764ddc4 100644
--- a/desktop/src/components/AgentDrawer.tsx
+++ b/desktop/src/components/AgentDrawer.tsx
@@ -34,6 +34,7 @@ import {
peekEntities, entitiesInInput, effectiveSelection, selectAgentModel, retryAgentTurn,
type AgentTurn, type AgentEntry, type AgentToolEntry,
} from '@/store/AgentStore';
+import type { ConfirmAnswer } from '../../electron/agent/types';
import {
agentProviders, agentProvider, agentKeyId, parseModelList, subscribeProviders, providersRevision,
} from '@/agent/providers';
@@ -53,7 +54,7 @@ const TOOL_ICON: Record<string, typeof Eye> = {
irreversible: TriangleAlert,
};
-function ToolRow({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (allow: boolean) => void }) {
+function ToolRow({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (answer: ConfirmAnswer) => void }) {
const [open, setOpen] = useState(false);
const Icon = TOOL_ICON[entry.effect ?? 'read'] ?? Eye;
// While the model is writing them, show the raw text arriving; once the call
@@ -99,7 +100,7 @@ function ToolRow({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (allo
* unconditionally when it appears — a question you never saw is a turn that
* looks hung.
*/
-function ConfirmPassage({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (allow: boolean) => void }) {
+function ConfirmPassage({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (answer: ConfirmAnswer) => void }) {
const ref = useRef<HTMLDivElement>(null);
const target = describeTarget(entry.input);
useEffect(() => {
@@ -119,8 +120,18 @@ function ConfirmPassage({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm
echoing the tool name back is noise, and the heading already said it. */}
{target && <div className="ag-ask-tgt">{target}</div>}
<div className="ag-ask-acts">
- <button type="button" className="ag-go" onClick={() => onConfirm(true)}>{t('agent.confirm.allow')}</button>
- <button type="button" onClick={() => onConfirm(false)}>{t('agent.confirm.deny')}</button>
+ <button type="button" className="ag-go" onClick={() => onConfirm('once')}>{t('agent.confirm.allow')}</button>
+ {/* A task that saves eleven files should be one decision, not eleven
+ identical ones — a gate that interrupts that often is one people
+ learn to click through. Scoped to this run, and says so. */}
+ <button
+ type="button"
+ onClick={() => onConfirm('turn')}
+ title={t('agent.confirm.allowTurn.why', { tool: entry.name })}
+ >
+ {t('agent.confirm.allowTurn')}
+ </button>
+ <button type="button" onClick={() => onConfirm('no')}>{t('agent.confirm.deny')}</button>
</div>
</div>
);
@@ -179,7 +190,7 @@ function Prose({ text, streaming }: { text: string; streaming?: boolean }) {
/** Consecutive tool rows are one hairline-divided block; prose breaks the run. */
function Entries({ entries, onConfirm, streaming }: {
entries: readonly AgentEntry[];
- onConfirm: (callId: string, allow: boolean) => void;
+ onConfirm: (callId: string, answer: ConfirmAnswer) => void;
/** The run is still taking events, so the last entry is mid-write. */
streaming?: boolean;
}) {
@@ -192,7 +203,7 @@ function Entries({ entries, onConfirm, streaming }: {
out.push(
<div className="ag-steps" key={`steps-${group[0].id}`}>
{group.map((tool) => (
- <ToolRow key={tool.id} entry={tool} onConfirm={(allow) => onConfirm(tool.id, allow)} />
+ <ToolRow key={tool.id} entry={tool} onConfirm={(answer) => onConfirm(tool.id, answer)} />
))}
</div>,
);
diff --git a/desktop/src/i18n/messages/agent.ts b/desktop/src/i18n/messages/agent.ts
index b4a21b779..1e33d9cbd 100644
--- a/desktop/src/i18n/messages/agent.ts
+++ b/desktop/src/i18n/messages/agent.ts
@@ -79,6 +79,11 @@ export const agentMessages = defineMessages({
zh: '它会执行 Agent 自己写的代码,效果取决于那段代码。',
},
'agent.confirm.allow': { en: 'Run it', zh: '执行' },
+ 'agent.confirm.allowTurn': { en: 'Allow for this run', zh: '本轮都允许' },
+ 'agent.confirm.allowTurn.why': {
+ en: 'Stop asking for {tool} until this run ends. The next run asks again.',
+ zh: '本轮内不再为 {tool} 询问;下一轮会重新询问。',
+ },
'agent.confirm.deny': { en: 'Skip', zh: '跳过' },
'agent.confirm.denied': {
en: 'Skipped — the agent was told to work around it.',
diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.ts
index 8e1ab1a30..049808deb 100644
--- a/desktop/src/store/AgentStore.ts
+++ b/desktop/src/store/AgentStore.ts
@@ -18,7 +18,7 @@
*/
import { create } from 'zustand';
import type { AgentStatus, AgentMessage } from '../../electron/agent/host';
-import type { AgentEvent, ConfirmReason, ConfirmRequest } from '../../electron/agent/types';
+import type { AgentEvent, ConfirmAnswer, ConfirmReason, ConfirmRequest } from '../../electron/agent/types';
import {
agentProviders, agentProvider, agentKeyId, parseModelList, CUSTOM_PROVIDER, DEFAULT_CONTEXT_WINDOW,
} from '@/agent/providers';
@@ -488,17 +488,20 @@ export function stopAgentTurn(): void {
* main's echo — the person just decided, and a row that sits on "waiting for
* you" afterwards reads as a click that did not land.
*/
-export function confirmAgentCall(callId: string, allow: boolean): void {
+export function confirmAgentCall(callId: string, answer: ConfirmAnswer): void {
useAgent.setState((s) => {
const open = openTurn(s.turns);
if (!open) return {};
return {
turns: patchLast(s.turns, {
- entries: patchTool(open.entries, callId, { state: allow ? 'running' : 'declined', reason: null }),
+ entries: patchTool(open.entries, callId, {
+ state: answer === 'no' ? 'declined' : 'running',
+ reason: null,
+ }),
}),
};
});
- void window.estella?.agent?.confirm(callId, allow);
+ void window.estella?.agent?.confirm(callId, answer);
}
/** Drop the conversation — a new one starts with the next message. */
diff --git a/desktop/tests/agent-host.test.ts b/desktop/tests/agent-host.test.ts
index 39b67a186..5ce173603 100644
--- a/desktop/tests/agent-host.test.ts
+++ b/desktop/tests/agent-host.test.ts
@@ -150,7 +150,7 @@ describe('the agent host', () => {
await vi.waitFor(() => expect(h.status().phase).toBe('awaiting_confirm'));
expect(statuses().at(-1)?.phase).toBe('awaiting_confirm');
- h.confirm('c-save_scene', true);
+ h.confirm('c-save_scene', 'once');
await settled(h);
expect(events().some((e) => e.type === 'tool_end' && e.ok)).toBe(true);
});
@@ -159,7 +159,7 @@ describe('the agent host', () => {
const h = host([asks(call('save_scene')), ends()]);
h.send('save it');
await vi.waitFor(() => expect(h.status().phase).toBe('awaiting_confirm'));
- h.confirm('c-save_scene', false);
+ h.confirm('c-save_scene', 'no');
await settled(h);
expect(events().some((e) => e.type === 'tool_end' && e.summary === 'declined')).toBe(true);
});
@@ -186,7 +186,7 @@ describe('the agent host', () => {
it('ignores an answer to a call nobody is waiting on', async () => {
const h = host();
- expect(() => h.confirm('c-gone', true)).not.toThrow();
+ expect(() => h.confirm('c-gone', 'once')).not.toThrow();
});
});
diff --git a/desktop/tests/agent-kernel.test.ts b/desktop/tests/agent-kernel.test.ts
index ed02dad4b..3b9f2a6be 100644
--- a/desktop/tests/agent-kernel.test.ts
+++ b/desktop/tests/agent-kernel.test.ts
@@ -56,7 +56,7 @@ describe('the agent turn', () => {
events = [];
stepsSince = 0;
diagnostics = [];
- confirm = vi.fn(async () => true);
+ confirm = vi.fn(async () => 'once');
driver = vi.fn(async (method: string) => {
if (method === 'mark') return { seq: 7 };
if (method === 'stepsSince') return stepsSince;
@@ -111,7 +111,7 @@ describe('the agent turn', () => {
});
it('a decline is told to the model, not raised as a failure', async () => {
- confirm.mockResolvedValue(false);
+ confirm.mockResolvedValue('no');
const s = fakeSession([asks(call('export_game', { platform: 'web' })), ends()]);
await runTurn(deps(s), 'ship it', null, new AbortController().signal);
@@ -164,7 +164,7 @@ describe('the agent turn', () => {
stepsSince = 2;
const ac = new AbortController();
const s = fakeSession([asks(call('add_entity'), call('add_entity')), ends()]);
- confirm.mockImplementation(async () => true);
+ confirm.mockImplementation(async () => 'once');
driver.mockImplementation(async (method: string) => {
if (method === 'mark') return { seq: 7 };
if (method === 'stepsSince') return stepsSince;
@@ -237,4 +237,81 @@ describe('the agent turn', () => {
expect(String(s.results[0][0].content)).not.toContain('Truncated');
});
});
+
+ // A task that saves eleven files should be one decision, not eleven identical
+ // ones — a gate that interrupts that often is one people click through.
+ describe('the confirmation gate\'s scope', () => {
+ it('asks once per call by default', async () => {
+ const s = fakeSession([asks(call('save_scene'), call('save_scene')), ends()]);
+ await runTurn(deps(s), 'save twice', null, new AbortController().signal);
+ expect(confirm).toHaveBeenCalledTimes(2);
+ });
+
+ it('stops asking for that tool once it is allowed for the run', async () => {
+ confirm.mockResolvedValue('turn');
+ const s = fakeSession([asks(call('save_scene'), call('save_scene'), call('save_scene')), ends()]);
+ await runTurn(deps(s), 'save thrice', null, new AbortController().signal);
+ expect(confirm).toHaveBeenCalledTimes(1);
+ expect(events.filter((e) => e.type === 'tool_end' && e.ok)).toHaveLength(3);
+ });
+
+ // Scoped to the TOOL, not to everything: saying yes to saving is not saying
+ // yes to running arbitrary code.
+ it('does not carry the allowance to a different tool', async () => {
+ confirm.mockResolvedValue('turn');
+ const s = fakeSession([asks(call('save_scene'), call('run_editor_command')), ends()]);
+ await runTurn(deps(s), 'save then run', null, new AbortController().signal);
+ expect(confirm).toHaveBeenCalledTimes(2);
+ });
+
+ // The allowance is the run's. A new run starts from a clean gate, which is
+ // the whole reason it is not persisted.
+ it('expires with the run', async () => {
+ confirm.mockResolvedValue('turn');
+ const s = fakeSession([asks(call('save_scene')), ends(), asks(call('save_scene')), ends()]);
+ await runTurn(deps(s), 'save', null, new AbortController().signal);
+ await runTurn(deps(s), 'save again', null, new AbortController().signal);
+ expect(confirm).toHaveBeenCalledTimes(2);
+ });
+ });
+
+ // Reads cannot affect each other, so a batch of them is one wait rather than
+ // N. Anything that writes stays ordered, including against the reads around it.
+ describe('running a batch of calls', () => {
+ /** Records overlap: how many calls were in flight at the busiest moment. */
+ const withConcurrency = () => {
+ let live = 0;
+ let peak = 0;
+ driver = vi.fn(async (method: string) => {
+ if (method === 'mark') return { seq: 7 };
+ if (method === 'stepsSince') return stepsSince;
+ if (method === 'getDiagnostics') return diagnostics;
+ live++;
+ peak = Math.max(peak, live);
+ await new Promise((r) => setTimeout(r, 5));
+ live--;
+ return method === 'getSceneTree' ? [] : null;
+ }) as never;
+ (driver as { js: unknown }).js = vi.fn(async () => null);
+ (driver as { op: unknown }).op = vi.fn(async () => null);
+ return () => peak;
+ };
+
+ it('sends a run of reads together', async () => {
+ const peak = withConcurrency();
+ const s = fakeSession([asks(call('get_scene_tree'), call('get_stats'), call('get_document')), ends()]);
+ await runTurn(deps(s), 'look around', null, new AbortController().signal);
+ expect(peak()).toBeGreaterThan(1);
+ });
+
+ it('keeps a write to itself, and in order with the reads around it', async () => {
+ const peak = withConcurrency();
+ const s = fakeSession([asks(call('get_scene_tree'), call('add_entity'), call('get_stats')), ends()]);
+ await runTurn(deps(s), 'read, write, read', null, new AbortController().signal);
+ expect(peak()).toBe(1);
+ // Results still line up with the calls that produced them.
+ expect(s.results[0].map((o) => o.id))
+ .toEqual(['cget_scene_tree', 'cadd_entity', 'cget_stats']);
+ });
+ });
});