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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: AgentSes
const 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.ts
new file mode 100644
index 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.ts
index 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 Age
describe('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(),