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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(editor): the agent's conversation has a budget, so a long one stops failing
esengine90b4a35fc0c8
diff --git a/desktop/electron/agent/anthropic.ts b/desktop/electron/agent/anthropic.tsindex 929ddcec5..b1d06290e 100644--- a/desktop/electron/agent/anthropic.ts+++ b/desktop/electron/agent/anthropic.ts@@ -22,7 +22,7 @@*/import Anthropic from '@anthropic-ai/sdk';import type { AgentProvider, AgentSession, CatalogTool, StepEvent, ToolOutcome } from './types';-import { DEFAULT_MODEL } from '../../src/settings/agentIds';+import { DEFAULT_MODEL, DEFAULT_CONTEXT_WINDOW, COMPACT_AT, KEEP_WHOLE_RUNS } from '../../src/settings/agentIds';/** Agentic work is what `xhigh` is for; it is also the depth Claude Code runs at. */export const DEFAULT_EFFORT = 'xhigh';@@ -42,6 +42,9 @@ export interface AnthropicOptions {/** Point at an Anthropic-compatible gateway; omit for the API. Its presence* is what drops the request to the core wire format — see the file header. */baseURL?: string;+ /** How far the conversation may grow before the oldest runs are folded away.+ * The window knows which provider this is, so it is the side that says. */+ contextWindow?: number;}type Message = Anthropic.Beta.BetaMessageParam;@@ -188,6 +191,68 @@ export function describeApiError(error: unknown): string {return raw;}+/**+ * Fold the oldest runs into one note, keeping what the PERSON said.+ *+ * A conversation grows mostly by tool traffic — a scene tree, a diagnostics+ * list, the reasoning about them — and almost none of that is worth carrying+ * once the edits have landed. The intent is: "make it feel like dusk" governs+ * the ninth run as much as the first. So the person's own words survive verbatim+ * and everything around them becomes a line.+ *+ * Structural rather than model-written: asking a model to summarise costs a call+ * and a wait at exactly the moment the conversation is already long, and the+ * facts worth keeping (what was asked) are ones already held exactly.+ *+ * Pure and exported for the reason buildStepRequest is: it rewrites the history+ * everything else depends on, and the bookkeeping — turn COORDINATES outliving+ * the messages they named — is the part worth pinning by test rather than by+ * whichever long conversation happens to hit it first.+ *+ * @returns the rewritten history, or null when there is not enough to fold.+ */+export function compactHistory(+ messages: readonly Message[],+ turnStarts: readonly number[],+ dropped: number,+ keepRuns: number,+): { messages: Message[]; turnStarts: number[]; dropped: number } | null {+ const cut = turnStarts.length - keepRuns;+ if (cut <= 0) return null;+ const at = turnStarts[cut];+ const asked = turnStarts.slice(0, cut)+ .map((start, i) => `${dropped + i + 1}. ${firstText(messages[start])}`);+ const note = 'Earlier in this conversation you were asked, in order:\n'+ + `${asked.join('\n')}\n`+ + 'The tool calls and results from those runs were dropped to keep this conversation '+ + 'inside its context window. Whatever they changed is in the scene — read it back if '+ + 'you need the current state rather than trusting this summary.';+ const kept: Message[] = [+ { role: 'user', content: note },+ { role: 'assistant', content: 'Understood.' },+ ...messages.slice(at),+ ];+ const shift = at - 2;+ return {+ messages: kept,+ turnStarts: turnStarts.slice(cut).map((s) => s - shift),+ // Coordinates count from the start of the CONVERSATION, not of what is left.+ dropped: dropped + cut,+ };+}++/** What a person's turn said, as one line for the compaction note. They are+ * pushed as plain strings; the block form is handled for completeness. */+function firstText(message: Message | undefined): string {+ const content = message?.content;+ const text = typeof content === 'string'+ ? content+ : content?.flatMap((b) => (b.type === 'text' ? [b.text] : [])).join(' ') ?? '';+ const flat = text.replace(/\s+/g, ' ').trim();+ if (!flat) return '(no text)';+ return flat.length > 200 ? `${flat.slice(0, 197)}…` : flat;+}+class AnthropicSession implements AgentSession {private readonly messages: Message[] = [];/** Context waiting for a legal spot — see {@link flushContext}. */@@ -195,16 +260,22 @@ class AnthropicSession implements AgentSession {/** Where each person's turn starts. A tool result is a `user` message too, so* counting roles would not find them. */private readonly turnStarts: number[] = [];+ /** Runs folded away by {@link compactOldest}. Turn coordinates count from the+ * start of the CONVERSATION, so they must survive their messages. */+ private dropped = 0;+ /** What the last call was billed for its input — the size of this whole+ * conversation as the endpoint measures it, which beats counting it here. */+ private lastInputTokens = 0;constructor(private readonly client: Anthropic,- private readonly opts: { model: string; effort: string; dialect: Dialect },+ private readonly opts: { model: string; effort: string; dialect: Dialect; contextWindow: number },private readonly system: string,private readonly tools: readonly CatalogTool[],) {}get turnIndex(): number {- return this.turnStarts.length;+ return this.dropped + this.turnStarts.length;}pushUser(text: string): void {@@ -213,14 +284,24 @@ class AnthropicSession implements AgentSession {}rewindTo(n: number): void {- const at = this.turnStarts[n];+ const at = this.turnStarts[n - this.dropped];+ // Rewinding into runs that have already been folded away is not something+ // this can do — their messages are gone. Refusing beats half-doing it.if (at === undefined) return;this.messages.length = at;- this.turnStarts.length = n;+ this.turnStarts.length = n - this.dropped;// Context buffered for a turn that is no longer going to happen.this.pending.length = 0;}+ private compactOldest(keepRuns: number): void {+ const next = compactHistory(this.messages, this.turnStarts, this.dropped, keepRuns);+ if (!next) return;+ this.messages.splice(0, this.messages.length, ...next.messages);+ this.turnStarts.splice(0, this.turnStarts.length, ...next.turnStarts);+ this.dropped = next.dropped;+ }+pushContext(text: string): void {this.pending.push(text);}@@ -275,6 +356,12 @@ class AnthropicSession implements AgentSession {async *step(signal: AbortSignal): AsyncIterable<StepEvent> {this.flushContext();+ // Fold the oldest runs away BEFORE a call that would not fit. Measured by+ // what the endpoint billed last time rather than by counting here: the+ // tokeniser is theirs, and an estimate that drifts low fails the turn.+ if (this.lastInputTokens > this.opts.contextWindow * COMPACT_AT) {+ this.compactOldest(KEEP_WHOLE_RUNS);+ }const request = buildStepRequest({dialect: this.opts.dialect,@@ -337,6 +424,7 @@ class AnthropicSession implements AgentSession {this.messages.push({ role: 'assistant', content: message.content as Message['content'] });if (message.usage) {+ this.lastInputTokens = message.usage.input_tokens ?? this.lastInputTokens;yield {type: 'usage',inputTokens: message.usage.input_tokens ?? 0,@@ -383,7 +471,11 @@ export function createAnthropicProvider(options: AnthropicOptions): AgentProvidereturn {id: dialect === 'anthropic' ? 'anthropic' : `compatible:${baseURL ?? ''}`,model,- createSession: ({ system, tools }) =>- new AnthropicSession(client, { model, effort, dialect }, system, tools),+ createSession: ({ system, tools }) => new AnthropicSession(+ client,+ { model, effort, dialect, contextWindow: options.contextWindow || DEFAULT_CONTEXT_WINDOW },+ system,+ tools,+ ),};}diff --git a/desktop/electron/agent/kernel.ts b/desktop/electron/agent/kernel.tsindex b8f9fef86..bb51878a6 100644--- a/desktop/electron/agent/kernel.ts+++ b/desktop/electron/agent/kernel.ts@@ -48,6 +48,27 @@ function summarize(text: string): string {return trimmed.length > 4000 ? `${trimmed.slice(0, 3997)}…` : trimmed;}+/**+ * The result as the MODEL receives it.+ *+ * A tool that answers with the whole scene can spend a conversation's context in+ * one call, and the turn that follows fails for a reason no one can see from the+ * transcript. Cut it, and SAY it was cut — a model handed a silently truncated+ * list believes it saw everything and reasons from a scene that ends at entity+ * 400. Most tools take a filter, so the useful thing to say is "ask for less".+ */+function budgeted(text: string): string {+ if (text.length <= MAX_TOOL_RESULT) return text;+ const kept = text.slice(0, MAX_TOOL_RESULT);+ return `${kept}\n\n[Truncated: this result was ${text.length} characters and only the first `+ + `${MAX_TOOL_RESULT} were kept. You have NOT seen all of it. Narrow the request — most `+ + 'tools take a filter or an id — rather than reasoning from what is above as if complete.]';+}++/** Room for a large-but-reasonable answer (a few hundred entities), well under+ * the smallest context window we assume (agentIds.DEFAULT_CONTEXT_WINDOW). */+const MAX_TOOL_RESULT = 24_000;+/*** MCP wraps a result as content blocks because that is its wire format. Text* flattens; an image stays an image — a tool whose whole purpose is letting the@@ -61,7 +82,7 @@ function toOutcome(id: string, result: {const text = result.content.filter((c) => c.type !== 'image').map((c) => c.text ?? '').join('\n');return {id,- content: text || (image ? 'screenshot attached' : 'ok'),+ content: budgeted(text) || (image ? 'screenshot attached' : 'ok'),isError: result.isError === true,...(image ? { image: { data: image.data!, mediaType: image.mimeType ?? 'image/png' } } : {}),};diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex 5b73df3aa..4bcb8b540 100644--- a/desktop/electron/main.ts+++ b/desktop/electron/main.ts@@ -675,7 +675,7 @@ ipcMain.handle('secret:clear', (_e, id: string) => clearSecret(id));// settings live in its localStorage) and merged, since the two rows fire// separately; read at session creation, so a change lands on the next// conversation rather than under the one being read.-let agentEndpoint: { baseUrl?: string; model?: string; keyId?: string } = {};+let agentEndpoint: { baseUrl?: string; model?: string; keyId?: string; contextWindow?: number } = {};const agentHost = createAgentHost({driver: createSurfaceDriver(() => win),@@ -692,6 +692,7 @@ const agentHost = createAgentHost({apiKey,baseURL: agentEndpoint.baseUrl,model: agentEndpoint.model,+ contextWindow: agentEndpoint.contextWindow,});},});@@ -702,7 +703,7 @@ ipcMain.handle('agent:stop', () => agentHost.stop());ipcMain.handle('agent:confirm', (_e, callId: string, allow: boolean) => agentHost.confirm(callId, allow));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 }) => {+ipcMain.handle('agent:setEndpoint', (_e, patch: { baseUrl?: string; model?: string; keyId?: string; contextWindow?: number }) => {agentEndpoint = { ...agentEndpoint, ...patch };// `ready` is derived from which key this points at, so it just changed.agentHost.announce();diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.tsindex 7478aa08d..7b81a6b20 100644--- a/desktop/electron/preload.ts+++ b/desktop/electron/preload.ts@@ -128,7 +128,7 @@ const api = {retry: (n: number, text: string): Promise<AgentStatus> => ipcRenderer.invoke('agent:retry', n, text),/** Point the NEXT session at an endpoint/model. Merged, so each settings row* can push its own field. */- setEndpoint: (patch: { baseUrl?: string; model?: string; keyId?: string }): Promise<void> =>+ setEndpoint: (patch: { baseUrl?: string; model?: string; keyId?: string; contextWindow?: number }): Promise<void> =>ipcRenderer.invoke('agent:setEndpoint', patch),/** Transcript events + status changes, in the order they happened; returns* an unsubscribe. One channel because the two must not be reordered. */diff --git a/desktop/src/agent/providers.ts b/desktop/src/agent/providers.tsindex 84b709e98..6939efa04 100644--- a/desktop/src/agent/providers.ts+++ b/desktop/src/agent/providers.ts@@ -30,10 +30,24 @@ export interface AgentProviderDef {baseUrl: string;/** What this provider offers, best-first. */models: readonly string[];+ /**+ * How much the conversation may grow before it has to be compacted, in tokens.+ *+ * Per provider rather than per model because one vendor's line sits at one+ * order of magnitude, and a table with a row per model is a table that goes+ * stale a model at a time. Unlike a PRICE — which we deliberately do not ship,+ * because being wrong there means confidently showing someone the wrong amount+ * of money — being wrong here costs a compaction that was not needed yet.+ * Absent means {@link DEFAULT_CONTEXT_WINDOW}: conservative, because guessing+ * high is what makes a turn fail outright.+ */+ contextWindow?: number;/** Filled in from settings rather than shipped — see {@link CUSTOM_PROVIDER}. */userDefined?: boolean;}+export { DEFAULT_CONTEXT_WINDOW } from '@/settings/agentIds';+/** The id a provider's key is stored under (electron/secrets.ts). */export const agentKeyId = (providerId: string): string => `agents.key.${providerId}`;@@ -47,12 +61,14 @@ registry.registerAll('core', [label: 'Anthropic',baseUrl: '',models: ['claude-opus-5', 'claude-sonnet-5', 'claude-haiku-4-5'],+ contextWindow: 200_000,},{id: 'deepseek',label: 'DeepSeek',baseUrl: 'https://api.deepseek.com/anthropic',models: ['deepseek-v4-pro', 'deepseek-v4-flash'],+ contextWindow: 1_000_000,},// The escape hatch. Its endpoint and model list come from settings, because a// provider we have not heard of is exactly the one we cannot ship a list for.diff --git a/desktop/src/settings/agentIds.ts b/desktop/src/settings/agentIds.tsindex 146a2250b..e8a9670ed 100644--- a/desktop/src/settings/agentIds.ts+++ b/desktop/src/settings/agentIds.ts@@ -13,3 +13,22 @@* real project: a wrong edit costs the user their scene, and the turn's* checkpoint only helps if the plan was sane. */export const DEFAULT_MODEL = 'claude-opus-5';++/**+ * What a gateway we have never heard of is assumed to accept, in tokens.+ *+ * Deliberately low. Guessing high means a turn that fails outright after the+ * person waited for it; guessing low means a compaction that was not needed yet.+ * Providers we do ship say their own (agent/providers.ts).+ */+export const DEFAULT_CONTEXT_WINDOW = 128_000;++/**+ * Fold the oldest runs away once the conversation is this far into its window,+ * keeping the last {@link KEEP_WHOLE_RUNS} intact.+ *+ * Not at the brim: the call that trips the limit is the one that fails, and it+ * fails after the wait. Three quarters leaves room for one more large turn.+ */+export const COMPACT_AT = 0.75;+export const KEEP_WHOLE_RUNS = 3;diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.tsindex b644abcb1..8e1ab1a30 100644--- a/desktop/src/store/AgentStore.ts+++ b/desktop/src/store/AgentStore.ts@@ -20,7 +20,7 @@ import { create } from 'zustand';import type { AgentStatus, AgentMessage } from '../../electron/agent/host';import type { AgentEvent, ConfirmReason, ConfirmRequest } from '../../electron/agent/types';import {- agentProviders, agentProvider, agentKeyId, parseModelList, CUSTOM_PROVIDER,+ agentProviders, agentProvider, agentKeyId, parseModelList, CUSTOM_PROVIDER, DEFAULT_CONTEXT_WINDOW,} from '@/agent/providers';import { refreshSecret, secretStatus, subscribeSecrets } from '@/store/SecretStore';import { useSettings } from '@/store/settingsStore';@@ -192,6 +192,9 @@ export function syncAgentEndpoint(): void {baseUrl: def?.baseUrl ?? '',model: selection?.model ?? '',keyId: selection ? agentKeyId(selection.providerId) : '',+ // How far the conversation may grow before it is compacted. Travels with the+ // endpoint because it is the same piece of knowledge: which provider this is.+ contextWindow: def?.contextWindow ?? DEFAULT_CONTEXT_WINDOW,});}diff --git a/desktop/tests/agent-compaction.test.ts b/desktop/tests/agent-compaction.test.tsnew file mode 100644index 000000000..b62607cb0--- /dev/null+++ b/desktop/tests/agent-compaction.test.ts@@ -0,0 +1,100 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Folding the oldest runs away when a conversation outgrows its window.+ *+ * Two things have to survive it: what the PERSON asked (intent governs+ * the ninth run as much as the first), and the turn COORDINATES the rest+ * of the system names runs by — those count from the start of the+ * conversation, so they must outlive the messages they pointed at.+ */+import { describe, it, expect } from 'vitest';+import { compactHistory } from '../electron/agent/anthropic';++type Message = Parameters<typeof compactHistory>[0][number];++/** `runs` turns, each: the person's line, the model's reply, a tool result. */+function history(runs: number): { messages: Message[]; turnStarts: number[] } {+ const messages: Message[] = [];+ const turnStarts: number[] = [];+ for (let i = 0; i < runs; i++) {+ turnStarts.push(messages.length);+ messages.push({ role: 'user', content: `ask ${i}` });+ messages.push({ role: 'assistant', content: `reply ${i}` });+ messages.push({ role: 'user', content: `tool result ${i}` });+ }+ return { messages, turnStarts };+}++describe('compacting a long conversation', () => {+ it('leaves a short one alone', () => {+ const { messages, turnStarts } = history(3);+ expect(compactHistory(messages, turnStarts, 0, 3)).toBeNull();+ expect(compactHistory(messages, turnStarts, 0, 5)).toBeNull();+ });++ it('keeps the last runs whole and folds the rest into one note', () => {+ const { messages, turnStarts } = history(6);+ const out = compactHistory(messages, turnStarts, 0, 2)!;++ // Note + acknowledgement, then the last two runs verbatim (3 messages each).+ expect(out.messages).toHaveLength(2 + 6);+ expect(out.messages[0].role).toBe('user');+ expect(out.messages[2]).toEqual({ role: 'user', content: 'ask 4' });+ expect(out.messages.at(-1)).toEqual({ role: 'user', content: 'tool result 5' });+ });++ it('carries what was asked, and says the rest was dropped', () => {+ const { messages, turnStarts } = history(5);+ const note = String(compactHistory(messages, turnStarts, 0, 2)!.messages[0].content);++ for (const asked of ['ask 0', 'ask 1', 'ask 2']) expect(note).toContain(asked);+ // Told it is a summary, and told to re-read rather than trust it — a model+ // that believes this IS the state will edit from a scene it never saw.+ expect(note).toMatch(/dropped|read it back/i);+ });++ // The whole point of the bookkeeping: run 7 stays run 7 after its messages are+ // gone, or "re-ask this one" rewinds the session to the wrong place.+ it('keeps turn coordinates counting from the start of the conversation', () => {+ const { messages, turnStarts } = history(6);+ const out = compactHistory(messages, turnStarts, 0, 2)!;++ expect(out.dropped).toBe(4);+ // Next turn opens at 6 — the same number it would have without compaction.+ expect(out.dropped + out.turnStarts.length).toBe(6);+ });++ it('re-bases what is left so each start still points at that person\'s line', () => {+ const { messages, turnStarts } = history(6);+ const out = compactHistory(messages, turnStarts, 0, 2)!;++ expect(out.turnStarts.map((s) => out.messages[s])).toEqual([+ { role: 'user', content: 'ask 4' },+ { role: 'user', content: 'ask 5' },+ ]);+ });++ it('numbers the note from the runs already folded away, not from zero', () => {+ const { messages, turnStarts } = history(5);+ const out = compactHistory(messages, turnStarts, 10, 2)!;++ expect(String(out.messages[0].content)).toContain('11. ask 0');+ expect(out.dropped).toBe(13);+ });++ // Compacting twice is the ordinary case in a conversation long enough to need+ // it once — the second pass must fold the note itself away with the rest.+ it('can be applied again to its own output', () => {+ const first = compactHistory(...Object.values(history(6)) as [Message[], number[]], 0, 2)!;+ const grown = {+ messages: [...first.messages, { role: 'user' as const, content: 'ask 6' }],+ turnStarts: [...first.turnStarts, first.messages.length],+ };+ const second = compactHistory(grown.messages, grown.turnStarts, first.dropped, 1)!;++ expect(second.dropped).toBe(6);+ expect(second.turnStarts.map((s) => second.messages[s]))+ .toEqual([{ role: 'user', content: 'ask 6' }]);+ });+});diff --git a/desktop/tests/agent-kernel.test.ts b/desktop/tests/agent-kernel.test.tsindex bf83385c7..ed02dad4b 100644--- a/desktop/tests/agent-kernel.test.ts+++ b/desktop/tests/agent-kernel.test.ts@@ -20,6 +20,8 @@ function fakeSession(steps: StepEvent[][]): AgentSession & {const results: ToolOutcome[][] = [];return {context, user, results,+ // Faithful to the real one: the coordinate the next turn will occupy.+ get turnIndex() { return user.length; },pushUser: (t) => { user.push(t); },pushContext: (t) => { context.push(t); },pushToolResults: (o) => { results.push([...o]); },@@ -44,7 +46,7 @@ describe('the agent turn', () => {let diagnostics: unknown[];const deps = (session: AgentSession) => ({- driver: driver as never, session, confirm: confirm as never,+ driver: driver as never, session, model: 'fake-model', confirm: confirm as never,emit: (e: AgentEvent) => { events.push(e); },});const kinds = () => events.map((e) => e.type);@@ -73,7 +75,7 @@ describe('the agent turn', () => {expect(out.steps).toBe(3);// Both carry what the editor's read model needs and cannot infer across IPC:// what was asked, and the point an Undo would go back to.- expect(events.at(0)).toEqual({ type: 'turn_start', prompt: 'hi' });+ expect(events.at(0)).toEqual({ type: 'turn_start', prompt: 'hi', model: 'fake-model', index: 0 });expect(events.at(-1)).toEqual({ type: 'turn_end', steps: 3, mark: { seq: 7 }, reason: 'end_turn' });});@@ -201,4 +203,38 @@ describe('the agent turn', () => {const ended = events.find((e) => e.type === 'tool_end');expect(ended).toMatchObject({ image: 'data:image/png;base64,BASE64PNG' });});++ // A tool that answers with the whole scene can spend a conversation's context+ // in one call, and the turn after it fails for a reason nothing on screen+ // explains. The cut has to be SAID, too: a model handed a silently truncated+ // list believes it saw everything and edits from a scene that ends early.+ describe('a result too big to hand the model whole', () => {+ it('cuts it, and says it was cut', async () => {+ const huge = Array.from({ length: 4000 }, (_, i) => ({ id: i, name: `Entity${i}` }));+ driver = vi.fn(async (method: string) => {+ if (method === 'mark') return { seq: 7 };+ if (method === 'stepsSince') return stepsSince;+ if (method === 'getDiagnostics') return diagnostics;+ if (method === 'getSceneTree') return huge;+ return null;+ }) as never;+ (driver as { js: unknown }).js = vi.fn(async () => null);+ (driver as { op: unknown }).op = vi.fn(async () => null);++ const s = fakeSession([asks(call('get_scene_tree')), ends()]);+ await runTurn(deps(s), 'what is in here', null, new AbortController().signal);++ const content = String(s.results[0][0].content);+ expect(content.length).toBeLessThan(30_000);+ expect(content).toContain('Truncated');+ // Told what to do instead, not just that something is missing.+ expect(content).toMatch(/narrow/i);+ });++ it('leaves an ordinary result untouched', async () => {+ const s = fakeSession([asks(call('get_scene_tree')), ends()]);+ await runTurn(deps(s), 'what is in here', null, new AbortController().signal);+ expect(String(s.results[0][0].content)).not.toContain('Truncated');+ });+ });});