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): see a batch of scene edits before it lands, and strike out part of it

esenginef840f850f9aa
diff --git a/desktop/electron/agent/host.ts b/desktop/electron/agent/host.ts
index e7361f336..80bb92505 100644
--- a/desktop/electron/agent/host.ts
+++ b/desktop/electron/agent/host.ts
@@ -23,7 +23,9 @@
*/
import { runTurn, agentTools } from './kernel';
import { SYSTEM_PROMPT, editorContext } from './prompt';
-import type { AgentEvent, AgentProvider, AgentSession, ConfirmAnswer, ConfirmRequest } from './types';
+import type {
+ AgentEvent, AgentProvider, AgentSession, ConfirmAnswer, ConfirmDecision, ConfirmRequest,
+} from './types';
import type { SurfaceDriver } from '../surfaceDriver';
export type AgentPhase = 'idle' | 'running' | 'awaiting_confirm';
@@ -66,7 +68,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, answer: ConfirmAnswer): void;
+ confirm(callId: string, answer: ConfirmAnswer, declined?: readonly number[]): void;
/** Drop the conversation and start over; the next turn re-reads the key. */
reset(): AgentStatus;
/**
@@ -101,7 +103,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, (answer: ConfirmAnswer) => void>();
+ const pending = new Map<string, (decision: ConfirmDecision) => void>();
const status = (): AgentStatus => ({
ready: deps.ready(),
@@ -141,12 +143,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('no');
+ for (const resolve of pending.values()) resolve({ answer: 'no' });
pending.clear();
};
- const confirm = (request: ConfirmRequest): Promise<ConfirmAnswer> =>
- new Promise<ConfirmAnswer>((resolve) => {
+ const confirm = (request: ConfirmRequest): Promise<ConfirmDecision> =>
+ new Promise<ConfirmDecision>((resolve) => {
pending.set(request.callId, resolve);
phase = 'awaiting_confirm';
pushStatus();
@@ -227,11 +229,11 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
// not interrupt — it is waiting on us, not on the model.
settlePending();
},
- confirm: (callId, answer) => {
+ confirm: (callId, answer, declined) => {
const resolve = pending.get(callId);
if (!resolve) return;
pending.delete(callId);
- resolve(answer);
+ resolve({ answer, declined });
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 2ff58e50a..e61685937 100644
--- a/desktop/electron/agent/kernel.ts
+++ b/desktop/electron/agent/kernel.ts
@@ -30,11 +30,23 @@ export const agentTools = (): readonly CatalogTool[] => catalog;
/** Why `tool` needs saying out loud. A code — the editor renders the sentence,
* because it is the side that knows the reader's language. */
function confirmReason(tool: CatalogTool): ConfirmReason {
+ if (tool.name === BULK_EDIT_TOOL) return 'bulk_edit';
return tool.name === 'run_editor_command' || tool.name === 'play_probe'
? 'arbitrary_code'
: 'irreversible';
}
+/**
+ * The one undoable tool that still stops to ask.
+ *
+ * Not for safety — it is one undo step. For SIZE: it authors a subtree in a
+ * single call, and a hundred-node edit is worth seeing before it lands rather
+ * than reading back afterwards. The window renders the preview, since that takes
+ * the scene. "Allow for this run" turns it off for the rest of the run, which is
+ * what keeps a long build from becoming a hundred prompts.
+ */
+const BULK_EDIT_TOOL = 'apply_scene_ops';
+
/**
* The result as the transcript's disclosure shows it: bounded so a tool that
* returns a megabyte cannot cost the renderer that much, but NOT flattened —
@@ -179,6 +191,22 @@ export async function runTurn(
const MAX_ROUNDS = 48;
+/**
+ * The batch minus the lines the person struck out, or null when nothing is left.
+ *
+ * Only the ops array is rewritten; the dependency pruning that makes the
+ * remainder runnable lives with the preview that produced the indices
+ * (engine/sceneOpsPreview), so main is not a second opinion on what depends on
+ * what. A batch given by `opsPath` is not previewable and is left alone.
+ */
+function keptOps(input: Record<string, unknown>, declined: readonly number[]): Record<string, unknown> | null {
+ const ops = input.ops;
+ if (!Array.isArray(ops)) return input;
+ const drop = new Set(declined);
+ const kept = ops.filter((_, i) => !drop.has(i));
+ return kept.length === 0 ? null : { ...input, ops: kept };
+}
+
/** True when a call cannot change anything, so it may run alongside others. */
function isRead(call: ToolCall): boolean {
const tool = byName.get(call.name);
@@ -208,10 +236,12 @@ async function execute(
// `irreversible` is where undo stops being an answer, so it is where the
// person has to be.
// Already waved through for the rest of this run — see ConfirmAnswer.
- if (irreversible(tool) && !allowed.has(call.name)) {
+ const gated = irreversible(tool) || call.name === BULK_EDIT_TOOL;
+ let input = call.input;
+ if (gated && !allowed.has(call.name)) {
const request = { callId: call.id, tool: call.name, reason: confirmReason(tool), input: call.input };
emit({ type: 'awaiting_confirm', request });
- const answer = await confirm(request);
+ const { answer, declined } = 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.';
@@ -219,9 +249,27 @@ async function execute(
return { outcome: { id: call.id, content, isError: false }, mutated: false };
}
if (answer === 'turn') allowed.add(call.name);
+ if (declined?.length) {
+ const kept = keptOps(call.input, declined);
+ if (kept === null) {
+ // Everything was struck out — running an empty batch would report
+ // success for work nobody accepted.
+ emit({ type: 'tool_end', id: call.id, ok: false, summary: 'declined' });
+ return {
+ outcome: {
+ id: call.id,
+ content: `the user struck out every operation of ${call.name}. Do not retry it as-is; `
+ + 'ask what they wanted different.',
+ isError: false,
+ },
+ mutated: false,
+ };
+ }
+ input = kept;
+ }
}
- const result = await runTool(tool, driver, call.input, true) as {
+ const result = await runTool(tool, driver, input, true) as {
content: Array<{ type: string; text?: string; data?: string }>;
isError?: boolean;
};
diff --git a/desktop/electron/agent/types.ts b/desktop/electron/agent/types.ts
index 543e49ed1..1bfb33a68 100644
--- a/desktop/electron/agent/types.ts
+++ b/desktop/electron/agent/types.ts
@@ -123,7 +123,14 @@ export type ConfirmReason =
/** Escapes the undo stack — a file, a project setting, an export. */
| 'irreversible'
/** Runs code the agent wrote, so its effect is whatever that code does. */
- | 'arbitrary_code';
+ | 'arbitrary_code'
+ /**
+ * Authors a whole subtree at once. Undoable, so this is not about safety — it
+ * is about seeing a hundred-node edit BEFORE it lands, while saying no to part
+ * of it is still free. The window renders the preview, because reading what a
+ * batch would change takes the scene, and the scene is on that side.
+ */
+ | 'bulk_edit';
/** A tool the user has to say yes to before it runs (see `effect`). */
export interface ConfirmRequest {
@@ -133,6 +140,17 @@ export interface ConfirmRequest {
input: Record<string, unknown>;
}
+/** What came back, and — for a previewed batch — which lines were struck out. */
+export interface ConfirmDecision {
+ answer: ConfirmAnswer;
+ /**
+ * Indices into the batch's `ops` the person declined. The rest still runs; the
+ * kernel drops anything that depended on a declined line, because a `set` on
+ * an entity that was never created is a throw, not a smaller change.
+ */
+ declined?: readonly number[];
+}
+
/**
* How one of those was answered.
*
@@ -190,7 +208,7 @@ export interface KernelDeps {
* no name for itself, and the host is where that name is known. */
model: string;
/** Ask the person. `no` is declined, which the model is told about. */
- confirm(request: ConfirmRequest): Promise<ConfirmAnswer>;
+ confirm(request: ConfirmRequest): Promise<ConfirmDecision>;
emit(event: AgentEvent): void;
}
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index c71ab0400..cc54ea259 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -701,7 +701,10 @@ 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, answer: ConfirmAnswer) => agentHost.confirm(callId, answer));
+ipcMain.handle(
+ 'agent:confirm',
+ (_e, callId: string, answer: ConfirmAnswer, declined?: number[]) => agentHost.confirm(callId, answer, declined),
+);
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 e3dcf0e26..3d9c27a3b 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -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, answer: ConfirmAnswer): Promise<void> =>
- ipcRenderer.invoke('agent:confirm', callId, answer),
+ confirm: (callId: string, answer: ConfirmAnswer, declined?: readonly number[]): Promise<void> =>
+ ipcRenderer.invoke('agent:confirm', callId, answer, declined),
/** 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 43a9db7a4..5a3a796d3 100644
--- a/desktop/src/components/AgentDrawer.tsx
+++ b/desktop/src/components/AgentDrawer.tsx
@@ -47,6 +47,8 @@ import { dockApi } from '@/layout/dockApi';
import { EditorHistory, type HistoryMark } from '@/engine/EditorHistory';
import { useSelection } from '@/store/selectionStore';
import { EditorControlSurface } from '@/engine/EditorSession';
+import { previewSceneOps, withoutDeclined, type PreviewScene } from '@/engine/sceneOpsPreview';
+import type { SceneOp } from '@/engine/sceneOps';
import { ProjectStore } from '@/project/ProjectStore';
import { t } from '@/i18n';
@@ -56,7 +58,10 @@ const TOOL_ICON: Record<string, typeof Eye> = {
irreversible: TriangleAlert,
};
-function ToolRow({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (answer: ConfirmAnswer) => void }) {
+function ToolRow({ entry, onConfirm }: {
+ entry: AgentToolEntry;
+ onConfirm: (answer: ConfirmAnswer, declined?: readonly number[]) => 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
@@ -92,7 +97,9 @@ function ToolRow({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (answ
<Fold open={open}><div className="ag-call-detail">{entry.summary}</div></Fold>
)}
</div>
- {entry.state === 'awaiting' && <ConfirmPassage entry={entry} onConfirm={onConfirm} />}
+ {entry.state === 'awaiting' && (entry.reason === 'bulk_edit'
+ ? <PreviewPassage entry={entry} onConfirm={onConfirm} />
+ : <ConfirmPassage entry={entry} onConfirm={onConfirm} />)}
</>
);
}
@@ -102,6 +109,90 @@ function ToolRow({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (answ
* unconditionally when it appears — a question you never saw is a turn that
* looks hung.
*/
+/**
+ * A batch of scene edits, read before it lands.
+ *
+ * The change set below a finished run answers "what happened"; this answers
+ * "what is about to", while saying no to part of it still costs nothing. Lines
+ * are struck out rather than removed, and striking a create takes the ops that
+ * address it — running a `set` on an entity that was never created is a throw,
+ * not a smaller edit — so the consequence is visible before you commit to it.
+ */
+function PreviewPassage({ entry, onConfirm }: {
+ entry: AgentToolEntry;
+ onConfirm: (answer: ConfirmAnswer, declined?: readonly number[]) => void;
+}) {
+ const ref = useRef<HTMLDivElement>(null);
+ const [struck, setStruck] = useState<ReadonlySet<number>>(new Set());
+ useEffect(() => { ref.current?.scrollIntoView({ block: 'nearest' }); }, []);
+
+ const ops = Array.isArray(entry.input.ops) ? (entry.input.ops as SceneOp[]) : null;
+ const preview = ops ? previewSceneOps(ops, editorScene) : [];
+ // What striking these lines actually costs, dependents included.
+ const dropped = ops ? new Set(withoutDeclined(ops, struck).dropped) : new Set<number>();
+ const keeping = preview.length - dropped.size;
+
+ const toggle = (index: number) => setStruck((was) => {
+ const next = new Set(was);
+ if (next.has(index)) next.delete(index);
+ else next.add(index);
+ return next;
+ });
+
+ return (
+ <div ref={ref} className="ag-ask ag-ask--preview">
+ <span className="ag-ask-g"><Pencil size={16} strokeWidth={1.8} /></span>
+ <span className="ag-ask-hd">{t('agent.preview.title', { count: preview.length })}</span>
+ <div className="ag-ask-d">{t('agent.preview.why')}</div>
+ <div className="ag-preview">
+ {preview.map((line) => (
+ <button
+ type="button"
+ key={line.index}
+ className={`ag-pv ag-pv--${line.kind}${dropped.has(line.index) ? ' struck' : ''}`}
+ onClick={() => toggle(line.index)}
+ onMouseEnter={() => line.entity !== null && peekEntities([line.entity])}
+ onMouseLeave={() => peekEntities([])}
+ >
+ <span className="ag-pv-s">{line.kind === 'add' ? '+' : line.kind === 'remove' ? '−' : '~'}</span>
+ <span className="ag-pv-t">
+ {line.target}
+ {line.detail && <span className="ag-pv-d"> {line.detail}</span>}
+ {line.components?.length ? <span className="ag-pv-d"> {line.components.join(', ')}</span> : null}
+ </span>
+ {line.fields?.length ? <span className="ag-pv-n">{line.fields.length}</span> : null}
+ </button>
+ ))}
+ </div>
+ <div className="ag-ask-acts">
+ <button
+ type="button"
+ className="ag-go"
+ onClick={() => onConfirm('once', struck.size ? [...struck] : undefined)}
+ >
+ {struck.size ? t('agent.preview.applyKept', { count: keeping }) : t('agent.preview.apply')}
+ </button>
+ {/* Trusting the batch once is different from not wanting to be asked
+ again this run — the second is what makes a long build bearable. */}
+ <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>
+ );
+}
+
+/** The preview reads names and current values straight from the live scene. */
+const editorScene: PreviewScene = {
+ entityName: (id) => EditorControlSurface.getEntity(id)?.name ?? null,
+ fieldValue: (id, component, key) => EditorControlSurface.getFieldValue(id, component, key) ?? undefined,
+};
+
function ConfirmPassage({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (answer: ConfirmAnswer) => void }) {
const ref = useRef<HTMLDivElement>(null);
const target = describeTarget(entry.input);
@@ -209,7 +300,7 @@ function Prose({ text, streaming, onRerun }: { text: string; streaming?: boolean
/** Consecutive tool rows are one hairline-divided block; prose breaks the run. */
function Entries({ entries, onConfirm, streaming, onRerun }: {
entries: readonly AgentEntry[];
- onConfirm: (callId: string, answer: ConfirmAnswer) => void;
+ onConfirm: (callId: string, answer: ConfirmAnswer, declined?: readonly number[]) => void;
/** The run is still taking events, so the last entry is mid-write. */
streaming?: boolean;
/** Ask this run again. Absent while one is running — see Turn. */
@@ -224,7 +315,7 @@ function Entries({ entries, onConfirm, streaming, onRerun }: {
out.push(
<div className="ag-steps" key={`steps-${group[0].id}`}>
{group.map((tool) => (
- <ToolRow key={tool.id} entry={tool} onConfirm={(answer) => onConfirm(tool.id, answer)} />
+ <ToolRow key={tool.id} entry={tool} onConfirm={(answer, declined) => onConfirm(tool.id, answer, declined)} />
))}
</div>,
);
diff --git a/desktop/src/engine/sceneOpsPreview.ts b/desktop/src/engine/sceneOpsPreview.ts
new file mode 100644
index 000000000..b823aa63d
--- /dev/null
+++ b/desktop/src/engine/sceneOpsPreview.ts
@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file sceneOpsPreview.ts — what a batch of scene ops WOULD do, before it does it.
+ *
+ * The change set the drawer already shows is read from EditorHistory, so it can
+ * only answer after the fact: you see what happened, and your recourse is to
+ * revert the whole run. This answers the same question in the other direction —
+ * what is about to happen, while saying no is still free.
+ *
+ * Derived rather than rehearsed. A dry run would mean executing the batch
+ * against a scratch copy of the scene and diffing it, which is both expensive
+ * and a second implementation of applySceneOps to keep in step. The ops are
+ * already declarative — each one names what it does and to what — so the
+ * preview is a fold over the program plus ONE read of the scene for the values
+ * being replaced. Nothing is mutated, and nothing has to be undone if the
+ * person says no.
+ *
+ * What it cannot know, it does not claim: a `template` expands to components
+ * this module does not resolve (that needs the async source build), and an
+ * entity created by an earlier op has no name in the scene yet. Both are
+ * reported as what the op SAYS, which is what the person is being asked about.
+ */
+import type { EntityId } from '@/types';
+import type { SceneOp, EntityRef } from './sceneOps';
+
+export type PreviewKind = 'add' | 'modify' | 'remove';
+
+/** One field a `set` (or a `create`'s `fields`) would write. */
+export interface PreviewField {
+ /** `"Transform.position.x"`, as written. */
+ path: string;
+ /** What the scene holds now — absent for an entity this batch is creating. */
+ before?: unknown;
+ after: unknown;
+}
+
+/** One line of the preview: an op, said in the scene's terms rather than the program's. */
+export interface PreviewEntry {
+ /** Index in the original program — what a caller drops to decline this line. */
+ index: number;
+ kind: PreviewKind;
+ /** The op's verb, for the row's label. */
+ op: SceneOp['op'];
+ /** The entity as the person would name it: its scene name, or the op's `ref`. */
+ target: string;
+ /** Resolved id, when the op addresses one that already exists. */
+ entity: EntityId | null;
+ /** Components being added (create/add_component) or removed. */
+ components?: string[];
+ fields?: PreviewField[];
+ /** For `parent` / `rename`: what it becomes. */
+ detail?: string;
+ /** Ops that cannot run without this one — declining it declines them too. */
+ dependents?: number[];
+}
+
+/** What the preview needs from the editor: names and current values, nothing else. */
+export interface PreviewScene {
+ entityName(id: EntityId): string | null;
+ fieldValue(id: EntityId, component: string, key: string): unknown;
+}
+
+const KIND: Record<SceneOp['op'], PreviewKind> = {
+ create: 'add',
+ set: 'modify',
+ add_component: 'modify',
+ remove_component: 'modify',
+ rename: 'modify',
+ parent: 'modify',
+ delete: 'remove',
+};
+
+/** Split `"Component.key"` the way sceneOps does — only the FIRST dot separates. */
+function splitPath(path: string): { component: string; key: string } | null {
+ const dot = path.indexOf('.');
+ if (dot <= 0 || dot === path.length - 1) return null;
+ return { component: path.slice(0, dot), key: path.slice(dot + 1) };
+}
+
+const refName = (ref: EntityRef): string =>
+ (typeof ref === 'string' && ref.startsWith('$') ? ref.slice(1) : String(ref));
+
+/**
+ * Read `ops` as the list of changes it would make.
+ *
+ * `scene` is consulted only for entities that already exist: their name, and the
+ * value a write would replace. An op addressing `"$ref"` refers to something
+ * this batch creates, which has neither yet.
+ */
+export function previewSceneOps(ops: readonly SceneOp[], scene: PreviewScene): PreviewEntry[] {
+ // ref → the op that creates it, so a declined create can take its dependents.
+ const createdBy = new Map<string, number>();
+ ops.forEach((op, i) => {
+ if (op.op === 'create' && op.ref) createdBy.set(op.ref, i);
+ });
+
+ const dependents = new Map<number, number[]>();
+ const noteDependency = (ref: EntityRef | null | undefined, from: number): void => {
+ if (typeof ref !== 'string') return;
+ const owner = createdBy.get(refName(ref));
+ if (owner === undefined || owner === from) return;
+ const list = dependents.get(owner) ?? [];
+ list.push(from);
+ dependents.set(owner, list);
+ };
+
+ /** A live id, or null when the op names something this batch has yet to create. */
+ const liveId = (ref: EntityRef | null | undefined): EntityId | null =>
+ (typeof ref === 'number' ? (ref as EntityId) : null);
+
+ const describe = (ref: EntityRef | null | undefined): string => {
+ if (ref == null) return '(root)';
+ const id = liveId(ref);
+ if (id === null) return refName(ref);
+ return scene.entityName(id) ?? `#${id}`;
+ };
+
+ const entries: PreviewEntry[] = ops.map((op, index) => {
+ const base = { index, kind: KIND[op.op], op: op.op };
+
+ if (op.op === 'create') {
+ noteDependency(op.parent, index);
+ const fields = Object.entries(op.fields ?? {}).map(([path, after]) => ({ path, after }));
+ return {
+ ...base,
+ target: op.name ?? op.ref ?? '(unnamed)',
+ entity: null,
+ components: op.template
+ ? [op.template]
+ : (op.components ?? []).map((c) => (typeof c === 'string' ? c : c.type)),
+ ...(fields.length ? { fields } : {}),
+ ...(op.parent != null ? { detail: `under ${describe(op.parent)}` } : {}),
+ };
+ }
+
+ noteDependency(op.entity, index);
+ const id = liveId(op.entity);
+ const target = describe(op.entity);
+
+ switch (op.op) {
+ case 'set': {
+ const fields = Object.entries(op.fields).map(([path, after]) => {
+ const split = id !== null ? splitPath(path) : null;
+ const before = split ? scene.fieldValue(id!, split.component, split.key) : undefined;
+ return before === undefined ? { path, after } : { path, before, after };
+ });
+ return { ...base, target, entity: id, fields };
+ }
+ case 'add_component':
+ case 'remove_component':
+ return { ...base, target, entity: id, components: [op.component] };
+ case 'rename':
+ return { ...base, target, entity: id, detail: op.name };
+ case 'parent': {
+ noteDependency(op.parent, index);
+ return { ...base, target, entity: id, detail: `under ${describe(op.parent)}` };
+ }
+ default:
+ return { ...base, target, entity: id };
+ }
+ });
+
+ for (const [owner, list] of dependents) entries[owner].dependents = list;
+ return entries;
+}
+
+/**
+ * The batch with `declined` (and everything that depends on it) removed.
+ *
+ * Dependents travel with their create because the program addresses them by
+ * `"$ref"`: running a `set` whose entity was never created is not a smaller
+ * change, it is a throw that rolls the rest back.
+ */
+export function withoutDeclined(
+ ops: readonly SceneOp[],
+ declined: ReadonlySet<number>,
+): { ops: SceneOp[]; dropped: number[] } {
+ const preview = previewSceneOps(ops, { entityName: () => null, fieldValue: () => undefined });
+ const drop = new Set(declined);
+ // A dependent can itself create a ref others depend on, so keep going until
+ // the set stops growing rather than assuming one level.
+ for (let grew = true; grew;) {
+ grew = false;
+ for (const entry of preview) {
+ if (!drop.has(entry.index)) continue;
+ for (const dep of entry.dependents ?? []) {
+ if (!drop.has(dep)) { drop.add(dep); grew = true; }
+ }
+ }
+ }
+ return {
+ ops: ops.filter((_, i) => !drop.has(i)),
+ dropped: [...drop].sort((a, b) => a - b),
+ };
+}
diff --git a/desktop/src/i18n/messages/agent.ts b/desktop/src/i18n/messages/agent.ts
index e12b9b279..a2ca58b34 100644
--- a/desktop/src/i18n/messages/agent.ts
+++ b/desktop/src/i18n/messages/agent.ts
@@ -90,6 +90,16 @@ export const agentMessages = defineMessages({
en: 'It runs code the agent wrote, so its effect is whatever that code does.',
zh: '它会执行 Agent 自己写的代码,效果取决于那段代码。',
},
+ 'agent.preview.title': {
+ en: '{count} scene changes, before they land',
+ zh: '{count} 项场景改动,尚未应用',
+ },
+ 'agent.preview.why': {
+ en: 'Click a line to strike it out. Striking a new entity also strikes what refers to it.',
+ zh: '点击某一行可划掉它。划掉一个新建实体时,引用它的行会一并划掉。',
+ },
+ 'agent.preview.apply': { en: 'Apply all', zh: '全部应用' },
+ 'agent.preview.applyKept': { en: 'Apply {count}', zh: '应用 {count} 项' },
'agent.confirm.allow': { en: 'Run it', zh: '执行' },
'agent.confirm.allowTurn': { en: 'Allow for this run', zh: '本轮都允许' },
'agent.confirm.allowTurn.why': {
diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.ts
index a940f4b4c..e3038d3eb 100644
--- a/desktop/src/store/AgentStore.ts
+++ b/desktop/src/store/AgentStore.ts
@@ -515,7 +515,7 @@ 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, answer: ConfirmAnswer): void {
+export function confirmAgentCall(callId: string, answer: ConfirmAnswer, declined?: readonly number[]): void {
useAgent.setState((s) => {
const open = openTurn(s.turns);
if (!open) return {};
@@ -528,7 +528,7 @@ export function confirmAgentCall(callId: string, answer: ConfirmAnswer): void {
}),
};
});
- void window.estella?.agent?.confirm(callId, answer);
+ void window.estella?.agent?.confirm(callId, answer, declined);
}
/** Drop the conversation — a new one starts with the next message. */
diff --git a/desktop/src/theme/agent.css b/desktop/src/theme/agent.css
index 19b49e794..75dc9ac96 100644
--- a/desktop/src/theme/agent.css
+++ b/desktop/src/theme/agent.css
@@ -281,6 +281,47 @@
border-left: 2px solid var(--ag-tone);
}
.ag-ask--confirm { --ag-tone: var(--warn); }
+/* A batch of scene edits waiting to land. Neutral rather than amber: nothing is
+ at risk here — it is one undo step — and colouring it like the irreversible
+ gate would spend the warning that gate depends on. */
+.ag-ask--preview { --ag-tone: var(--line-strong); }
+.ag-ask--preview > .ag-ask-g { color: var(--text-dim); }
+
+/* The lines themselves: the same +/~/− vocabulary the change set uses, because
+ they are the same facts asked in the other direction. */
+.ag-preview {
+ grid-column: 2;
+ margin-top: 9px;
+ max-height: 260px;
+ overflow: auto;
+ overscroll-behavior: contain;
+}
+.ag-pv {
+ display: grid;
+ grid-template-columns: 14px minmax(0, 1fr) auto;
+ gap: 9px;
+ align-items: baseline;
+ width: 100%;
+ padding: 3px 6px;
+ border-radius: var(--r-sm);
+ font: var(--fs-xs) var(--font-mono);
+ color: var(--text);
+ text-align: left;
+ transition: background var(--t-fast), opacity var(--t-fast);
+}
+.ag-pv:hover { background: var(--hover); }
+.ag-pv-s { text-align: center; font-weight: 600; }
+.ag-pv--add .ag-pv-s { color: var(--run); }
+.ag-pv--modify .ag-pv-s { color: var(--warn); }
+.ag-pv--remove .ag-pv-s { color: var(--error); }
+.ag-pv-t { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.ag-pv-d { color: var(--text-faint); }
+/* How many fields this line writes — the row is a summary, not the diff. */
+.ag-pv-n { color: var(--text-faint); font-size: var(--fs-2xs); }
+/* Struck, not removed: the line stays where it was so the consequence of
+ striking a create — its dependents going with it — is visible in place. */
+.ag-pv.struck { opacity: 0.4; }
+.ag-pv.struck .ag-pv-t { text-decoration: line-through; }
.ag-ask--fail { --ag-tone: var(--error); }
/* Arriving in a transcript that has been scrolling on its own, a question that
merely appeared is one you read past. It flashes ONCE, on arrival. */
diff --git a/desktop/tests/agent-kernel.test.ts b/desktop/tests/agent-kernel.test.ts
index ceb0ea33f..0e997f8a7 100644
--- a/desktop/tests/agent-kernel.test.ts
+++ b/desktop/tests/agent-kernel.test.ts
@@ -57,7 +57,7 @@ describe('the agent turn', () => {
events = [];
stepsSince = 0;
diagnostics = [];
- confirm = vi.fn(async () => 'once');
+ confirm = vi.fn(async () => ({ answer: 'once' }));
driver = vi.fn(async (method: string) => {
if (method === 'mark') return { seq: 7 };
if (method === 'stepsSince') return stepsSince;
@@ -112,7 +112,7 @@ describe('the agent turn', () => {
});
it('a decline is told to the model, not raised as a failure', async () => {
- confirm.mockResolvedValue('no');
+ confirm.mockResolvedValue({ answer: 'no' });
const s = fakeSession([asks(call('export_game', { platform: 'web' })), ends()]);
await runTurn(deps(s), 'ship it', null, new AbortController().signal);
@@ -165,7 +165,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 () => 'once');
+ confirm.mockImplementation(async () => ({ answer: 'once' }));
driver.mockImplementation(async (method: string) => {
if (method === 'mark') return { seq: 7 };
if (method === 'stepsSince') return stepsSince;
@@ -249,7 +249,7 @@ describe('the agent turn', () => {
});
it('stops asking for that tool once it is allowed for the run', async () => {
- confirm.mockResolvedValue('turn');
+ confirm.mockResolvedValue({ answer: '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);
@@ -259,7 +259,7 @@ describe('the agent turn', () => {
// 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');
+ confirm.mockResolvedValue({ answer: '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);
@@ -268,7 +268,7 @@ describe('the agent turn', () => {
// 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');
+ confirm.mockResolvedValue({ answer: '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);
@@ -315,4 +315,52 @@ describe('the agent turn', () => {
.toEqual(['cget_scene_tree', 'cadd_entity', 'cget_stats']);
});
});
+
+ // Authoring a subtree is one undo step, so this gate is not about safety — it
+ // is about seeing a hundred-node edit before it lands, while declining part of
+ // it still costs nothing.
+ describe('previewing a batch before it lands', () => {
+ const ops = [
+ { op: 'create', ref: 'root', name: 'Root' },
+ { op: 'create', ref: 'child', name: 'Child', parent: '$root' },
+ { op: 'rename', entity: 1, name: 'Renamed' },
+ ];
+ const batch = (): ToolCall => ({ id: 'cbatch', name: 'apply_scene_ops', input: { ops } });
+
+ it('asks, and says which kind of question it is', async () => {
+ const s = fakeSession([asks(batch()), ends()]);
+ await runTurn(deps(s), 'build it', null, new AbortController().signal);
+ expect(confirm).toHaveBeenCalledTimes(1);
+ expect(confirm.mock.calls[0][0]).toMatchObject({ tool: 'apply_scene_ops', reason: 'bulk_edit' });
+ });
+
+ it('runs only what survived, in order', async () => {
+ confirm.mockResolvedValue({ answer: 'once', declined: [1] });
+ const s = fakeSession([asks(batch()), ends()]);
+ await runTurn(deps(s), 'build it', null, new AbortController().signal);
+
+ const call = (driver as unknown as { mock: { calls: unknown[][] } }).mock.calls
+ .find((c) => c[0] === 'applyOps');
+ expect((call?.[1] as unknown[])[0]).toEqual([ops[0], ops[2]]);
+ });
+
+ // Applying nothing and reporting success would tell the model its work
+ // landed. It has to hear that the person said no to all of it.
+ it('treats an entirely struck-out batch as declined', async () => {
+ confirm.mockResolvedValue({ answer: 'once', declined: [0, 1, 2] });
+ const s = fakeSession([asks(batch()), ends()]);
+ await runTurn(deps(s), 'build it', null, new AbortController().signal);
+
+ expect(ran('apply_scene_ops')).toBe(true); // it was announced
+ expect(events.some((e) => e.type === 'tool_end' && !e.ok)).toBe(true);
+ expect(String(s.results[0][0].content)).toMatch(/struck out/i);
+ });
+
+ it('stops asking once the run is trusted', async () => {
+ confirm.mockResolvedValue({ answer: 'turn' });
+ const s = fakeSession([asks(batch(), batch()), ends()]);
+ await runTurn(deps(s), 'build it twice', null, new AbortController().signal);
+ expect(confirm).toHaveBeenCalledTimes(1);
+ });
+ });
});
diff --git a/desktop/tests/scene-ops-preview.test.ts b/desktop/tests/scene-ops-preview.test.ts
new file mode 100644
index 000000000..62e222f2e
--- /dev/null
+++ b/desktop/tests/scene-ops-preview.test.ts
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What a batch of scene ops would do, read before it does it.
+ *
+ * Derived from the program rather than rehearsed against a scratch scene:
+ * the ops are declarative, so the preview is a fold over them plus one
+ * read for the values being replaced. These pin the two things that makes
+ * non-obvious — that an op naming `"$ref"` refers to something not in the
+ * scene yet, and that declining a create has to take its dependents.
+ */
+import { describe, it, expect } from 'vitest';
+import { previewSceneOps, withoutDeclined, type PreviewScene } from '@/engine/sceneOpsPreview';
+import type { SceneOp } from '@/engine/sceneOps';
+
+/** A scene with two entities and one readable field. */
+const scene: PreviewScene = {
+ entityName: (id) => ({ 1: 'Panel', 2: 'Label' } as Record<number, string>)[id] ?? null,
+ fieldValue: (id, component, key) =>
+ (id === 1 && component === 'Transform' && key === 'position.x' ? 10 : undefined),
+};
+
+describe('previewing a batch of scene ops', () => {
+ it('names a create by what the op calls it, and lists what it seeds', () => {
+ const ops: SceneOp[] = [
+ { op: 'create', ref: 'root', name: 'PauseRoot', components: ['Transform', 'UINode'] },
+ ];
+ expect(previewSceneOps(ops, scene)[0]).toMatchObject({
+ kind: 'add', op: 'create', target: 'PauseRoot', entity: null,
+ components: ['Transform', 'UINode'],
+ });
+ });
+
+ // The whole reason this beats reading the raw program: an id means nothing to
+ // the person, and the scene knows what it is called.
+ it('names an existing entity the way the scene does', () => {
+ const ops: SceneOp[] = [{ op: 'rename', entity: 1, name: 'Backdrop' }];
+ expect(previewSceneOps(ops, scene)[0]).toMatchObject({
+ kind: 'modify', target: 'Panel', entity: 1, detail: 'Backdrop',
+ });
+ });
+
+ it('reads the value a write would replace', () => {
+ const ops: SceneOp[] = [
+ { op: 'set', entity: 1, fields: { 'Transform.position.x': 42, 'Text.content': 'hi' } },
+ ];
+ const [entry] = previewSceneOps(ops, scene);
+ // Known field: before and after. Unknown one: only what it becomes — claiming
+ // a `before` the scene did not give would be inventing it.
+ expect(entry.fields).toEqual([
+ { path: 'Transform.position.x', before: 10, after: 42 },
+ { path: 'Text.content', after: 'hi' },
+ ]);
+ });
+
+ // An entity this batch creates has no name and no values yet, and saying so is
+ // more honest than showing "#undefined" or a stale reading.
+ it('claims no before-value for something the batch has yet to create', () => {
+ const ops: SceneOp[] = [
+ { op: 'create', ref: 'panel', name: 'Panel2' },
+ { op: 'set', entity: '$panel', fields: { 'UIVisual.color': '#fff' } },
+ ];
+ const [, set] = previewSceneOps(ops, scene);
+ expect(set).toMatchObject({ target: 'panel', entity: null });
+ expect(set.fields).toEqual([{ path: 'UIVisual.color', after: '#fff' }]);
+ });
+
+ it('records which ops a create is holding up', () => {
+ const ops: SceneOp[] = [
+ { op: 'create', ref: 'root', name: 'Root' },
+ { op: 'create', ref: 'child', name: 'Child', parent: '$root' },
+ { op: 'set', entity: '$root', fields: { 'Transform.position.y': 1 } },
+ ];
+ expect(previewSceneOps(ops, scene)[0].dependents).toEqual([1, 2]);
+ });
+});
+
+describe('declining part of a batch', () => {
+ const ops: SceneOp[] = [
+ { op: 'create', ref: 'root', name: 'Root' },
+ { op: 'create', ref: 'child', name: 'Child', parent: '$root' },
+ { op: 'set', entity: '$child', fields: { 'Transform.position.x': 5 } },
+ { op: 'rename', entity: 1, name: 'Renamed' },
+ ];
+
+ it('keeps the rest when the declined op holds nothing up', () => {
+ const out = withoutDeclined(ops, new Set([3]));
+ expect(out.ops).toHaveLength(3);
+ expect(out.dropped).toEqual([3]);
+ });
+
+ // Running a `set` whose entity was never created is not a smaller change —
+ // it is a throw that rolls the whole batch back.
+ it('takes the dependents of a declined create, transitively', () => {
+ const out = withoutDeclined(ops, new Set([0]));
+ expect(out.dropped).toEqual([0, 1, 2]);
+ expect(out.ops).toEqual([{ op: 'rename', entity: 1, name: 'Renamed' }]);
+ });
+
+ it('leaves a batch nobody declined alone', () => {
+ expect(withoutDeclined(ops, new Set()).ops).toEqual(ops);
+ });
+});