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 drawer, and the palette branch that opens it

esengine7bae920e6c8e
diff --git a/desktop/electron/agent/kernel.ts b/desktop/electron/agent/kernel.ts
index 9a9178d06..ad575b6fe 100644
--- a/desktop/electron/agent/kernel.ts
+++ b/desktop/electron/agent/kernel.ts
@@ -13,7 +13,7 @@
* two would drift; there is one.
*/
import type {
- AgentEvent, CatalogTool, KernelDeps, ToolCall, ToolOutcome,
+ AgentEvent, CatalogTool, ConfirmReason, KernelDeps, ToolCall, ToolOutcome,
} from './types';
// Plain .mjs, shared with the MCP fronts — esbuild bundles it into main.
// @ts-expect-error untyped shared module
@@ -27,11 +27,12 @@ const byName = new Map(catalog.map((t) => [t.name, t]));
* ask, and this one has the user right there (see the confirm gate below). */
export const agentTools = (): readonly CatalogTool[] => catalog;
-/** Why `tool` needs saying out loud, phrased for the person who will read it. */
-function confirmReason(tool: CatalogTool): string {
+/** 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 {
return tool.name === 'run_editor_command' || tool.name === 'play_probe'
- ? 'runs code the agent wrote, so its effect is whatever that code does'
- : 'writes outside the scene, and Undo cannot take it back';
+ ? 'arbitrary_code'
+ : 'irreversible';
}
/** Short enough to render as one transcript row; the model gets the full text. */
diff --git a/desktop/electron/agent/types.ts b/desktop/electron/agent/types.ts
index d836a8225..f35315fed 100644
--- a/desktop/electron/agent/types.ts
+++ b/desktop/electron/agent/types.ts
@@ -74,12 +74,22 @@ export interface AgentProvider {
createSession(opts: { system: string; tools: readonly CatalogTool[] }): AgentSession;
}
+/**
+ * Why a call needs saying out loud. A code rather than a sentence: the person
+ * who reads it is in the editor, and the editor is the only side that knows
+ * their language.
+ */
+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';
+
/** A tool the user has to say yes to before it runs (see `effect`). */
export interface ConfirmRequest {
callId: string;
tool: string;
- /** Why it needs asking, already phrased for a person. */
- reason: string;
+ reason: ConfirmReason;
input: Record<string, unknown>;
}
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 857241ce3..9964061f2 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -7,6 +7,7 @@ import { StatusBar } from '@/layout/StatusBar';
import { DockLayout } from '@/layout/DockLayout';
import { ActivityBar } from '@/layout/ActivityBar';
import { ContentDrawer } from '@/layout/ContentDrawer';
+import { AgentDrawer } from '@/components/AgentDrawer';
import '@/engine/EditorSession'; // side effect: constructs defaultSession → wires the editor engine
import '@/document/dirtyDocs'; // side effect: registers scene + asset docs on the DirtyRegistry
import { Launcher } from '@/launcher/Launcher';
@@ -296,6 +297,7 @@ export function App() {
<main className="shell__workspace">
<ErrorBoundary label="activitybar"><Perf id="activitybar"><ActivityBar /></Perf></ErrorBoundary>
<DockLayout />
+ <ErrorBoundary label="agentdrawer"><Perf id="agentdrawer"><AgentDrawer /></Perf></ErrorBoundary>
</main>
<ErrorBoundary label="statusbar"><Perf id="statusbar"><StatusBar /></Perf></ErrorBoundary>
<ErrorBoundary label="contentdrawer"><Perf id="contentdrawer"><ContentDrawer /></Perf></ErrorBoundary>
diff --git a/desktop/src/commands/editorCommands.ts b/desktop/src/commands/editorCommands.ts
index ecc8ec7d9..c2d4c3967 100644
--- a/desktop/src/commands/editorCommands.ts
+++ b/desktop/src/commands/editorCommands.ts
@@ -488,6 +488,14 @@ commands.register({
keybinding: 'mod+,',
run: () => editor().setSettingsOpen(true),
});
+// No chord of its own: the palette already takes a sentence, and the design's
+// "zero new pixels of entry" means one more overlay is one too many.
+commands.register({
+ id: 'agent.open',
+ label: t('agent.open'),
+ category: t('cat.editor'),
+ run: () => editor().setAgentDrawer(true),
+});
commands.register({
id: 'palette.open',
label: t('cmd.palette.open'),
diff --git a/desktop/src/commands/palette.ts b/desktop/src/commands/palette.ts
index 76a2bb4ae..cb67f9c9f 100644
--- a/desktop/src/commands/palette.ts
+++ b/desktop/src/commands/palette.ts
@@ -49,6 +49,25 @@ export function fuzzyScore(query: string, text: string): number | null {
return score;
}
+/**
+ * Whether a query reads as something SAID rather than something named — the
+ * palette's one branch between running a command and handing the text to the
+ * agent.
+ *
+ * Two signals, because commands are terse identifiers and sentences are not: a
+ * space, or a CJK character (which needs no spaces to be a sentence). Length
+ * rules out "up", "ui " and a half-typed word.
+ *
+ * Deliberately generous, because it only decides whether the row is OFFERED.
+ * Whether it is also SELECTED is the caller's business, and the rule there is
+ * the strict one — a query matching a real command keeps that command under
+ * Enter, so "save scene" still saves the scene.
+ */
+export function readsAsSentence(query: string): boolean {
+ const q = query.trim();
+ return q.length > 3 && (/\s/.test(q) || /[㐀-鿿぀-ヿ]/.test(q));
+}
+
/**
* Filter + rank items for a query. Empty query preserves registration order
* (commands group naturally by category); otherwise best score first, ties
diff --git a/desktop/src/components/AgentDrawer.tsx b/desktop/src/components/AgentDrawer.tsx
new file mode 100644
index 000000000..6e92fe985
--- /dev/null
+++ b/desktop/src/components/AgentDrawer.tsx
@@ -0,0 +1,421 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AgentDrawer.tsx
+ * @brief The conversation with the built-in agent, rendered from AgentStore's
+ * projection of what main is doing.
+ *
+ * Three decisions carried over from the design, because they are what make this
+ * different from a chat panel bolted onto an editor:
+ *
+ * A RUN IS THE UNIT. Each turn gets its own header — what was asked, and the
+ * numbers you actually check afterwards. Only the run you are IN sticks; every
+ * past header sticking would stack into a pile the moment there are three.
+ * Finished runs fold to that header, because the stat line already IS the
+ * summary and the transcript below is the evidence for it.
+ *
+ * DECISIONS ARE PASSAGES, NOT DIALOGS. A modal would steal focus while you
+ * are watching the viewport for the result. A confirmation is a passage in the
+ * transcript with a rule above and below and a coloured edge — and the path it
+ * wants to write is never truncated, because approving a write to a file whose
+ * name has been hidden is the one thing this interaction must not do.
+ *
+ * COLOUR MEANS SOMETHING. Green added, red failed, amber needs you. Nothing
+ * is tinted for belonging to the agent.
+ */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import {
+ X, Plus, PanelRight, ArrowUp, Square, ChevronRight, Check, TriangleAlert,
+ Loader, Copy, Pencil, Eye, KeyRound, Boxes, Stethoscope, Image as ImageIcon,
+} from 'lucide-react';
+import { useEditorStore } from '@/store/editorStore';
+import {
+ useAgent, sendAgentMessage, stopAgentTurn, confirmAgentCall, resetAgentSession,
+ type AgentTurn, type AgentEntry, type AgentToolEntry,
+} from '@/store/AgentStore';
+import { t } from '@/i18n';
+
+const TOOL_ICON: Record<string, typeof Eye> = {
+ read: Eye,
+ undoable: Pencil,
+ irreversible: TriangleAlert,
+};
+
+function ToolRow({ entry, onConfirm }: { entry: AgentToolEntry; onConfirm: (allow: boolean) => void }) {
+ const [open, setOpen] = useState(false);
+ const Icon = TOOL_ICON[entry.effect ?? 'read'] ?? Eye;
+ const arg = summarizeInput(entry.input);
+ return (
+ <>
+ <div className={`ag-call ag-call--${entry.state}`}>
+ <button type="button" className="ag-call-top" onClick={() => setOpen((o) => !o)}>
+ <span className="ag-call-g"><Icon size={13} strokeWidth={1.8} /></span>
+ <span className="ag-call-nm">{entry.name}</span>
+ <span className="ag-call-arg">{arg}</span>
+ <span className="ag-call-out">
+ {entry.state === 'queued' && t('agent.queued')}
+ {entry.state === 'running' && <Loader size={11} className="ag-spin" />}
+ {entry.state === 'awaiting' && <TriangleAlert size={11} />}
+ {entry.state === 'stopped' && t('agent.stopped')}
+ {entry.state === 'declined' && t('agent.declined')}
+ {(entry.state === 'ok' || entry.state === 'error') && entry.summary}
+ </span>
+ </button>
+ {open && entry.summary && <div className="ag-call-detail">{entry.summary}</div>}
+ </div>
+ {entry.state === 'awaiting' && <ConfirmPassage entry={entry} onConfirm={onConfirm} />}
+ </>
+ );
+}
+
+/**
+ * The one thing the agent cannot do without you. Scrolled into view
+ * 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 }) {
+ const ref = useRef<HTMLDivElement>(null);
+ const target = describeTarget(entry.input);
+ useEffect(() => {
+ ref.current?.scrollIntoView({ block: 'nearest' });
+ }, []);
+ return (
+ <div ref={ref} className="ag-ask ag-ask--confirm">
+ <span className="ag-ask-g"><TriangleAlert size={16} strokeWidth={1.8} /></span>
+ <span className="ag-ask-hd">{t('agent.confirm.title', { tool: entry.name })}</span>
+ <div className="ag-ask-d">
+ {entry.reason === 'arbitrary_code'
+ ? t('agent.confirm.why.arbitrary_code')
+ : t('agent.confirm.why.irreversible')}
+ </div>
+ {/* Never truncated, and it wraps rather than scrolls: this is the whole
+ basis on which someone says yes. Absent when the call names no target —
+ 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>
+ </div>
+ </div>
+ );
+}
+
+function Thinking({ text }: { text: string }) {
+ const [open, setOpen] = useState(false);
+ return (
+ <div className={`ag-think${open ? ' open' : ''}`}>
+ <button type="button" className="ag-think-t" onClick={() => setOpen((o) => !o)}>
+ <ChevronRight size={10} strokeWidth={2} className="ag-car" />
+ <span>{t('agent.thinking')}</span>
+ </button>
+ {open && <div className="ag-think-body">{text}</div>}
+ </div>
+ );
+}
+
+function Prose({ text }: { text: string }) {
+ const [copied, setCopied] = useState(false);
+ return (
+ <div className="ag-say">
+ {text}
+ <button
+ type="button"
+ className="ag-say-copy"
+ title={t('agent.copy')}
+ onClick={() => {
+ void navigator.clipboard?.writeText(text);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 900);
+ }}
+ >
+ {copied ? <Check size={12} /> : <Copy size={12} />}
+ </button>
+ </div>
+ );
+}
+
+/** Consecutive tool rows are one hairline-divided block; prose breaks the run. */
+function Entries({ entries, onConfirm }: {
+ entries: readonly AgentEntry[];
+ onConfirm: (callId: string, allow: boolean) => void;
+}) {
+ const out: React.ReactNode[] = [];
+ let run: AgentToolEntry[] = [];
+ const flush = () => {
+ if (run.length === 0) return;
+ const group = run;
+ run = [];
+ 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)} />
+ ))}
+ </div>,
+ );
+ };
+ entries.forEach((entry, i) => {
+ if (entry.kind === 'tool') {
+ run.push(entry);
+ return;
+ }
+ flush();
+ if (entry.kind === 'error') {
+ out.push(
+ <div className="ag-ask ag-ask--fail" key={i}>
+ <span className="ag-ask-g"><TriangleAlert size={16} strokeWidth={1.8} /></span>
+ <span className="ag-ask-hd">{entry.message}</span>
+ </div>,
+ );
+ } else if (entry.kind === 'thinking') out.push(<Thinking key={i} text={entry.text} />);
+ else out.push(<Prose key={i} text={entry.text} />);
+ });
+ flush();
+ return <>{out}</>;
+}
+
+/** Waiting on the first token: a shimmer, not a spinner — it says how much is
+ * coming, and a spinner in a text column says only "something". */
+function Skeleton() {
+ return (
+ <div className="ag-wait">
+ <div className="ag-wait-t"><span className="ag-dots"><i /><i /><i /></span>{t('agent.waiting')}</div>
+ <div className="ag-skel" /><div className="ag-skel s2" /><div className="ag-skel s3" />
+ </div>
+ );
+}
+
+function Turn({ turn, isLast, running }: { turn: AgentTurn; isLast: boolean; running: boolean }) {
+ // Past runs arrive folded; the one you are in stays open. Local state so the
+ // user's own fold survives the next event landing in the store.
+ const [folded, setFolded] = useState(!isLast);
+ useEffect(() => {
+ if (isLast) setFolded(false);
+ }, [isLast]);
+
+ const tokens = turn.inputTokens + turn.outputTokens;
+ const empty = turn.entries.length === 0;
+ return (
+ <div className={`ag-turn${folded ? ' folded' : ''}${isLast ? ' current' : ''}`}>
+ <button type="button" className="ag-th" onClick={() => setFolded((f) => !f)}>
+ <span className="ag-hrow">
+ <ChevronRight size={12} strokeWidth={2} className="ag-fold" />
+ <span className="ag-req">{turn.prompt}</span>
+ </span>
+ <span className="ag-stat">
+ {tokens > 0 && <span>↑{compact(turn.inputTokens)} ↓{compact(turn.outputTokens)}</span>}
+ <span className="ag-sp" />
+ {turn.reason === 'aborted' && <span className="ag-warn">{t('agent.turn.aborted')}</span>}
+ {turn.reason === 'refusal' && <span className="ag-warn">{t('agent.turn.refusal')}</span>}
+ {turn.steps > 0 && <span className="ag-add">{t('agent.checkpoint.steps', { count: turn.steps })}</span>}
+ </span>
+ </button>
+ {!folded && (
+ <div className="ag-tb">
+ {empty && running && isLast ? <Skeleton /> : (
+ <Entries entries={turn.entries} onConfirm={confirmAgentCall} />
+ )}
+ </div>
+ )}
+ </div>
+ );
+}
+
+function EmptyState() {
+ const ready = useAgent((s) => s.status.ready);
+ const openSettings = useEditorStore((s) => s.openSettings);
+ if (!ready) {
+ return (
+ <div className="ag-empty">
+ <KeyRound size={30} strokeWidth={1.2} className="ag-empty-mark" />
+ <h4>{t('agent.nokey.title')}</h4>
+ <p>{t('agent.nokey.body')}</p>
+ <button type="button" className="ag-setup" onClick={() => openSettings('agents')}>
+ <KeyRound size={13} strokeWidth={2} />{t('agent.nokey.action')}
+ </button>
+ </div>
+ );
+ }
+ const suggestions = [
+ { Icon: Boxes, text: t('agent.empty.sug1'), hint: t('agent.empty.sug1.h') },
+ { Icon: Stethoscope, text: t('agent.empty.sug2'), hint: t('agent.empty.sug2.h') },
+ { Icon: ImageIcon, text: t('agent.empty.sug3'), hint: t('agent.empty.sug3.h') },
+ ];
+ return (
+ <div className="ag-empty">
+ <h4>{t('agent.empty.title')}</h4>
+ <p>{t('agent.empty.body')}</p>
+ <div className="ag-sugs">
+ {suggestions.map((s) => (
+ <button type="button" className="ag-sug" key={s.text} onClick={() => void sendAgentMessage(s.text)}>
+ <s.Icon size={14} strokeWidth={1.8} />
+ <span>{s.text}<span className="ag-sug-h">{s.hint}</span></span>
+ </button>
+ ))}
+ </div>
+ </div>
+ );
+}
+
+function Compose() {
+ const status = useAgent((s) => s.status);
+ const [draft, setDraft] = useState('');
+ const ref = useRef<HTMLTextAreaElement>(null);
+ const busy = status.phase !== 'idle';
+
+ const autosize = () => {
+ const el = ref.current;
+ if (!el) return;
+ el.style.height = 'auto';
+ el.style.height = `${Math.min(112, el.scrollHeight)}px`;
+ };
+
+ const submit = () => {
+ const text = draft.trim();
+ if (!text) return;
+ setDraft('');
+ requestAnimationFrame(autosize);
+ void sendAgentMessage(text);
+ };
+
+ return (
+ <div className={`ag-compose${busy ? ' busy' : ''}`}>
+ <div className="ag-cbox">
+ <textarea
+ ref={ref}
+ rows={1}
+ value={draft}
+ placeholder={busy ? t('agent.compose.busy') : t('agent.compose')}
+ aria-label={t('agent.compose')}
+ onChange={(e) => { setDraft(e.target.value); autosize(); }}
+ onKeyDown={(e) => {
+ if (e.key === 'Enter' && !e.shiftKey) {
+ e.preventDefault();
+ submit();
+ }
+ }}
+ />
+ <button
+ type="button"
+ className="ag-send"
+ title={busy ? t('agent.stop') : t('agent.send')}
+ aria-label={busy ? t('agent.stop') : t('agent.send')}
+ onClick={() => (busy ? stopAgentTurn() : submit())}
+ >
+ {busy ? <Square size={12} strokeWidth={2.4} /> : <ArrowUp size={14} strokeWidth={2.2} />}
+ </button>
+ </div>
+ <div className="ag-chint">
+ <span><b>⏎</b> {t('agent.hint.send')}</span>
+ <span><b>⇧⏎</b> {t('agent.hint.newline')}</span>
+ <span><b>Esc</b> {t('agent.hint.close')}</span>
+ </div>
+ </div>
+ );
+}
+
+export function AgentDrawer() {
+ const open = useEditorStore((s) => s.agentDrawer);
+ const pinned = useEditorStore((s) => s.agentDrawerPinned);
+ const setOpen = useEditorStore((s) => s.setAgentDrawer);
+ const setPinned = useEditorStore((s) => s.setAgentDrawerPinned);
+ const turns = useAgent((s) => s.turns);
+ const status = useAgent((s) => s.status);
+ const logRef = useRef<HTMLDivElement>(null);
+ const stuck = useRef(true);
+
+ useEffect(() => {
+ if (!open || pinned) return;
+ const onKey = (e: KeyboardEvent) => {
+ if (e.key === 'Escape') setOpen(false);
+ };
+ window.addEventListener('keydown', onKey);
+ return () => window.removeEventListener('keydown', onKey);
+ }, [open, pinned, setOpen]);
+
+ // Follow the tail only while the reader is already at it — yanking someone
+ // back down while they read an earlier tool result is the classic log-view bug.
+ useLayoutEffect(() => {
+ const el = logRef.current;
+ if (el && stuck.current) el.scrollTop = el.scrollHeight;
+ }, [turns]);
+
+ if (!open) return null;
+
+ const body = (
+ <div className="ag-drawer" onMouseDown={(e) => e.stopPropagation()}>
+ <div className="ag-head">
+ <span className="ag-ttl">{t('agent.title')}</span>
+ <span className="ag-sp" />
+ {status.model && <span className="ag-model">{status.model}</span>}
+ <button type="button" title={t('agent.newConversation')} onClick={() => void resetAgentSession()}>
+ <Plus size={14} strokeWidth={2} />
+ </button>
+ <button
+ type="button"
+ className={pinned ? 'on' : undefined}
+ title={t('agent.pin')}
+ onClick={() => setPinned(!pinned)}
+ >
+ <PanelRight size={14} strokeWidth={1.9} />
+ </button>
+ <button type="button" title={t('agent.close')} onClick={() => setOpen(false)}>
+ <X size={14} strokeWidth={2} />
+ </button>
+ </div>
+
+ <div
+ className="ag-log"
+ ref={logRef}
+ role="log"
+ aria-live="polite"
+ onScroll={(e) => {
+ const el = e.currentTarget;
+ stuck.current = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
+ }}
+ >
+ {turns.length === 0
+ ? <EmptyState />
+ : turns.map((turn, i) => (
+ <Turn key={turn.id} turn={turn} isLast={i === turns.length - 1} running={status.phase !== 'idle'} />
+ ))}
+ </div>
+
+ {status.error && <div className="ag-banner">{status.error}</div>}
+ <Compose />
+ </div>
+ );
+
+ // Pinned it is a fourth column; floating it dims what is behind, because then
+ // it is the thing you are doing.
+ if (pinned) return <div className="ag-column">{body}</div>;
+ return (
+ <div className="ag-scrim open" onMouseDown={() => setOpen(false)}>
+ {body}
+ </div>
+ );
+}
+
+const compact = (n: number): string => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+
+/** One line of the call's arguments — enough to tell two calls apart. */
+function summarizeInput(input: Record<string, unknown>): string {
+ const parts: string[] = [];
+ for (const [key, value] of Object.entries(input)) {
+ if (value === null || value === undefined) continue;
+ const text = typeof value === 'object' ? Array.isArray(value) ? `${value.length}` : '…' : String(value);
+ parts.push(text.length > 28 ? `${key}=${text.slice(0, 27)}…` : `${key}=${text}`);
+ if (parts.length === 3) break;
+ }
+ return parts.join(' ');
+}
+
+/** What an irreversible call is about to touch, in full. See ConfirmPassage. */
+function describeTarget(input: Record<string, unknown>): string {
+ for (const key of ['path', 'file', 'dest', 'code', 'command']) {
+ const value = input[key];
+ if (typeof value === 'string' && value) return value;
+ }
+ return Object.entries(input)
+ .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
+ .join('\n');
+}
diff --git a/desktop/src/components/CommandPalette.tsx b/desktop/src/components/CommandPalette.tsx
index 6f5c2a50d..11329241a 100644
--- a/desktop/src/components/CommandPalette.tsx
+++ b/desktop/src/components/CommandPalette.tsx
@@ -9,11 +9,14 @@
*/
import { useEffect, useMemo, useRef, useState } from 'react';
import { createPortal } from 'react-dom';
+import { Sparkles } from 'lucide-react';
import { SearchField } from '@/components/SearchField';
import { useDialogFocus } from '@/components/dialogFocus';
import { usePanelWindow } from '@/components/PanelWindow';
import { commands, formatKeybinding } from '@/commands';
-import { filterPalette, paletteItems, type PaletteItem } from '@/commands/palette';
+import { filterPalette, paletteItems, readsAsSentence, type PaletteItem } from '@/commands/palette';
+import { useEditorStore } from '@/store/editorStore';
+import { sendAgentMessage } from '@/store/AgentStore';
import { t } from '@/i18n';
export function CommandPalette({ onClose }: { onClose: () => void }) {
@@ -50,9 +53,18 @@ export function CommandPalette({ onClose }: { onClose: () => void }) {
const filtered = useMemo(() => filterPalette(items, query), [items, query]);
+ // "Type a command, get a command; type a sentence, the first row becomes Hand
+ // to Agent." The row is OFFERED whenever the text reads as something said —
+ // but it is only SELECTED when no command matches, so `save scene` still
+ // saves the scene rather than being narrated at a model.
+ const offerAgent = readsAsSentence(query);
+ // Index -1 IS the agent row: reachable with ↑ whenever it is offered, and the
+ // default only when there is no command to prefer over it.
+ const agentFirst = offerAgent && filtered.length === 0;
+
useEffect(() => {
- setActive(0);
- }, [query]);
+ setActive(agentFirst ? -1 : 0);
+ }, [query, agentFirst]);
useEffect(() => {
activeRef.current?.scrollIntoView({ block: 'nearest' });
}, [active]);
@@ -63,6 +75,14 @@ export function CommandPalette({ onClose }: { onClose: () => void }) {
commands.run(item.id);
};
+ const handOff = () => {
+ onClose();
+ useEditorStore.getState().setAgentDrawer(true);
+ void sendAgentMessage(query.trim());
+ };
+
+ // The agent row sits at index -1 when it is the default, so ↓ walks from it
+ // into the commands and ↑ comes back.
const onKeyDown = (e: React.KeyboardEvent) => {
if (e.key === 'Escape') {
e.preventDefault();
@@ -72,11 +92,16 @@ export function CommandPalette({ onClose }: { onClose: () => void }) {
setActive((a) => Math.min(filtered.length - 1, a + 1));
} else if (e.key === 'ArrowUp') {
e.preventDefault();
- setActive((a) => Math.max(0, a - 1));
+ setActive((a) => Math.max(offerAgent ? -1 : 0, a - 1));
} else if (e.key === 'Enter') {
e.preventDefault();
+ if (offerAgent && active < 0) {
+ handOff();
+ return;
+ }
const item = filtered[active];
if (item) run(item);
+ else if (offerAgent) handOff();
}
};
@@ -105,7 +130,27 @@ export function CommandPalette({ onClose }: { onClose: () => void }) {
</SearchField>
<div className="ac-body">
- {filtered.length === 0 ? (
+ {offerAgent && (
+ <>
+ <button
+ type="button"
+ className={`ac-item cp-item cp-agent${active < 0 ? ' sel' : ''}`}
+ onMouseEnter={() => setActive(-1)}
+ onClick={handOff}
+ >
+ <span className="at">
+ <div className="an">
+ <Sparkles size={13} strokeWidth={1.8} />
+ {t('agent.handOff')}
+ <span className="cp-cat"> · {t('agent.handOff.sub')}</span>
+ </div>
+ </span>
+ <span className="cp-kb">Enter</span>
+ </button>
+ {filtered.length > 0 && <div className="cp-sep" />}
+ </>
+ )}
+ {filtered.length === 0 && !offerAgent ? (
<div className="empty-line">{t('palette.noMatch')}</div>
) : (
filtered.map((item, idx) => {
diff --git a/desktop/src/i18n/messages/agent.ts b/desktop/src/i18n/messages/agent.ts
new file mode 100644
index 000000000..1570f1c69
--- /dev/null
+++ b/desktop/src/i18n/messages/agent.ts
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file agent.ts — the built-in agent's surface: the drawer, the transcript,
+ * the decisions it asks you to make, and the checkpoint bar.
+ */
+import { defineMessages } from './types';
+
+export const agentMessages = defineMessages({
+ 'agent.title': { en: 'Agent', zh: 'Agent' },
+ 'agent.open': { en: 'Agent: Open', zh: 'Agent:打开' },
+ 'agent.handOff': { en: 'Hand to Agent', zh: '交给 Agent' },
+ 'agent.handOff.sub': {
+ en: 'reads the scene, may change it',
+ zh: '会读场景、可能改动',
+ },
+
+ // — Drawer chrome —
+ 'agent.newConversation': { en: 'New conversation', zh: '新对话' },
+ 'agent.pin': { en: 'Pin as a column', zh: '固定成常驻列' },
+ 'agent.close': { en: 'Close (Esc)', zh: '关闭 (Esc)' },
+ 'agent.compose': { en: 'Say something…', zh: '说点什么…' },
+ 'agent.compose.busy': { en: 'It is working — this will be the next message…', zh: '正在干活,这条会排到下一轮…' },
+ 'agent.send': { en: 'Send', zh: '发送' },
+ 'agent.stop': { en: 'Stop', zh: '停止' },
+ 'agent.hint.send': { en: 'send', zh: '发送' },
+ 'agent.hint.newline': { en: 'new line', zh: '换行' },
+ 'agent.hint.close': { en: 'close', zh: '关闭' },
+
+ // — Empty states —
+ 'agent.empty.title': { en: 'Ask the agent to do something', zh: '让 Agent 帮你做点什么' },
+ 'agent.empty.body': {
+ en: 'It can read the scene, change entities, and look at what it rendered. Its edits are bracketed by a checkpoint, so one Undo takes the whole turn back.',
+ zh: '它能读场景、改实体、看渲染结果。改动会记一个检查点,一次撤销全退。',
+ },
+ 'agent.empty.sug1': { en: 'Add a pause menu for the player', zh: '给玩家加一个暂停菜单' },
+ 'agent.empty.sug1.h': { en: 'creates UI entities', zh: '会新建 UI 实体' },
+ 'agent.empty.sug2': { en: 'Why is nothing showing in this scene?', zh: '这个场景为什么不显示?' },
+ 'agent.empty.sug2.h': { en: 'read-only, changes nothing', zh: '只读,不会改东西' },
+ 'agent.empty.sug3': { en: 'Give every button a nine-slice texture', zh: '把所有按钮换成九宫格贴图' },
+ 'agent.empty.sug3.h': { en: 'edits fields in bulk', zh: '会批量改字段' },
+ 'agent.nokey.title': { en: 'No model configured yet', zh: '还没有配置模型' },
+ 'agent.nokey.body': {
+ en: 'The key lives in the system keychain — not in the project, not in the settings file, and never handed to this window.',
+ zh: '密钥存在系统钥匙串里,不进项目、不进设置文件,也不会交给这个窗口。',
+ },
+ 'agent.nokey.action': { en: 'Configure it in Settings', zh: '去设置里配置' },
+
+ // — Transcript —
+ 'agent.waiting': { en: 'Waiting for the model', zh: '等待模型响应' },
+ 'agent.thinking': { en: 'Thinking', zh: '正在思考' },
+ 'agent.queued': { en: 'queued', zh: '排队中' },
+ 'agent.stopped': { en: 'stopped', zh: '已中止' },
+ 'agent.declined': { en: 'skipped', zh: '已跳过' },
+ 'agent.turn.aborted': { en: 'Stopped part-way.', zh: '中途停止。' },
+ 'agent.turn.refusal': { en: 'The model declined this one.', zh: '模型拒绝了这个请求。' },
+ 'agent.turn.queuedMessage': { en: 'Queued: {text}', zh: '已排队:{text}' },
+ 'agent.copy': { en: 'Copy', zh: '复制' },
+
+ // — The decision it needs from you —
+ 'agent.confirm.title': { en: 'Run {tool}?', zh: '要执行 {tool} 吗?' },
+ 'agent.confirm.why.irreversible': {
+ en: 'It writes outside the scene, and Undo cannot take it back.',
+ zh: '它会写到场景之外,撤销收不回来。',
+ },
+ 'agent.confirm.why.arbitrary_code': {
+ en: 'It runs code the agent wrote, so its effect is whatever that code does.',
+ zh: '它会执行 Agent 自己写的代码,效果取决于那段代码。',
+ },
+ 'agent.confirm.allow': { en: 'Run it', zh: '执行' },
+ 'agent.confirm.deny': { en: 'Skip', zh: '跳过' },
+ 'agent.confirm.denied': {
+ en: 'Skipped — the agent was told to work around it.',
+ zh: '已跳过 —— 已告诉 Agent 绕开它继续。',
+ },
+ 'agent.jump': { en: 'One waiting on you', zh: '有一条待确认' },
+
+ // — The checkpoint a finished turn leaves behind —
+ 'agent.checkpoint.undo': { en: 'Undo', zh: '撤销' },
+ 'agent.checkpoint.keep': { en: 'Keep', zh: '保留' },
+ 'agent.checkpoint.steps': { en: '{count} steps', zh: '{count} 步' },
+ 'agent.checkpoint.undone': { en: 'Took back this turn · {count} steps', zh: '已撤销这一轮 · {count} 步' },
+ 'agent.checkpoint.stale': {
+ en: 'You have edited since — Undo would take those back too.',
+ zh: '之后你自己编辑过 —— 撤销会连那些一起退回。',
+ },
+
+ // — The status-bar segment —
+ 'agent.status.running': { en: 'Agent is working', zh: 'Agent 正在干活' },
+ 'agent.status.awaiting': { en: 'Agent is waiting on you', zh: 'Agent 在等你确认' },
+});
diff --git a/desktop/src/i18n/messages/index.ts b/desktop/src/i18n/messages/index.ts
index 1f1fbabed..2e0696980 100644
--- a/desktop/src/i18n/messages/index.ts
+++ b/desktop/src/i18n/messages/index.ts
@@ -38,6 +38,7 @@ import { materialMessages } from './material';
import { projectMessages } from './project';
import { controllerMessages } from './controllers';
import { animatorMessages } from './animator';
+import { agentMessages } from './agent';
import { eventMessages } from './events';
import { pluginMessages } from './plugins';
@@ -65,6 +66,7 @@ export const messageModules = {
animator: animatorMessages,
events: eventMessages,
plugins: pluginMessages,
+ agent: agentMessages,
} as const;
export const editorMessages = {
@@ -90,4 +92,5 @@ export const editorMessages = {
...animatorMessages,
...eventMessages,
...pluginMessages,
+ ...agentMessages,
} as const;
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 42ad575f7..e444b3fe7 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -36,6 +36,7 @@ import './theme/nodegraph.css';
import './theme/chrome.css';
import './theme/menus.css';
import './theme/settings.css';
+import './theme/agent.css';
import './theme/launcher.css';
import './theme/plugins.css';
import { App } from './App';
diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.ts
index 208a21f98..4f7b62e37 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, ConfirmRequest } from '../../electron/agent/types';
+import type { AgentEvent, ConfirmReason, ConfirmRequest } from '../../electron/agent/types';
export type { AgentStatus, AgentEvent };
@@ -45,7 +45,7 @@ export interface AgentToolEntry {
/** The result, shortened for one row. */
summary: string | null;
/** Why it needs saying out loud, while it is awaiting an answer. */
- reason: string | null;
+ reason: ConfirmReason | null;
}
export interface AgentProseEntry {
@@ -290,4 +290,4 @@ export async function resetAgentSession(): Promise<void> {
export const agentDriving = (): boolean => useAgent.getState().driving;
export const subscribeAgent = (fn: () => void): (() => void) => useAgent.subscribe(fn);
-export type { ConfirmRequest };
+export type { ConfirmRequest, ConfirmReason };
diff --git a/desktop/src/store/editorStore.ts b/desktop/src/store/editorStore.ts
index 9a17e6e02..55c29bb3d 100644
--- a/desktop/src/store/editorStore.ts
+++ b/desktop/src/store/editorStore.ts
@@ -114,6 +114,16 @@ interface EditorState {
paletteOpen: boolean;
setPaletteOpen: (open: boolean) => void;
+ // The built-in agent's conversation. Slides in over the right-hand panels
+ // rather than squeezing the viewport: you look at properties or you talk to
+ // the agent, and pinning turns the overlay into a fourth column for the times
+ // you want both. The conversation itself lives in AgentStore.
+ agentDrawer: boolean;
+ toggleAgentDrawer: () => void;
+ setAgentDrawer: (open: boolean) => void;
+ agentDrawerPinned: boolean;
+ setAgentDrawerPinned: (pinned: boolean) => void;
+
// "New Tilemap" tileset chooser (Entity → New Tilemap): picks the .estileset
// palette for a fresh map, then createTilemapFromTileset does the rest.
tilemapPickerOpen: boolean;
@@ -219,6 +229,12 @@ export const useEditorStore = create<EditorState>((set) => ({
paletteOpen: false,
setPaletteOpen: (paletteOpen) => set({ paletteOpen }),
+ agentDrawer: false,
+ toggleAgentDrawer: () => set((s) => ({ agentDrawer: !s.agentDrawer })),
+ setAgentDrawer: (agentDrawer) => set({ agentDrawer }),
+ agentDrawerPinned: false,
+ setAgentDrawerPinned: (agentDrawerPinned) => set({ agentDrawerPinned }),
+
tilemapPickerOpen: false,
setTilemapPickerOpen: (tilemapPickerOpen) => set({ tilemapPickerOpen }),
}));
diff --git a/desktop/src/theme/agent.css b/desktop/src/theme/agent.css
new file mode 100644
index 000000000..e0cb59eeb
--- /dev/null
+++ b/desktop/src/theme/agent.css
@@ -0,0 +1,357 @@
+/* SPDX-License-Identifier: Apache-2.0
+ * SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+ *
+ * The built-in agent's drawer. Near-monochrome and completely flat: hierarchy
+ * comes from size, weight and tracking, never from a box. Colour is reserved
+ * for meaning — green added, red failed, amber needs a decision — so nothing is
+ * tinted merely for belonging to the agent.
+ *
+ * Hairlines DIVIDE; they never ENCLOSE. A rule between two rows is structure; a
+ * rule around a thing is a box. That is why tool rows are separated by lines but
+ * have no border of their own, and why a confirmation is a rule above and below
+ * plus a coloured leading edge rather than a card dropped onto the transcript.
+ */
+
+/* Floating: it covers the right-hand panels rather than squeezing the viewport.
+ You look at properties or you talk to the agent — the two naturally alternate,
+ and a viewport that resizes under a conversation is the worse trade. */
+.ag-scrim {
+ /* Absolute, not fixed: bounded to the workspace row, so the menubar, toolbar
+ and status bar stay live. The status bar in particular is where the agent
+ reports progress — dimming it would hide the thing that says work is
+ happening. */
+ position: absolute;
+ inset: 0;
+ z-index: 60;
+ background: rgba(0, 0, 0, 0.42);
+ display: flex;
+ justify-content: flex-end;
+}
+/* Pinned: an ordinary flex child of the workspace row — a real fourth column,
+ no scrim, nothing dimmed, for when you do want both at once. */
+.ag-column { display: contents; }
+
+.ag-drawer {
+ width: 384px;
+ max-width: 100vw;
+ flex: none;
+ display: flex;
+ flex-direction: column;
+ min-height: 0;
+ height: 100%;
+ background: var(--panel);
+ border-left: 1px solid var(--line-strong);
+}
+
+.ag-head {
+ height: 40px;
+ flex: none;
+ display: flex;
+ align-items: center;
+ gap: 2px;
+ padding: 0 6px 0 13px;
+ border-bottom: 1px solid var(--line);
+}
+.ag-ttl { font-size: var(--fs-md); font-weight: 500; color: var(--text-hi); letter-spacing: -0.008em; }
+.ag-sp { flex: 1; }
+.ag-model {
+ font: var(--fs-2xs) var(--font-mono);
+ color: var(--text-faint);
+ padding: 3px 8px;
+ border-radius: var(--r-sm);
+ white-space: nowrap;
+ max-width: 150px;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+.ag-head button {
+ width: 26px; height: 26px;
+ display: grid; place-items: center;
+ border-radius: var(--r-sm);
+ color: var(--text-faint);
+ transition: color var(--t-fast), background var(--t-fast);
+}
+.ag-head button:hover { color: var(--text-hi); background: var(--hover); }
+.ag-head button.on { color: var(--text-hi); background: var(--pressed); }
+
+.ag-log { flex: 1; overflow-y: auto; overflow-x: hidden; min-height: 0; padding-bottom: 12px; }
+
+/* ── A run ─────────────────────────────────────────────────────────────────
+ The unit of work, so it gets a header: what was asked plus the numbers that
+ get checked afterwards. Only the CURRENT run sticks — every past header
+ sticking would stack into a pile as soon as there are three of them. */
+.ag-turn { border-bottom: 1px solid var(--line); }
+.ag-th {
+ display: block;
+ width: 100%;
+ text-align: left;
+ padding: 13px 14px 11px;
+ background: var(--panel);
+ transition: background var(--t-fast);
+}
+.ag-turn.current > .ag-th { position: sticky; top: 0; z-index: 3; }
+.ag-th:hover { background: var(--elevated); }
+.ag-hrow { display: flex; align-items: flex-start; gap: 9px; }
+.ag-fold { color: var(--text-faint); margin-top: 3px; flex: none; transition: transform 0.18s var(--ease, ease); }
+.ag-turn:not(.folded) .ag-fold { transform: rotate(90deg); }
+.ag-req {
+ flex: 1; min-width: 0;
+ font-size: var(--fs-lg);
+ line-height: 1.45;
+ font-weight: 500;
+ color: var(--text-hi);
+ letter-spacing: -0.01em;
+ overflow-wrap: anywhere;
+}
+.ag-stat {
+ display: flex; align-items: center; gap: 12px; flex-wrap: wrap;
+ margin: 8px 0 0 21px;
+ font: var(--fs-xs) var(--font-mono);
+ color: var(--text-faint);
+}
+.ag-stat .ag-sp { flex: 1; }
+.ag-add { color: var(--run); }
+.ag-warn { color: var(--warn); }
+
+.ag-tb { padding: 12px 14px 16px; display: flex; flex-direction: column; gap: 12px; border-top: 1px solid var(--line); }
+/* A flex column shrinks its children by default, so one expanded tool detail
+ would squash every row above it. */
+.ag-tb > * { flex: 0 0 auto; }
+
+/* ── Prose ───────────────────────────────────────────────────────────────── */
+.ag-say {
+ position: relative;
+ font-size: var(--fs-md);
+ line-height: 1.7;
+ color: var(--text);
+ white-space: pre-wrap;
+ overflow-wrap: anywhere;
+}
+.ag-say-copy {
+ position: absolute; top: -10px; right: 0;
+ width: 22px; height: 22px;
+ display: grid; place-items: center;
+ border-radius: var(--r-sm);
+ background: var(--raised);
+ border: 1px solid var(--line);
+ color: var(--text-faint);
+ opacity: 0;
+ transition: opacity var(--t-fast), color var(--t-fast);
+}
+.ag-say:hover .ag-say-copy, .ag-say-copy:focus-visible { opacity: 1; }
+.ag-say-copy:hover { color: var(--text-hi); }
+
+.ag-think { padding-left: 12px; border-left: 1px solid var(--line); }
+.ag-think-t {
+ display: flex; align-items: center; gap: 6px;
+ font-size: var(--fs-sm);
+ color: var(--text-faint);
+ transition: color var(--t-fast);
+}
+.ag-think-t:hover { color: var(--text-dim); }
+.ag-car { transition: transform 0.18s var(--ease, ease); }
+.ag-think.open .ag-car { transform: rotate(90deg); }
+.ag-think-body {
+ padding-top: 7px;
+ font-size: var(--fs-sm);
+ line-height: 1.8;
+ color: var(--text-dim);
+ white-space: pre-wrap;
+}
+
+/* ── Tool steps: rows divided by hairlines, never enclosed by one. ───────── */
+.ag-steps { display: flex; flex-direction: column; }
+.ag-call + .ag-call, .ag-ask + .ag-call { border-top: 1px solid var(--line); }
+.ag-call-top {
+ display: grid;
+ grid-template-columns: 15px auto minmax(0, 1fr) auto;
+ gap: 10px;
+ align-items: center;
+ width: 100%;
+ text-align: left;
+ padding: 7px 2px;
+ transition: background var(--t-fast);
+}
+.ag-call-top:hover { background: var(--hover); }
+.ag-call-g { display: grid; place-items: center; color: var(--text-faint); }
+.ag-call-nm { font: 500 var(--fs-xs) / 1 var(--font-mono); color: var(--text); white-space: nowrap; letter-spacing: -0.015em; }
+.ag-call-arg {
+ min-width: 0;
+ font: var(--fs-xs) / 1 var(--font-mono);
+ color: var(--text-faint);
+ overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.ag-call-out {
+ font: var(--fs-xs) var(--font-mono);
+ color: var(--text-faint);
+ white-space: nowrap;
+ display: flex; align-items: center; gap: 5px;
+ max-width: 130px;
+ overflow: hidden; text-overflow: ellipsis;
+}
+.ag-spin { animation: ag-spin 0.9s linear infinite; }
+@keyframes ag-spin { to { transform: rotate(360deg); } }
+/* Asked for but not started: greyed, not a third spinner. */
+.ag-call--queued { opacity: 0.45; }
+.ag-call--stopped, .ag-call--declined { opacity: 0.5; }
+.ag-call--running .ag-call-nm { color: var(--text-hi); }
+.ag-call--ok .ag-call-g { color: var(--run); }
+.ag-call--error .ag-call-g, .ag-call--error .ag-call-out { color: var(--error); }
+.ag-call--awaiting .ag-call-g, .ag-call--awaiting .ag-call-out { color: var(--warn); }
+.ag-call-detail {
+ margin: 2px 0 9px 25px;
+ padding: 10px 12px;
+ border-radius: var(--r-sm);
+ background: var(--inset);
+ font: var(--fs-xs) / 1.75 var(--font-mono);
+ color: var(--text-dim);
+ white-space: pre-wrap;
+ overflow: auto;
+ max-height: 220px;
+ overscroll-behavior: contain;
+ user-select: text;
+}
+
+/* ── A decision, as a passage rather than a dialog ───────────────────────── */
+.ag-ask {
+ display: grid;
+ grid-template-columns: 16px minmax(0, 1fr);
+ gap: 10px;
+ padding: 13px 0 13px 12px;
+ margin: 2px 0;
+ border-top: 1px solid var(--line);
+ border-bottom: 1px solid var(--line);
+ border-left: 2px solid var(--ag-tone);
+}
+.ag-ask--confirm { --ag-tone: var(--warn); }
+.ag-ask--fail { --ag-tone: var(--error); }
+.ag-ask-g { color: var(--ag-tone); margin-top: 1px; }
+.ag-ask-hd { font-size: var(--fs-md); font-weight: 500; color: var(--text-hi); letter-spacing: -0.01em; line-height: 1.4; }
+.ag-ask-d { grid-column: 2; font-size: var(--fs-sm); color: var(--text-dim); margin-top: 5px; line-height: 1.65; }
+/* Wraps rather than scrolls or truncates: this is the whole basis on which
+ someone says yes, and a hidden filename is the one thing to never ship. */
+.ag-ask-tgt {
+ grid-column: 2;
+ margin-top: 8px;
+ padding: 8px 10px;
+ border-radius: var(--r-sm);
+ background: var(--inset);
+ font: var(--fs-xs) / 1.6 var(--font-mono);
+ color: var(--text);
+ white-space: pre-wrap;
+ overflow-wrap: anywhere;
+ word-break: break-word;
+}
+.ag-ask-acts { grid-column: 2; display: flex; flex-wrap: wrap; gap: 7px; margin-top: 12px; }
+.ag-ask-acts button {
+ padding: 6px 14px;
+ border-radius: var(--r-sm);
+ font-size: var(--fs-sm);
+ color: var(--text);
+ background: var(--hover);
+ transition: background var(--t-fast);
+}
+.ag-ask-acts button:hover { background: var(--pressed); }
+.ag-ask-acts .ag-go { background: var(--text-hi); color: var(--srf-0); font-weight: 500; }
+.ag-ask-acts .ag-go:hover { background: #fff; }
+
+/* ── Waiting on the first token ──────────────────────────────────────────── */
+.ag-wait { display: flex; flex-direction: column; gap: 8px; }
+.ag-wait-t { display: flex; align-items: center; gap: 8px; font-size: var(--fs-sm); color: var(--text-faint); }
+.ag-dots { display: inline-flex; gap: 3px; align-items: center; }
+.ag-dots i { width: 3px; height: 3px; border-radius: 50%; background: currentColor; animation: ag-hop 1.2s ease infinite; }
+.ag-dots i:nth-child(2) { animation-delay: 0.15s; }
+.ag-dots i:nth-child(3) { animation-delay: 0.3s; }
+@keyframes ag-hop { 0%, 60%, 100% { opacity: 0.25; } 30% { opacity: 1; } }
+.ag-skel {
+ height: 10px;
+ border-radius: 3px;
+ background: linear-gradient(90deg, var(--hover) 24%, var(--pressed) 46%, var(--hover) 68%);
+ background-size: 220% 100%;
+ animation: ag-shimmer 1.6s linear infinite;
+}
+.ag-skel.s2 { width: 84%; }
+.ag-skel.s3 { width: 56%; }
+@keyframes ag-shimmer { from { background-position: 120% 0; } to { background-position: -120% 0; } }
+
+/* ── Empty states ────────────────────────────────────────────────────────── */
+.ag-empty { padding: 40px 14px; text-align: center; display: flex; flex-direction: column; align-items: center; }
+.ag-empty-mark { color: var(--text-faint); opacity: 0.5; }
+.ag-empty h4 { margin: 14px 0 6px; font-size: var(--fs-lg); color: var(--text-hi); font-weight: 600; letter-spacing: -0.016em; }
+.ag-empty p { margin: 0 0 18px; font-size: var(--fs-sm); color: var(--text-dim); line-height: 1.7; }
+.ag-sugs { display: flex; flex-direction: column; align-self: stretch; text-align: left; border-top: 1px solid var(--line); }
+.ag-sug {
+ display: grid;
+ grid-template-columns: 15px 1fr;
+ gap: 10px;
+ align-items: start;
+ padding: 11px 4px;
+ font-size: var(--fs-sm);
+ color: var(--text);
+ border-bottom: 1px solid var(--line);
+ transition: background var(--t-fast);
+}
+.ag-sug svg { color: var(--text-faint); margin-top: 2px; }
+.ag-sug:hover { background: var(--hover); }
+.ag-sug:hover svg { color: var(--text); }
+.ag-sug-h { display: block; font-size: var(--fs-2xs); color: var(--text-faint); margin-top: 3px; }
+.ag-setup {
+ display: flex; align-items: center; gap: 7px;
+ padding: 8px 16px;
+ border-radius: var(--r-sm);
+ background: var(--text-hi);
+ color: var(--srf-0);
+ font-weight: 500;
+ font-size: var(--fs-sm);
+}
+
+/* Refusals and endpoint failures — what main could not do, above the box you
+ would otherwise retype into. */
+.ag-banner {
+ flex: none;
+ padding: 9px 14px;
+ border-top: 1px solid var(--line);
+ border-left: 2px solid var(--error);
+ font-size: var(--fs-sm);
+ color: var(--text-dim);
+}
+
+/* ── Compose ─────────────────────────────────────────────────────────────── */
+.ag-compose { flex: none; padding: 11px 13px 12px; border-top: 1px solid var(--line); }
+.ag-cbox {
+ display: flex; align-items: flex-end; gap: 7px;
+ padding: 6px 6px 6px 11px;
+ border-radius: var(--r-md, 6px);
+ background: var(--inset);
+ border: 1px solid var(--line);
+ transition: border-color var(--t-fast);
+}
+.ag-cbox:focus-within { border-color: var(--line-strong); }
+.ag-cbox textarea {
+ flex: 1; min-width: 0;
+ background: none; border: 0; outline: 0;
+ color: var(--text);
+ font: var(--fs-md) / 1.55 var(--font-ui);
+ padding: 4px 0;
+ resize: none;
+ max-height: 112px;
+ overflow-y: auto;
+}
+.ag-cbox textarea::placeholder { color: var(--text-faint); }
+.ag-send {
+ width: 27px; height: 27px;
+ flex: none;
+ display: grid; place-items: center;
+ border-radius: var(--r-sm);
+ background: var(--text-hi);
+ color: var(--srf-0);
+ transition: background var(--t-fast);
+}
+.ag-send:hover { background: #fff; }
+.ag-compose.busy .ag-send { background: var(--pressed); color: var(--text-hi); }
+.ag-chint { display: flex; gap: 13px; padding: 8px 2px 0; font-size: var(--fs-2xs); color: var(--text-faint); }
+.ag-chint b { color: var(--text-dim); font-weight: 500; }
+
+@media (prefers-reduced-motion: reduce) {
+ .ag-spin, .ag-skel, .ag-dots i { animation: none; }
+}
diff --git a/desktop/src/theme/menus.css b/desktop/src/theme/menus.css
index 5364e80ff..5d221d001 100644
--- a/desktop/src/theme/menus.css
+++ b/desktop/src/theme/menus.css
@@ -390,3 +390,10 @@
/* "compression lives in Import Settings" pointer + footer scene/target summary. */
.build__hint { display: inline-flex; align-items: center; gap: 5px; font-size: var(--fs-2xs); color: var(--text-mute); }
.build__footsum { margin-right: auto; align-self: center; font-family: var(--mono); font-size: var(--fs-2xs); color: var(--text-mute); }
+
+/* The palette's agent branch: a separator between "hand this sentence over" and
+ the commands, so the two readings of the same text stay visibly distinct. */
+.cp-sep { height: 1px; margin: 5px 8px; background: var(--line); }
+.cp-agent .an { display: flex; align-items: center; gap: 8px; }
+.cp-agent .an svg { color: var(--text-faint); flex: none; }
+.cp-agent.sel .an svg { color: var(--star-hi); }
diff --git a/desktop/tests/agent-palette.test.ts b/desktop/tests/agent-palette.test.ts
new file mode 100644
index 000000000..c1d84ff6b
--- /dev/null
+++ b/desktop/tests/agent-palette.test.ts
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The palette's one branch: type a command, get a command; type a
+ * sentence, the first row becomes "hand it to the agent".
+ *
+ * Worth pinning because the failure is silent in one direction. Too
+ * eager, and `save scene` gets narrated at a model instead of saving the
+ * scene — which is why the offer and the DEFAULT are separate decisions,
+ * and only the second one is strict.
+ */
+import { describe, it, expect } from 'vitest';
+import { readsAsSentence, filterPalette } from '@/commands/palette';
+
+describe('when a query reads as a sentence', () => {
+ it('takes a space as the signal, since command names have none', () => {
+ expect(readsAsSentence('add a pause menu for the player')).toBe(true);
+ expect(readsAsSentence('why is nothing showing')).toBe(true);
+ });
+
+ // CJK needs no spaces to be a sentence, so the space test alone would never
+ // offer the agent to a Chinese user.
+ it('takes CJK as the same signal', () => {
+ expect(readsAsSentence('给玩家加一个暂停菜单')).toBe(true);
+ expect(readsAsSentence('这个场景为什么不显示')).toBe(true);
+ });
+
+ it('leaves single command-shaped words alone', () => {
+ expect(readsAsSentence('settings')).toBe(false);
+ expect(readsAsSentence('undo')).toBe(false);
+ expect(readsAsSentence('')).toBe(false);
+ });
+
+ // A half-typed word is not a request.
+ it('ignores anything too short to be one', () => {
+ expect(readsAsSentence('ui ')).toBe(false);
+ expect(readsAsSentence('a b')).toBe(false);
+ expect(readsAsSentence('新建')).toBe(false);
+ });
+});
+
+// The offer is generous; the DEFAULT is where the command has to win, and that
+// is decided by whether anything matched — so pin the pairing, not just the flag.
+describe('what Enter does', () => {
+ const COMMANDS = [
+ { label: 'Save Scene', category: 'File' },
+ { label: 'Toggle Grid', category: 'View' },
+ ];
+ const wouldHandOff = (query: string) =>
+ readsAsSentence(query) && filterPalette(COMMANDS, query).length === 0;
+
+ it('runs the command when the sentence is also a command', () => {
+ expect(readsAsSentence('save scene')).toBe(true); // still offered…
+ expect(wouldHandOff('save scene')).toBe(false); // …but Enter saves the scene
+ });
+
+ it('hands over when nothing in the registry matches', () => {
+ expect(wouldHandOff('给玩家加一个暂停菜单')).toBe(true);
+ expect(wouldHandOff('add a pause menu for the player')).toBe(true);
+ });
+});