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
fix(editor): a run's identity is the session's, so a reloaded window can rejoin it
esengine526296fbd90e
diff --git a/desktop/electron/agent/anthropic.ts b/desktop/electron/agent/anthropic.tsindex f65dc9221..929ddcec5 100644--- a/desktop/electron/agent/anthropic.ts+++ b/desktop/electron/agent/anthropic.ts@@ -203,6 +203,10 @@ class AnthropicSession implements AgentSession {private readonly tools: readonly CatalogTool[],) {}+ get turnIndex(): number {+ return this.turnStarts.length;+ }+pushUser(text: string): void {this.turnStarts.push(this.messages.length);this.messages.push({ role: 'user', content: text });diff --git a/desktop/electron/agent/host.ts b/desktop/electron/agent/host.tsindex 409522080..758aee84a 100644--- a/desktop/electron/agent/host.ts+++ b/desktop/electron/agent/host.ts@@ -75,6 +75,17 @@ export interface AgentHost {* whole conversation leading up to it.*/retry(n: number, text: string): AgentStatus;+ /**+ * Every event of the open conversation, in order, so a window that was not+ * there for them can rebuild the transcript.+ *+ * The stream is the record. A reloaded renderer used to come back to an empty+ * drawer while this host still held the conversation — the model remembered+ * what the screen had forgotten, and a "re-ask" aimed at run 0 of a transcript+ * that started counting again rewound the session to somewhere nobody asked+ * for. Replaying is what makes the two sides agree again.+ */+ transcript(): readonly AgentEvent[];/*** Re-push the status because something OUTSIDE changed it — the window picked* a different provider, so `ready` now answers differently. Without this the@@ -101,7 +112,32 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {});const pushStatus = (): void => deps.push({ kind: 'status', status: status() });- const emit = (event: AgentEvent): void => deps.push({ kind: 'event', event });++ // The conversation as a replayable stream. Bounded, and trimmed by WHOLE runs+ // from the front: half a run replays as a run that never ended. Dropping the+ // oldest is safe only because a run's identity is the session's own index and+ // not its position here — see AgentSession.turnIndex.+ const log: AgentEvent[] = [];+ const LOG_LIMIT = 4000;++ const trimOldestRun = (): void => {+ const next = log.findIndex((e, i) => i > 0 && e.type === 'turn_start');+ // One run longer than the whole budget: keep it rather than corrupt it.+ if (next > 0) log.splice(0, next);+ };++ /** A re-ask discards that run and everything after it — here too, or the+ * replay would hand a reloaded window the runs it just threw away. */+ const trimFrom = (turnIndex: number): void => {+ const at = log.findIndex((e) => e.type === 'turn_start' && e.index === turnIndex);+ if (at >= 0) log.length = at;+ };++ const emit = (event: AgentEvent): void => {+ log.push(event);+ if (log.length > LOG_LIMIT) trimOldestRun();+ deps.push({ kind: 'event', event });+ };/** Settle every outstanding ask as declined. See invariant 2. */const settlePending = (): void => {@@ -134,7 +170,10 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {}}- if (rewindTo !== undefined) session.rewindTo(rewindTo);+ if (rewindTo !== undefined) {+ session.rewindTo(rewindTo);+ trimFrom(rewindTo);+ }error = null;phase = 'running';@@ -207,8 +246,10 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {model = null;phase = 'idle';error = null;+ log.length = 0;pushStatus();return status();},+ transcript: () => log,};}diff --git a/desktop/electron/agent/kernel.ts b/desktop/electron/agent/kernel.tsindex 421564c62..b8f9fef86 100644--- a/desktop/electron/agent/kernel.ts+++ b/desktop/electron/agent/kernel.ts@@ -86,7 +86,8 @@ export async function runTurn(): Promise<{ mark: unknown; steps: number }> {const { driver, session, emit, model } = deps;const mark = await driver('mark', []);- emit({ type: 'turn_start', prompt: text, model });+ // Read before pushUser opens it: this is the index that turn will occupy.+ emit({ type: 'turn_start', prompt: text, model, index: session.turnIndex });let reason: Extract<AgentEvent, { type: 'turn_end' }>['reason'] = 'end_turn';try {diff --git a/desktop/electron/agent/types.ts b/desktop/electron/agent/types.tsindex fa54ce7ca..e5a128518 100644--- a/desktop/electron/agent/types.ts+++ b/desktop/electron/agent/types.ts@@ -71,6 +71,17 @@ export type StepEvent =* appends, then asks for a step; it never reads the history back.*/export interface AgentSession {+ /**+ * Which person's turn the NEXT {@link pushUser} opens — the coordinate+ * {@link rewindTo} counts in.+ *+ * The transcript quotes it back as a run's identity rather than numbering runs+ * itself. A renderer that numbered its own would agree with the session only+ * until it lost some (a reload, a trimmed log), after which "re-ask run 0"+ * meant two different turns on the two sides and rewinding threw away a+ * conversation nobody asked to end.+ */+ readonly turnIndex: number;/** The person's turn. */pushUser(text: string): void;/**@@ -134,8 +145,9 @@ export interface ConfirmRequest {export type AgentEvent =| StepEvent/** `model` because a conversation can change models between runs, and the- * header of a past run has to say which one actually answered it. */- | { type: 'turn_start'; prompt: string; model: string }+ * header of a past run has to say which one answered it. `index` is the+ * session's own coordinate for this run — see {@link AgentSession.turnIndex}. */+ | { type: 'turn_start'; prompt: string; model: string; index: number }| { type: 'tool_start'; call: ToolCall; effect: NonNullable<CatalogTool['effect']> }| { type: 'tool_end'; id: string; ok: boolean; summary: string; image?: string }| { type: 'awaiting_confirm'; request: ConfirmRequest }diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex 0b98a60cd..5b73df3aa 100644--- a/desktop/electron/main.ts+++ b/desktop/electron/main.ts@@ -696,6 +696,7 @@ const agentHost = createAgentHost({},});ipcMain.handle('agent:status', () => agentHost.status());+ipcMain.handle('agent:transcript', () => agentHost.transcript());ipcMain.handle('agent:send', (_e, text: string) => agentHost.send(text));ipcMain.handle('agent:stop', () => agentHost.stop());ipcMain.handle('agent:confirm', (_e, callId: string, allow: boolean) => agentHost.confirm(callId, allow));diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.tsindex 993a68466..7478aa08d 100644--- a/desktop/electron/preload.ts+++ b/desktop/electron/preload.ts@@ -22,6 +22,7 @@ import type { NativeTemplateEntry, InstallResult } from './nativeTemplates';import type { McpEndpointStatus } from './mcpEndpoint';import type { SecretStatus } from './secrets';import type { AgentStatus, AgentMessage } from './agent/host';+import type { AgentEvent } from './agent/types';// The privileged bridge the renderer is allowed to touch. Keep this surface small// and explicit — anything the editor needs from the OS or Node goes through here.@@ -113,6 +114,8 @@ const api = {// this is the window's way to talk to it and to hear what it is doing. —agent: {status: (): Promise<AgentStatus> => ipcRenderer.invoke('agent:status'),+ /** The open conversation's events, for a window that was not there for them. */+ transcript: (): Promise<AgentEvent[]> => ipcRenderer.invoke('agent:transcript'),/** Start a turn; resolves with the resulting status, refusals included. */send: (text: string): Promise<AgentStatus> => ipcRenderer.invoke('agent:send', text),stop: (): Promise<void> => ipcRenderer.invoke('agent:stop'),diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.tsindex a66a550b4..b644abcb1 100644--- a/desktop/src/store/AgentStore.ts+++ b/desktop/src/store/AgentStore.ts@@ -249,8 +249,14 @@ function patchTool(entries: readonly AgentEntry[], id: string, patch: Partial<Ag*/export function applyAgentEvent(turns: readonly AgentTurn[], event: AgentEvent): AgentTurn[] {if (event.type === 'turn_start') {+ // Idempotent, so replaying the stream over a transcript that already has+ // some of it cannot double a run (see attachAgentBridge).+ if (turns.some((t) => t.id === event.index)) return turns as AgentTurn[];return [...turns, {- id: turns.length,+ // The SESSION's coordinate, not this array's position. They agree while a+ // window sees every run, and stop agreeing the moment one reloads — after+ // which numbering here would aim "re-ask run 0" at the wrong turn.+ id: event.index,prompt: event.prompt,model: event.model,entries: [],@@ -403,6 +409,18 @@ export function applyAgentMessage(message: AgentMessage): void {export function attachAgentBridge(): () => void {const off = window.estella?.agent?.onMessage(applyAgentMessage) ?? (() => {});void window.estella?.agent?.status().then(adoptStatus);+ // The conversation can outlive the window: main holds the session, so a reload+ // used to come back to an empty drawer while the model still remembered+ // everything. Subscribed FIRST so nothing arriving meanwhile is missed; the+ // replay is the history in front of whatever did (runs are matched by id).+ void window.estella?.agent?.transcript?.().then((events) => {+ if (!events?.length) return;+ useAgent.setState((s) => {+ const replayed = events.reduce<AgentTurn[]>(applyAgentEvent, []);+ const known = new Set(replayed.map((t) => t.id));+ return { turns: [...replayed, ...s.turns.filter((t) => !known.has(t.id))] };+ });+ });// Which keys exist decides which provider runs when nothing is picked, so ask// once at boot rather than the first time a settings row happens to render.for (const p of agentProviders()) void refreshSecret(agentKeyId(p.id)).then(syncAgentEndpoint);@@ -447,9 +465,10 @@ export const clearAgentQueue = (): void => useAgent.setState({ queued: [] });* already forgotten.*/export async function retryAgentTurn(turnId: number): Promise<void> {- const turn = useAgent.getState().turns[turnId];+ const turn = useAgent.getState().turns.find((t) => t.id === turnId);if (!turn) return;- useAgent.setState((s) => ({ turns: s.turns.slice(0, turnId), checkpointDone: null }));+ // By id, not by position: this window may not hold every run the session does.+ useAgent.setState((s) => ({ turns: s.turns.filter((t) => t.id < turnId), checkpointDone: null }));const status = await window.estella?.agent?.retry(turnId, turn.prompt);if (status) adoptStatus(status);}diff --git a/desktop/tests/agent-host.test.ts b/desktop/tests/agent-host.test.tsindex 20f046f61..39b67a186 100644--- a/desktop/tests/agent-host.test.ts+++ b/desktop/tests/agent-host.test.ts@@ -23,10 +23,14 @@ function fakeProvider(steps: StepEvent[][]): AgentProvider & { session: AgentSesconst session: AgentSession & { asked: string[]; rewinds: number[] } = {asked: [],rewinds: [],+ // The real one counts person's turns; asking is what opens them.+ get turnIndex() { return session.asked.length; },pushUser: (t) => { session.asked.push(t); },pushContext: () => {},pushToolResults: () => {},- rewindTo: (n) => { session.rewinds.push(n); },+ // Faithful about the coordinate too: rewinding drops those turns, so the+ // next one reopens at n — which is what the host stamps onto turn_start.+ rewindTo: (n) => { session.rewinds.push(n); session.asked.length = n; },step: async function* () {for (const ev of steps[at] ?? [{ type: 'stop', reason: 'end_turn' }]) yield ev;at++;@@ -217,4 +221,60 @@ describe('the agent host', () => {expect(provider!.session.rewinds).toEqual([]);expect(provider!.session.asked).toEqual(['hello']);});++ // The conversation outlives the window: main holds the session, so a reloaded+ // renderer has to be able to rebuild what it was never there for.+ describe('the replayable transcript', () => {+ const startsIn = (h: AgentHost): number[] =>+ h.transcript().filter((e) => e.type === 'turn_start').map((e) => (e as { index: number }).index);++ it('keeps the conversation as a stream a new window can fold', async () => {+ const h = host([ends(), ends()]);+ h.send('first');+ await settled(h);+ h.send('second');+ await settled(h);++ expect(startsIn(h)).toEqual([0, 1]);+ // Same events, same order as were pushed live — the replay IS the record.+ expect(h.transcript().map((e) => e.type))+ .toEqual(messages.filter((m) => m.kind === 'event').map((m) => (m as { event: { type: string } }).event.type));+ });++ it('names each run with the session\'s own coordinate', async () => {+ const h = host([ends(), ends(), ends()]);+ h.send('first');+ await settled(h);+ h.send('second');+ await settled(h);+ h.send('third');+ await settled(h);+ expect(startsIn(h)).toEqual([0, 1, 2]);+ });++ // A re-ask discards that run and everything after it. Replaying afterwards+ // must not hand a window back the runs the session has already forgotten.+ it('drops the re-asked run and everything after it', async () => {+ const h = host([ends(), ends(), ends(), ends()]);+ h.send('first');+ await settled(h);+ h.send('second');+ await settled(h);+ h.send('third');+ await settled(h);++ h.retry(1, 'second, but better');+ await settled(h);+ expect(startsIn(h)).toEqual([0, 1]);+ });++ it('forgets everything when the conversation is dropped', async () => {+ const h = host([ends()]);+ h.send('first');+ await settled(h);+ expect(h.transcript().length).toBeGreaterThan(0);+ h.reset();+ expect(h.transcript()).toEqual([]);+ });+ });});diff --git a/desktop/tests/agent-replay.test.ts b/desktop/tests/agent-replay.test.tsnew file mode 100644index 000000000..258a53fd2--- /dev/null+++ b/desktop/tests/agent-replay.test.ts@@ -0,0 +1,92 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A window attaching to a conversation that started without it.+ *+ * main owns the session, so it outlives a reload. The drawer used to come+ * back empty from one — the model remembered what the screen had+ * forgotten — and worse, a transcript that started numbering runs again+ * made "re-ask this one" name a different turn on each side. Runs carry+ * the session's own coordinate now, and the stream is replayed on attach.+ */+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';+import { useAgent, attachAgentBridge } from '@/store/AgentStore';+import type { AgentEvent } from '../electron/agent/types';+import type { AgentStatus } from '../electron/agent/host';++const status: AgentStatus =+ { ready: true, conversation: true, phase: 'idle', model: 'opus-5', error: null };++/** A conversation of two finished runs, as main would have logged it. */+const conversation = (from = 0): AgentEvent[] => [+ { type: 'turn_start', prompt: 'add a pause menu', model: 'opus-5', index: from },+ { type: 'text', delta: 'Building it.' },+ { type: 'turn_end', steps: 7, mark: { seq: 1 }, reason: 'end_turn' },+ { type: 'turn_start', prompt: 'bigger buttons', model: 'opus-5', index: from + 1 },+ { type: 'text', delta: 'Done.' },+ { type: 'turn_end', steps: 3, mark: { seq: 2 }, reason: 'end_turn' },+];++let transcript: AgentEvent[];+let listener: ((m: unknown) => void) | null;++beforeEach(() => {+ transcript = [];+ listener = null;+ (globalThis as { window?: unknown }).window = {+ estella: {+ agent: {+ onMessage: (cb: (m: unknown) => void) => { listener = cb; return () => { listener = null; }; },+ status: async () => status,+ transcript: async () => transcript,+ setEndpoint: async () => {},+ },+ secrets: { status: async () => ({ id: 'x', configured: false, storage: 'keychain', error: null }) },+ },+ };+ useAgent.setState({ turns: [], queued: [], checkpointDone: null });+});++afterEach(() => { delete (globalThis as { window?: unknown }).window; });++const settle = () => new Promise((r) => setTimeout(r, 0));++describe('attaching to a conversation already in progress', () => {+ it('rebuilds the transcript from the stream', async () => {+ transcript = conversation();+ attachAgentBridge();+ await settle();++ const { turns } = useAgent.getState();+ expect(turns.map((t) => t.prompt)).toEqual(['add a pause menu', 'bigger buttons']);+ expect(turns.map((t) => t.reason)).toEqual(['end_turn', 'end_turn']);+ });++ // The point of the whole exercise: what this window calls run 7 has to be what+ // the session calls run 7, or rewinding to it discards the wrong thing.+ it('keeps the session\'s numbering, not its own', async () => {+ transcript = conversation(7);+ attachAgentBridge();+ await settle();+ expect(useAgent.getState().turns.map((t) => t.id)).toEqual([7, 8]);+ });++ // Subscribed before the transcript is asked for, so nothing arriving in+ // between is dropped — which means the two can overlap, and must not double.+ it('does not double a run that arrived live while it was catching up', async () => {+ transcript = conversation();+ attachAgentBridge();+ // Main pushes the tail of the same conversation before the replay lands.+ for (const event of conversation()) listener?.({ kind: 'event', event });+ await settle();++ const { turns } = useAgent.getState();+ expect(turns.map((t) => t.id)).toEqual([0, 1]);+ });++ it('leaves an empty conversation empty', async () => {+ attachAgentBridge();+ await settle();+ expect(useAgent.getState().turns).toEqual([]);+ });+});diff --git a/desktop/tests/agent-transcript.test.ts b/desktop/tests/agent-transcript.test.tsindex 71d4aba8f..9ae23a868 100644--- a/desktop/tests/agent-transcript.test.ts+++ b/desktop/tests/agent-transcript.test.ts@@ -17,8 +17,8 @@ import type { AgentEvent, ToolCall } from '../electron/agent/types';const fold = (...events: AgentEvent[]): AgentTurn[] =>events.reduce<AgentTurn[]>((turns, e) => applyAgentEvent(turns, e), []);-const started = (prompt = 'add a pause menu', model = 'opus-5'): AgentEvent =>- ({ type: 'turn_start', prompt, model });+const started = (prompt = 'add a pause menu', index = 0, model = 'opus-5'): AgentEvent =>+ ({ type: 'turn_start', prompt, model, index });const ended = (over: Partial<{ steps: number; mark: unknown; reason: 'end_turn' | 'aborted' | 'error' | 'refusal' }> = {}): AgentEvent =>({ type: 'turn_end', steps: 0, mark: null, reason: 'end_turn', ...over });const call = (name: string): ToolCall => ({ id: `c-${name}`, name, input: { a: 1 } });@@ -26,7 +26,7 @@ const tools = (t: AgentTurn): AgentToolEntry[] => t.entries.filter((e): e is Agedescribe('the transcript projection', () => {it('opens a run per turn, carrying what was asked', () => {- const turns = fold(started('one'), ended(), started('two'));+ const turns = fold(started('one'), ended(), started('two', 1));expect(turns.map((t) => t.prompt)).toEqual(['one', 'two']);expect(turns.map((t) => t.reason)).toEqual(['end_turn', null]);});@@ -34,10 +34,27 @@ describe('the transcript projection', () => {// The header of a past run has to say which model answered IT — the picker in// the composer only ever says what the NEXT message will use.it('records the model that answered each run, not just the current one', () => {- const turns = fold(started('one', 'opus-5'), ended(), started('two', 'haiku-4-5'));+ const turns = fold(started('one', 0, 'opus-5'), ended(), started('two', 1, 'haiku-4-5'));expect(turns.map((t) => t.model)).toEqual(['opus-5', 'haiku-4-5']);});+ // A run's identity is the SESSION's coordinate. A window that only saw the+ // tail of a conversation still has to name run 7 the way the session does, or+ // "re-ask this one" rewinds to somewhere nobody asked for.+ it('takes a run\'s identity from the session, not from its own position', () => {+ const turns = fold(started('seventh', 7), ended(), started('eighth', 8));+ expect(turns.map((t) => t.id)).toEqual([7, 8]);+ });++ // Replaying the stream over a transcript that already holds part of it is how+ // a reloaded window catches up — it must not double the runs it already had.+ it('replays without doubling a run it already has', () => {+ const stream = [started('one'), ended(), started('two', 1)];+ const once = fold(...stream);+ const twice = stream.reduce<AgentTurn[]>(applyAgentEvent, once);+ expect(twice.map((t) => t.id)).toEqual([0, 1]);+ });+it('gathers a streamed answer into one paragraph', () => {const [turn] = fold(started(),