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(agent): a tier for the writes something is holding

esengine05c4f780bf05
diff --git a/desktop/electron/agent/host.ts b/desktop/electron/agent/host.ts
index e3eab2cdf..a37565071 100644
--- a/desktop/electron/agent/host.ts
+++ b/desktop/electron/agent/host.ts
@@ -24,7 +24,8 @@
import { runTurn, agentTools, type ContributedTool } from './kernel';
import { SYSTEM_PROMPT, editorContext } from './prompt';
import type {
- AgentEvent, AgentProvider, AgentSession, ConfirmAnswer, ConfirmDecision, ConfirmRequest, UserImage,
+ AgentEvent, AgentProvider, AgentSession, ConfirmAnswer, ConfirmDecision, ConfirmRequest,
+ KernelDeps, UserImage,
} from './types';
import type { SurfaceDriver } from '../surfaceDriver';
@@ -84,6 +85,9 @@ export interface AgentHostDeps {
* construction would be the empty one, since plugins load after main does.
*/
contributedTools?(): readonly ContributedTool[];
+ /** The disk half of a turn's checkpoint. Absent in a host with no project —
+ * the kernel then confirms the writes it would otherwise have covered. */
+ journal?: KernelDeps['journal'];
}
/** A conversation as the host hands it over to be kept. See agent/store.ts. */
@@ -338,7 +342,10 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
// would be a second definition of "what the agent knows".
const context = await editorContext(deps.driver).catch(() => null);
await runTurn(
- { driver: deps.driver, session: session!, model: model ?? '', acceptsImages, confirm, emit },
+ {
+ driver: deps.driver, session: session!, model: model ?? '',
+ acceptsImages, confirm, emit, journal: deps.journal,
+ },
text,
context,
controller.signal,
@@ -350,7 +357,7 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
// path is reached BEFORE the turn starts (runTurn takes its checkpoint
// outside its own try), so there is no turn for it to be part of.
error = (e as Error)?.message ?? String(e);
- emit({ type: 'turn_end', steps: 0, mark: null, reason: 'error' });
+ emit({ type: 'turn_end', steps: 0, mark: null, tx: null, files: [], reason: 'error' });
} finally {
settlePending();
// The run is over either way — errors included, since a conversation
diff --git a/desktop/electron/agent/kernel.ts b/desktop/electron/agent/kernel.ts
index 75121a3e4..f71abdd42 100644
--- a/desktop/electron/agent/kernel.ts
+++ b/desktop/electron/agent/kernel.ts
@@ -17,7 +17,7 @@ import type {
} from './types';
// Plain .mjs, shared with the MCP fronts — esbuild bundles it into main.
// @ts-expect-error untyped shared module
-import { TOOLS, runTool, mutates, irreversible } from '../../shared/toolCatalog.mjs';
+import { TOOLS, runTool, mutates, irreversible, journaled } from '../../shared/toolCatalog.mjs';
// `driverOnly` tools are doors for an EXTERNAL driver (a harness running the
// editor's agent as a subject). The agent itself must not see them: a tool that
@@ -75,13 +75,16 @@ export interface ContributedTool {
name: string;
description: string;
schema: unknown;
- effect: 'read' | 'undoable' | 'irreversible';
+ effect: 'read' | 'undoable' | 'journaled' | 'irreversible';
}
/** Why `tool` needs saying out loud. A code — the editor renders the sentence,
* because it is the side that knows the reader's language. */
function confirmReason(tool: CatalogTool): ConfirmReason {
if (tool.name === BULK_EDIT_TOOL) return 'bulk_edit';
+ // A journaled tool only reaches the gate when nothing is holding its bytes,
+ // and that — not the tool — is what the person is being asked about.
+ if (journaled(tool)) return 'unjournaled';
return tool.name === 'run_editor_command' || tool.name === 'play_probe'
? 'arbitrary_code'
: 'irreversible';
@@ -154,13 +157,12 @@ function toOutcome(id: string, result: {
/**
* Run one turn to completion.
*
- * The turn is bracketed by an undo checkpoint rather than a transaction: a
- * transaction held across model latency would lock the editor for seconds and
- * leave a dangling one on a crash, while a checkpoint lets each tool call stay
- * its own ordinary undo step AND the whole turn revert in one gesture
- * (EditorHistory.mark).
+ * Bracketed by a CHECKPOINT over both halves it can change: an EditorHistory
+ * mark for the document, a fileJournal transaction for the disk. Neither is a
+ * lock — one held across model latency would freeze the editor. Each call stays
+ * its own undo step; the pair is what brings the whole turn back at once.
*
- * @returns the checkpoint, so the caller can offer that revert.
+ * @returns both, so the caller can offer that revert.
*/
export async function runTurn(
deps: KernelDeps,
@@ -168,9 +170,13 @@ export async function runTurn(
context: string | null,
signal: AbortSignal,
images?: readonly UserImage[],
-): Promise<{ mark: unknown; steps: number }> {
+): Promise<{ mark: unknown; steps: number; tx: string | null }> {
const { driver, session, emit, model, acceptsImages } = deps;
const mark = await driver('mark', []);
+ // Opened before the first call and closed once, in the finally below: a
+ // transaction that leaked past the turn would keep capturing the user's own
+ // edits into a checkpoint labelled with the model's prompt.
+ const tx = deps.journal?.begin() ?? null;
// Read before pushUser opens it: this is the index that turn will occupy.
emit({ type: 'turn_start', prompt: text, model, index: session.turnIndex });
@@ -306,8 +312,8 @@ export async function runTurn(
let end = i;
while (end < calls.length && isRead(calls[end])) end++;
const batch = end - i > 1
- ? await Promise.all(calls.slice(i, end).map((c) => execute(deps, c, allowed, signal)))
- : [await execute(deps, calls[i], allowed, signal)];
+ ? await Promise.all(calls.slice(i, end).map((c) => execute(deps, c, allowed, signal, tx !== null)))
+ : [await execute(deps, calls[i], allowed, signal, tx !== null)];
for (const done of batch) {
outcomes.push(done.outcome);
wrote ||= done.mutated;
@@ -344,9 +350,13 @@ export async function runTurn(
}
if (signal.aborted) reason = 'aborted';
+ // Closed before the tally is read, so nothing the editor does while rendering
+ // the result lands in the turn's own transaction.
+ deps.journal?.end();
const steps = await undoSteps(deps, mark);
- emit({ type: 'turn_end', steps, mark, reason });
- return { mark, steps };
+ const files = tx ? deps.journal?.changes(tx) ?? [] : [];
+ emit({ type: 'turn_end', steps, mark, tx, files, reason });
+ return { mark, steps, tx };
}
/**
@@ -436,6 +446,7 @@ async function execute(
call: ToolCall,
allowed: Set<string>,
signal: AbortSignal,
+ journalling: boolean,
): Promise<{ outcome: ToolOutcome; mutated: boolean }> {
const { emit, driver, confirm } = deps;
const tool = byName.get(call.name);
@@ -449,12 +460,12 @@ async function execute(
const effect = tool.effect ?? 'read';
emit({ type: 'tool_start', call, effect });
- // The one gate. `read` and `undoable` run unasked — the turn's checkpoint is
- // the approval, and a prompt per setField would make the agent unusable.
- // `irreversible` is where undo stops being an answer, so it is where the
- // person has to be.
- // Already waved through for the rest of this run — see ConfirmAnswer.
- const gated = irreversible(tool) || call.name === BULK_EDIT_TOOL;
+ // The one gate. Everything the turn's checkpoint covers runs unasked. The flag
+ // is why the tier is not enough: journaled with NO transaction open is
+ // irreversible wearing a gentler tier.
+ const gated = irreversible(tool)
+ || call.name === BULK_EDIT_TOOL
+ || (journaled(tool) && !journalling);
let input = call.input;
if (gated && !allowed.has(call.name)) {
const request = { callId: call.id, tool: call.name, reason: confirmReason(tool), input: call.input };
diff --git a/desktop/electron/agent/types.ts b/desktop/electron/agent/types.ts
index 7368fce83..ff95124c3 100644
--- a/desktop/electron/agent/types.ts
+++ b/desktop/electron/agent/types.ts
@@ -20,7 +20,7 @@ export interface CatalogTool {
name: string;
description: string;
schema: Record<string, unknown>;
- effect?: 'read' | 'undoable' | 'irreversible';
+ effect?: 'read' | 'undoable' | 'journaled' | 'irreversible';
}
/** One call the model wants made. */
@@ -187,8 +187,16 @@ export interface AgentProvider {
* their language.
*/
export type ConfirmReason =
- /** Escapes the undo stack — a file, a project setting, an export. */
+ /** Leaves the open project, or builds something outside it — an export, a new
+ * project tree. Nothing holds a copy of what it changed. */
| 'irreversible'
+ /**
+ * Writes the project on disk with NO transaction open to catch it — no
+ * project, or a journal that could not start. Ordinarily this tier runs
+ * unasked because the turn's Revert takes the file back; when it cannot, the
+ * person is the only thing standing between the model and a file that stays.
+ */
+ | 'unjournaled'
/** Runs code the agent wrote, so its effect is whatever that code does. */
| 'arbitrary_code'
/**
@@ -256,11 +264,21 @@ export type AgentEvent =
| { 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 }
- /** The turn is over. `steps` is what a single Undo would take back — 0 is the
- * signal not to offer one — and `mark` is where it would take it back to. */
- /** `max_rounds` is its own ending because the work is UNFINISHED: reported as
- * an ordinary end_turn it would look like the agent had said its piece. */
- | { type: 'turn_end'; steps: number; mark: unknown; reason: 'end_turn' | 'aborted' | 'error' | 'refusal' | 'max_rounds' }
+ /**
+ * The turn is over, with both halves a revert has to undo: `mark`/`steps` is
+ * the document, `tx`/`files` the project on disk. So a turn that only wrote
+ * files reports 0 steps and a non-empty `files` rather than reading as having
+ * changed nothing. `max_rounds` is its own ending — the work is UNFINISHED.
+ */
+ | {
+ type: 'turn_end';
+ steps: number;
+ mark: unknown;
+ /** The file journal's transaction id, or null when none was open. */
+ tx: string | null;
+ files: readonly FileChange[];
+ reason: 'end_turn' | 'aborted' | 'error' | 'refusal' | 'max_rounds';
+ }
| { type: 'error'; message: string };
/** Everything the kernel needs from outside, so it runs under a test with none
@@ -281,6 +299,31 @@ export interface KernelDeps {
/** Ask the person. `no` is declined, which the model is told about. */
confirm(request: ConfirmRequest): Promise<ConfirmDecision>;
emit(event: AgentEvent): void;
+ /**
+ * The disk half of the turn's checkpoint (electron/fileJournal), absent with
+ * no project to scope one to. Passed in, not imported, so the kernel needs no
+ * filesystem and "is one open" is the transaction owner's to answer.
+ */
+ journal?: {
+ /** Open one around this turn; null when it could not be opened. */
+ begin(): string | null;
+ /** Close the open one. Its copies stay restorable until retention or a
+ * revert consumes them. */
+ end(): void;
+ /** What it captured, for the transcript and the revert offer. */
+ changes(id: string): readonly FileChange[];
+ };
+}
+
+/** One project path a turn wrote, as the transcript and the History panel show
+ * it. Mirrors electron/fileJournal's JournalChange — the kernel does not import
+ * that module, so the shape is restated rather than shared. */
+export interface FileChange {
+ path: string;
+ kind: 'add' | 'modify' | 'remove';
+ /** True when the revert cannot put this path back (it was past the journal's
+ * budget). Rendered, not hidden — see fileJournal. */
+ unjournaled: boolean;
}
export type { HistoryMark };
diff --git a/desktop/electron/fileJournal.ts b/desktop/electron/fileJournal.ts
index ce2b09006..e23267b5c 100644
--- a/desktop/electron/fileJournal.ts
+++ b/desktop/electron/fileJournal.ts
@@ -38,13 +38,10 @@ import { resolveInside } from './pathSandbox';
const HOLDING_DIR = path.join(tmpdir(), 'estella-agent-journal');
/**
- * How much of a project one transaction may hold onto.
- *
- * Sized for the thing this exists to make reversible — authoring: scripts,
- * scenes, prefabs, materials, a sprite or two. An `import_assets` that drags in
- * a video does not fit, and that is the case the partial report is for. Holding
- * gigabytes to make one import undoable would trade a rare convenience for a
- * disk nobody agreed to spend.
+ * How much of a project one transaction may hold onto. Sized for authoring —
+ * scripts, scenes, prefabs, a sprite or two. An import that drags in a video
+ * does not fit, which is the case the partial report exists for: holding
+ * gigabytes for one import spends a disk nobody agreed to.
*/
let budgetBytes = 256 * 1024 * 1024;
@@ -105,11 +102,9 @@ let active: Transaction | null = null;
/**
* Open a transaction and make it the one every write door captures into.
*
- * One at a time by design: the doors capture AMBIENTLY rather than being handed
- * a transaction id, which is what lets a write the agent caused indirectly — a
- * document the editor saved because a tool asked it to — land in the same
- * transaction as the tool call. Nested or concurrent transactions would make
- * "which one owns this write" unanswerable at the door.
+ * One at a time by design. Doors capture AMBIENTLY rather than being handed an
+ * id, which is what catches a write the agent caused indirectly; concurrent
+ * transactions would make "which owns this write" unanswerable at the door.
*/
export function beginTransaction(root: string): string {
if (active) endTransaction();
@@ -145,16 +140,11 @@ export function activeTransaction(): string | null {
export type Intent = 'write' | 'remove';
/**
- * Hold what `relPath` is right now, before the caller changes it.
- *
- * A no-op when no transaction is open — which is the ordinary case (a person
- * editing by hand), and the reason every write door can call this
- * unconditionally instead of asking first.
+ * Hold what `relPath` is right now, before the caller changes it. A no-op with
+ * no transaction open, which is why every door can call it unconditionally.
*
- * The door says what it INTENDS; whether that lands as an add or a modify is
- * the journal's to answer, because it is the side that has just looked at the
- * path. A door deciding for itself is a door that can be wrong about it, and
- * "created" vs "changed" is the whole of what the history entry claims.
+ * The door says what it INTENDS; add-vs-modify is answered here, by the side
+ * that has just looked at the path.
*/
export async function capture(relPath: string, intent: Intent): Promise<void> {
const tx = active;
@@ -237,15 +227,9 @@ export function isRestorable(id: string): boolean {
/**
* Put every captured path back, newest capture first, and say what happened.
- *
- * LIFO because captures within a transaction can depend on each other: creating
- * `Scripts/` then writing `Scripts/HP.ts` must come apart as delete-the-file
- * then delete-the-directory, and the reverse order leaves a directory that
- * refuses to go.
- *
- * A failure on one path does not stop the rest. The alternative — abandoning the
- * revert half way — leaves a project in a state neither the turn nor the user
- * asked for, and the report is the thing that lets someone finish by hand.
+ * LIFO because captures depend on each other: `Scripts/` then `Scripts/HP.ts`
+ * comes apart file-first. One failure does not stop the rest — a half-abandoned
+ * revert leaves a project nobody asked for, and this is what finishes it.
*/
export async function revert(id: string): Promise<RevertResult> {
const tx = transactions.get(id);
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 2d2565d61..935c87e35 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -771,6 +771,14 @@ const agentHost = createAgentHost({
void saveConversation(projectRoot, conversation)
.catch((e) => console.error('[agent] could not save the conversation:', e));
},
+ // The disk half of the turn's checkpoint. Null without a project: there is no
+ // root to scope the capture to, and the kernel then asks about each write
+ // rather than pretending one is held.
+ journal: {
+ begin: () => (projectRoot ? journal.beginTransaction(projectRoot) : null),
+ end: () => { journal.endTransaction(); },
+ changes: (id) => journal.changes(id),
+ },
});
ipcMain.handle('agent:status', () => agentHost.status());
ipcMain.handle('agent:transcript', () => agentHost.transcript());
diff --git a/desktop/shared/capabilityCatalog.mjs b/desktop/shared/capabilityCatalog.mjs
index 6eff3ec82..b8c32e896 100644
--- a/desktop/shared/capabilityCatalog.mjs
+++ b/desktop/shared/capabilityCatalog.mjs
@@ -36,8 +36,8 @@ const obj = (properties, required = []) => ({ type: 'object', properties, requir
* Every capability, in the order a model should meet them.
*
* `effect` follows the same tiers as tools and must be the WORST of the steps it
- * runs: a capability that writes a file is irreversible however undoable its
- * other steps are, because that is the one an undo cannot rescue.
+ * runs: a capability that writes a file is `journaled` however undoable its
+ * other steps are, because that is the one the undo stack does not reach.
*/
/** Where on the screen a HUD element sits, as insets from the edges it hugs. */
const HUD_ANCHORS = {
@@ -175,7 +175,7 @@ export const CAPABILITIES = [
{
name: 'create_prefab',
- effect: 'irreversible',
+ effect: 'journaled',
description:
'Build an entity subtree and extract it as a reusable `.esprefab` in one step — the whole point being that '
+ 'what you build once becomes an INSTANCE everywhere else (the scene stores a delta, not a copy). '
@@ -286,7 +286,7 @@ export const CAPABILITIES = [
{
name: 'create_behavior',
- effect: 'irreversible',
+ effect: 'journaled',
description:
'Author a gameplay behaviour and attach it. A behaviour is a component plus its update loop, and getting one into '
+ 'a project is three steps that each look complete on their own: create_script makes the file AND wires it into '
diff --git a/desktop/shared/toolCatalog.mjs b/desktop/shared/toolCatalog.mjs
index 5bbc6789d..496ae0796 100644
--- a/desktop/shared/toolCatalog.mjs
+++ b/desktop/shared/toolCatalog.mjs
@@ -28,17 +28,27 @@
* Editor-host tools fail with a pointer when called on the headless fixtures
* host.
*
- * Every tool declares an `effect`, and the tiers are drawn where UNDO STOPS
- * WORKING — which is what makes them actionable rather than decorative:
+ * Every tool declares an `effect`, and the tiers are drawn where GOING BACK
+ * STOPS WORKING — which is what makes them actionable rather than decorative:
*
* read observes only. Never gated, never confirmed.
* undoable mutates the document through EditorHistory. A built-in agent
* runs these freely: the turn is bracketed by a history
* checkpoint, so one Undo is the whole approval mechanism.
- * irreversible escapes the undo stack — writes a file, rewrites a project,
- * builds an export, or dispatches an arbitrary command. A
- * built-in agent must get explicit confirmation; undo cannot
- * rescue the user afterwards.
+ * journaled writes the project on disk, which the undo stack does not
+ * reach — but electron/fileJournal keeps the before-image, so
+ * the turn's Revert takes the file back with the scene. Runs
+ * unasked for the same reason `undoable` does.
+ * irreversible past both: it leaves the open project (a new project tree
+ * elsewhere), or it runs code whose effects nobody enumerated
+ * (an editor command, a probe evaluated in the running game).
+ * A built-in agent must get explicit confirmation.
+ *
+ * The line between the last two moved once already, and it is worth saying why.
+ * A file write was called irreversible for as long as nobody kept the bytes it
+ * overwrote — a property of the editor, not of writing files. Keeping them
+ * turned a dozen prompts per turn into none, which is most of what decides
+ * whether a person lets an agent build anything at all.
*
* A remote MCP client has no one to confirm with, so it keeps the coarser door
* it always had: anything past `read` is hidden AND refused unless the host sets
@@ -55,10 +65,14 @@ const obj = (properties, required = []) => ({ type: 'object', properties, requir
* when it genuinely is; every mutating entry below states its tier. */
export const mutates = (tool) => (tool.effect ?? 'read') !== 'read';
-/** Whether `tool` is past what an undo can revert — the in-editor agent's
- * confirmation gate. */
+/** Whether `tool` is past what a turn's Revert can take back — the in-editor
+ * agent's confirmation gate. `journaled` is NOT: its file writes come back. */
export const irreversible = (tool) => tool.effect === 'irreversible';
+/** Whether `tool` writes the project on disk, so a transaction has to be open
+ * around it for the turn's Revert to mean anything. */
+export const journaled = (tool) => tool.effect === 'journaled';
+
// Render the viewport to a base64 PNG. Runs in the renderer (needs document):
// captureViewport returns bottom-up GL rows, so flip Y into a 2D canvas first.
// Resolves the surface on either host (headless fixtures / live editor).
@@ -266,7 +280,7 @@ const ATOMS = [
+ 'REFUSES while the open scene has unsaved changes (opening reloads from disk, so anything just authored would be gone): save_scene first, or pass discardChanges to throw the edits away on purpose.',
schema: obj({ path: { type: 'string' }, discardChanges: { type: 'boolean' } }, ['path']),
method: 'openScene', args: (i) => [i.path, i.discardChanges === true], root: 'editor' },
- { name: 'save_scene', effect: 'irreversible',
+ { name: 'save_scene', effect: 'journaled',
description: 'Save the open DOCUMENT to disk (the toolbar Save) — the scene, or, in Prefab Mode, the prefab being edited (see get_document).',
schema: obj({}), method: 'save', args: () => [], root: 'editor' },
{ name: 'open_asset',
@@ -287,7 +301,7 @@ const ATOMS = [
description: 'Open the prefab an INSTANCE came from, in Prefab Mode (the Outliner\'s "Edit Prefab") — no ref→path lookup needed. Same refusals as open_asset.',
schema: obj({ entity: { type: 'number' }, discardChanges: { type: 'boolean' } }, ['entity']),
js: (i) => `window.__estellaEditor.editPrefab(${Number(i.entity)}, ${i.discardChanges === true})` },
- { name: 'apply_prefab', effect: 'irreversible',
+ { name: 'apply_prefab', effect: 'journaled',
description: 'Push an instance\'s overrides back into its prefab asset (the Outliner\'s "Apply to Prefab") — the base for EVERY instance is rewritten, and this instance\'s overrides clear. '
+ 'Property, name, visibility and component overrides plus structural add/remove. `confirm` must be true: a person is shown an itemized diff first, so a driver says it out loud instead (get_inspector marks the overridden fields).',
schema: obj({ entity: { type: 'number' }, confirm: { type: 'boolean' } }, ['entity', 'confirm']),
@@ -300,12 +314,12 @@ const ATOMS = [
description: 'Detach an instance (the Outliner\'s "Unpack Prefab"): its entities become ordinary scene entities and lose every prefab link, so later prefab edits no longer reach them. Undoable.',
schema: obj({ entity: { type: 'number' } }, ['entity']),
js: (i) => `window.__estellaEditor.unpackPrefab(${Number(i.entity)})` },
- { name: 'create_prefab_variant', effect: 'irreversible',
+ { name: 'create_prefab_variant', effect: 'journaled',
description: 'Save a new `.esprefab` that INHERITS the instance\'s prefab and bakes in its current overrides (the Outliner\'s "Create Variant" — a prefab of a prefab), then re-link the instance to the variant. '
+ 'Written beside the base as "<base> Variant.esprefab"; returns the re-linked root\'s id. Deletions are not representable in a variant and are skipped.',
schema: obj({ entity: { type: 'number' } }, ['entity']),
js: (i) => `window.__estellaEditor.createPrefabVariant(${Number(i.entity)})` },
- { name: 'create_scene_file', effect: 'irreversible',
+ { name: 'create_scene_file', effect: 'journaled',
description: 'Create a blank scene FILE under a project-relative directory (does not switch to it); returns its path, immediately referenceable (the registry refresh happens before this resolves). '
+ '`name` names it (the `.esscene` extension is added if absent); without one it is `scene.esscene`, which collides the moment you make a second.',
schema: obj({
@@ -314,7 +328,7 @@ const ATOMS = [
}, ['destDir']),
js: (i) => `window.__estellaEditor.createSceneFile(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.name ?? null)}, ${JSON.stringify({ overwrite: i.overwrite === true })})
.then((p) => window.__estellaEditor.refreshAssets().then(() => p))` },
- { name: 'create_prefab_from_entity', effect: 'irreversible',
+ { name: 'create_prefab_from_entity', effect: 'journaled',
description: 'Extract an entity and its subtree into a `.esprefab` asset under assets/prefabs/ (the Outliner\'s Create Prefab), named after the entity; returns its `@uuid:` ref. '
+ 'This is what makes a subtree REUSABLE: afterwards `list_entity_templates` offers it as `prefab:<path>`, and creating with that template makes a real INSTANCE — the scene stores a delta, not a copy, so editing the prefab updates every instance. '
+ 'Without it a driver can build the same panel chrome into twenty scenes but never share it. Refs pointing OUT of the subtree cannot live in a standalone prefab and are cleared.',
@@ -324,7 +338,7 @@ const ATOMS = [
}, ['entity']),
js: (i) => `window.__estellaEditor.createPrefabFromEntity(${Number(i.entity)}, ${JSON.stringify({ replace: i.replace === true })})
.then((ref) => { if (!ref) throw new Error('could not create a prefab from entity ${Number(i.entity)} — it may not exist'); return ref; })` },
- { name: 'create_script', effect: 'irreversible',
+ { name: 'create_script', effect: 'journaled',
description: "Create a project script the editor will actually LOAD. `kind`: 'component' — a declaration the editor "
+ "reads without running the game, which is what makes a component ADDABLE (add_component / apply_scene_ops) — or "
+ "'system', behaviour the play realm bundles and runs. It writes the module AND wires it into the project's "
@@ -335,7 +349,7 @@ const ATOMS = [
kind: { type: 'string' }, name: { type: 'string' }, dir: { type: 'string' },
}, ['kind', 'name']),
js: (i) => `window.estella.project.createScript(${JSON.stringify(i.kind)}, ${JSON.stringify(i.name)}, ${JSON.stringify(i.dir ?? undefined)})` },
- { name: 'create_asset', effect: 'irreversible',
+ { name: 'create_asset', effect: 'journaled',
description: 'Create a text asset file under a project-relative directory with the given content. `type` is the meta vocabulary: scene, prefab, shader (.esshader), material (.esmaterial), materialgraph (.esmatgraph), animclip (.esanim), animation (.estimeline), tileset, statemachine (.esfsm), behaviortree (.esbt), locale, inputmap, tilemap (.tmj). A bare baseName gets the type\'s canonical extension appended. Returns the project-relative path, immediately referenceable (the registry refresh happens before this resolves). '
+ 'A material graph is the ONE type whose file is not the whole asset: it compiles to a sibling `.esshader`, which is written by save_asset_document — so create it, open_asset it, and save it, rather than leaving a graph with no shader beside it.',
schema: obj({
@@ -344,13 +358,13 @@ const ATOMS = [
}, ['destDir', 'baseName', 'content', 'type']),
js: (i) => `window.estella.project.createAsset(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.baseName)}, ${JSON.stringify(i.content)}, ${JSON.stringify(i.type)})
.then((p) => window.__estellaEditor.refreshAssets().then(() => p))` },
- { name: 'delete_asset', effect: 'irreversible',
+ { name: 'delete_asset', effect: 'journaled',
description: 'Delete a project file (or folder) to the OS trash — its `.meta` goes with it and the registry is re-scanned, so nothing is left half-removed. '
+ 'This is how you take back an asset you created by mistake: the editor command behind the Content Browser\'s Delete acts on whatever is SELECTED there, which a driver cannot see. '
+ 'Returns { path, type, restoreToken, usages } — `usages` is what still REFERENCES the asset (scenes, prefabs, materials); a non-empty list means you just left those refs dangling, and get_diagnostics will now report them. Recoverable from the OS trash.',
schema: obj({ path: { type: 'string' } }, ['path']),
js: (i) => `window.__estellaEditor.deleteAsset(${JSON.stringify(i.path)})`, root: 'editor' },
- { name: 'import_assets', effect: 'irreversible',
+ { name: 'import_assets', effect: 'journaled',
description: 'Import files into the asset registry (textures, audio, fonts, spine, tilemaps...). External absolute paths are copied into project-relative destDir; paths already INSIDE the project are registered in place (no copy, no rename). Returns { imported, skipped }; imported paths are immediately referenceable (the registry refresh happens before this resolves).',
schema: obj({ destDir: { type: 'string' }, sources: { type: 'object', description: 'array of absolute file paths' } },
['destDir', 'sources']),
@@ -404,7 +418,7 @@ const ATOMS = [
}, ['changes']),
js: (i) => `window.__estellaEditor.editAssetDocument(${JSON.stringify(i.changes)}, ${JSON.stringify(i.docId ?? null)} ?? undefined, ${JSON.stringify(i.label ?? null)} ?? undefined)`,
root: 'editor' },
- { name: 'save_asset_document', effect: 'irreversible',
+ { name: 'save_asset_document', effect: 'journaled',
description: 'Write an open asset editor\'s document to its file — the save its own panel performs, which for a MATERIAL GRAPH also recompiles the sibling `.esshader` every material on it reads. '
+ 'This is the save for these files: `save_scene` writes the scene, and writing the bytes yourself with write_project_file skips the serializer (and, for a graph, leaves the shader stale — the edit appears to save and still renders the old thing). '
+ 'Omit `docId` when only one is open. Returns { saved } — false means it was already clean, not that it failed.',
@@ -450,7 +464,7 @@ const ATOMS = [
description: "An asset's .meta import settings, layered over its type's defaults — the Import Settings panel's data. Returns { type, settings }.",
schema: obj({ path: { type: 'string' } }, ['path']),
method: 'getImportSettings', args: (i) => [i.path], root: 'editor' },
- { name: 'set_import_settings', effect: 'irreversible',
+ { name: 'set_import_settings', effect: 'journaled',
description: 'Patch an asset\'s .meta import settings and persist. Keys are DOTTED paths into the importer block, matching the inspector field keys — a texture\'s 9-slice border is '
+ '{"sliceBorder.left":12,"sliceBorder.right":12,"sliceBorder.top":12,"sliceBorder.bottom":12}; filter/wrap are {"filterMode":"nearest","wrapMode":"clamp"}. '
+ 'These live in IMPORT, not on a component: a UIVisual set to NineSlice takes its border from texture metadata, so this is what makes frames and buttons stretch correctly. '
@@ -463,7 +477,7 @@ const ATOMS = [
+ 'An offset past the end is refused, naming the line count — so an empty reply always means those lines are empty, never that you have run off the end.',
schema: obj({ path: { type: 'string' }, offset: { type: 'number' }, limit: { type: 'number' } }, ['path']),
js: (i) => `window.estella.fs.read(${JSON.stringify(i.path)}, ${i.offset ?? 'undefined'}, ${i.limit ?? 'undefined'})` },
- { name: 'write_project_file', effect: 'irreversible',
+ { name: 'write_project_file', effect: 'journaled',
description: 'Write a text file by project-relative path, CREATING or OVERWRITING it. This is how game scripts (src/*.ts) are authored — create_asset only makes .meta-carrying asset types and refuses to overwrite (it uniquifies to "name 2"). '
+ 'Writing project sources does not itself rebuild them; the editor picks the change up through its file watcher. '
+ 'Writing a .ts file returns the TypeScript errors in it — `{ ok, path, errors, diagnostics }` — so a script that does not compile says so HERE, not three steps later when the game plays black.',
@@ -491,7 +505,7 @@ const ATOMS = [
description: 'Project-relative paths of every file under a project-relative directory (recursive). Use for source trees (src/) where list_assets — which only knows registered assets — sees nothing.',
schema: obj({ dir: { type: 'string' } }, ['dir']),
js: (i) => `window.estella.fs.listFiles(${JSON.stringify(i.dir)})` },
- { name: 'set_project_physics', effect: 'irreversible',
+ { name: 'set_project_physics', effect: 'journaled',
description: 'Patch the project physics feature (Project Settings → Physics), e.g. { "enabled": true }. Persists to the manifest; Play and exports boot it.',
schema: obj({ patch: { type: 'object' } }, ['patch']),
method: 'setPhysics', args: (i) => [i.patch], root: 'editor' },
diff --git a/desktop/src/components/AgentDrawer.tsx b/desktop/src/components/AgentDrawer.tsx
index 86db97f4d..1645f3271 100644
--- a/desktop/src/components/AgentDrawer.tsx
+++ b/desktop/src/components/AgentDrawer.tsx
@@ -26,7 +26,7 @@
import { memo, useCallback, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
import {
X, Plus, PanelRight, ArrowUp, Square, ChevronRight, ChevronDown, Check, TriangleAlert,
- Loader, Copy, Pencil, Eye, KeyRound, Boxes, Stethoscope, Image as ImageIcon, ImageOff, RotateCcw,
+ Loader, Copy, Pencil, Eye, FileText, KeyRound, Boxes, Stethoscope, Image as ImageIcon, ImageOff, RotateCcw,
File as FileIcon, ArrowRight, History as HistoryIcon, Trash2, FoldVertical,
} from 'lucide-react';
import { useEditorStore } from '@/store/editorStore';
@@ -94,9 +94,13 @@ function askKeys(
*/
const ASKING = 'ag-asking';
+// A journaled call gets its own glyph: it reached the DISK, which is what a
+// reader scanning the transcript picks out, and the turn's Revert covers it,
+// which is why it is not the amber warning.
const TOOL_ICON: Record<string, typeof Eye> = {
read: Eye,
undoable: Pencil,
+ journaled: FileText,
irreversible: TriangleAlert,
};
diff --git a/desktop/src/i18n/messages/agent.ts b/desktop/src/i18n/messages/agent.ts
index 65d101335..feacbd431 100644
--- a/desktop/src/i18n/messages/agent.ts
+++ b/desktop/src/i18n/messages/agent.ts
@@ -163,8 +163,12 @@ export const agentMessages = defineMessages({
// — 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: '它会写到场景之外,撤销收不回来。',
+ en: 'It goes outside this project, and the run\'s Revert cannot take it back.',
+ zh: '它会动到本项目之外,这一轮的「撤销 Agent 改动」收不回来。',
+ },
+ 'agent.confirm.why.unjournaled': {
+ en: 'It writes a project file, and with no project open nothing is holding what it overwrites.',
+ zh: '它会写项目文件,而当前没有打开项目,没人替你留着被覆盖的内容。',
},
'agent.confirm.why.arbitrary_code': {
en: 'It runs code the agent wrote, so its effect is whatever that code does.',
diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.ts
index c4cd9b4f0..b6ba60769 100644
--- a/desktop/src/store/AgentStore.ts
+++ b/desktop/src/store/AgentStore.ts
@@ -18,7 +18,9 @@
*/
import { create } from 'zustand';
import type { AgentStatus, AgentMessage } from '../../electron/agent/host';
-import type { AgentEvent, ConfirmAnswer, ConfirmReason, ConfirmRequest } from '../../electron/agent/types';
+import type {
+ AgentEvent, ConfirmAnswer, ConfirmReason, ConfirmRequest, FileChange,
+} from '../../electron/agent/types';
import {
agentProviders, agentProvider, agentKeyId, parseModelList, protocolOf,
modelsSettingId, DEFAULT_CONTEXT_WINDOW, type AgentProviderDef,
@@ -32,7 +34,7 @@ import { t } from '@/i18n';
export type { AgentStatus, AgentEvent };
-export type AgentEffect = 'read' | 'undoable' | 'irreversible';
+export type AgentEffect = 'read' | 'undoable' | 'journaled' | 'irreversible';
/**
* Where a call is. `queued` is the model having asked for it while an earlier
@@ -138,6 +140,14 @@ export interface AgentTurn {
steps: number;
/** Where that Undo would go back to (EditorHistory.undoToMark). */
mark: unknown | null;
+ /**
+ * The turn's file-journal transaction and the project paths it captured — the
+ * other half of what a revert takes back. A turn that only wrote files ends
+ * with `steps: 0` and a non-empty `files`, and a checkpoint reading steps
+ * alone would offer nothing for it.
+ */
+ tx: string | null;
+ files: readonly FileChange[];
/** null while the turn is still running. */
reason: TurnReason | null;
/** Wall clock, stamped here rather than in main: it is what the person waited,
@@ -453,6 +463,8 @@ export function applyAgentEvent(turns: readonly AgentTurn[], event: AgentEvent):
context: null,
steps: 0,
mark: null,
+ tx: null,
+ files: [],
reason: null,
startedAt: Date.now(),
endedAt: null,
@@ -545,6 +557,8 @@ export function applyAgentEvent(turns: readonly AgentTurn[], event: AgentEvent):
reason: event.reason,
steps: event.steps,
mark: event.mark,
+ tx: event.tx,
+ files: event.files,
endedAt: Date.now(),
// Nothing will report on these now. Neither failed nor succeeded.
entries: closeProse(open.entries).map((e) =>
diff --git a/desktop/src/theme/agent.css b/desktop/src/theme/agent.css
index ef592550b..cc8e19dd2 100644
--- a/desktop/src/theme/agent.css
+++ b/desktop/src/theme/agent.css
@@ -284,10 +284,12 @@
.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); }
-/* The glyph says what KIND of call it is — reading, writing, or the one that
- cannot be taken back. Success is not a colour: it is the result in `out`, and
- tinting every finished row green makes the rows that matter harder to find. */
+/* The glyph says what KIND of call it is, on one ramp: a scene edit, a write
+ that reached the disk, and the one that cannot be taken back. Success is not
+ a colour — it is the result in `out`, and tinting every finished row green
+ makes the rows that matter harder to find. */
.ag-call-e--undoable .ag-call-g { color: var(--text-dim); }
+.ag-call-e--journaled .ag-call-g { color: var(--text); }
.ag-call-e--irreversible .ag-call-g { color: var(--warn); }
.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); }
diff --git a/desktop/tests/agent-host.test.ts b/desktop/tests/agent-host.test.ts
index bd50e67f2..2bab6f877 100644
--- a/desktop/tests/agent-host.test.ts
+++ b/desktop/tests/agent-host.test.ts
@@ -393,7 +393,7 @@ describe('a conversation that outlives the session', () => {
endpoint: 'fake',
events: [
{ type: 'turn_start', prompt: 'yesterday', model: 'fake-model', index: 0 },
- { type: 'turn_end', steps: 0, mark: null, reason: 'end_turn' },
+ { type: 'turn_end', steps: 0, mark: null, tx: null, files: [], reason: 'end_turn' },
],
memory: { asked: ['yesterday'] },
};
diff --git a/desktop/tests/agent-kernel.test.ts b/desktop/tests/agent-kernel.test.ts
index 69452e5bc..61ad477cc 100644
--- a/desktop/tests/agent-kernel.test.ts
+++ b/desktop/tests/agent-kernel.test.ts
@@ -8,7 +8,9 @@
*/
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { runTurn } from '../electron/agent/kernel';
-import type { AgentEvent, AgentSession, StepEvent, ToolCall, ToolOutcome } from '../electron/agent/types';
+import type {
+ AgentEvent, AgentSession, FileChange, StepEvent, ToolCall, ToolOutcome,
+} from '../electron/agent/types';
/** A provider that replays scripted steps and records what it was told. */
function fakeSession(steps: StepEvent[][]): AgentSession & {
@@ -40,6 +42,16 @@ const asks = (...calls: ToolCall[]): StepEvent[] =>
[...calls.map((c) => ({ type: 'tool_call' as const, call: c })), { type: 'stop' as const, reason: 'tool_use' as const }];
const ends = (): StepEvent[] => [{ type: 'stop', reason: 'end_turn' }];
+/** The disk half of the checkpoint, without a disk. `changes` answers whatever
+ * it was built with, since what the journal captured is main's business. */
+function fakeJournal(files: FileChange[] = []) {
+ return {
+ begin: vi.fn((): string | null => 'tx-1'),
+ end: vi.fn(),
+ changes: vi.fn((): readonly FileChange[] => files),
+ };
+}
+
describe('the agent turn', () => {
let events: AgentEvent[];
let confirm: ReturnType<typeof vi.fn>;
@@ -78,7 +90,9 @@ describe('the agent turn', () => {
// 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', model: 'fake-model', index: 0 });
- expect(events.at(-1)).toEqual({ type: 'turn_end', steps: 3, mark: { seq: 7 }, reason: 'end_turn' });
+ expect(events.at(-1)).toEqual({
+ type: 'turn_end', steps: 3, mark: { seq: 7 }, tx: null, files: [], reason: 'end_turn',
+ });
});
// The provider announces a call while the model writes its arguments, and
@@ -104,14 +118,83 @@ describe('the agent turn', () => {
expect(kinds()).toContain('tool_end');
});
- it('asks before anything Undo cannot take back', async () => {
- const s = fakeSession([asks(call('save_scene')), ends()]);
- await runTurn(deps(s), 'save it', null, new AbortController().signal);
+ it('asks before anything the turn cannot take back', async () => {
+ const s = fakeSession([asks(call('run_editor_command', { id: 'x' })), ends()]);
+ await runTurn(deps(s), 'do it', null, new AbortController().signal);
expect(confirm).toHaveBeenCalledTimes(1);
- expect(confirm.mock.calls[0][0]).toMatchObject({ tool: 'save_scene' });
+ expect(confirm.mock.calls[0][0]).toMatchObject({ tool: 'run_editor_command', reason: 'arbitrary_code' });
expect(kinds()).toContain('awaiting_confirm');
});
+ // The tier makes a file write ordinary, and only earns that while something
+ // holds the bytes. Both halves are asserted: a gate reading the tier alone
+ // waves the write through in exactly the case the tier does not cover.
+ describe('a write that reaches the disk', () => {
+ it('runs unasked while a transaction is open to catch it', async () => {
+ const journal = fakeJournal();
+ const s = fakeSession([asks(call('save_scene')), ends()]);
+ await runTurn({ ...deps(s), journal }, 'save it', null, new AbortController().signal);
+ expect(confirm).not.toHaveBeenCalled();
+ // The DISPATCH, not the `tool_start` — that is emitted before the gate, so
+ // it would be there for a call the person had declined.
+ expect(driver).toHaveBeenCalledWith('save', [], 'editor');
+ });
+
+ it('is confirmed when there is no transaction — nothing would hold it', async () => {
+ const s = fakeSession([asks(call('save_scene')), ends()]);
+ await runTurn(deps(s), 'save it', null, new AbortController().signal);
+ expect(confirm).toHaveBeenCalledTimes(1);
+ expect(confirm.mock.calls[0][0]).toMatchObject({ tool: 'save_scene', reason: 'unjournaled' });
+ });
+
+ it('is confirmed when the journal could not open one', async () => {
+ const journal = fakeJournal();
+ journal.begin.mockReturnValue(null);
+ const s = fakeSession([asks(call('save_scene')), ends()]);
+ await runTurn({ ...deps(s), journal }, 'save it', null, new AbortController().signal);
+ expect(confirm).toHaveBeenCalledTimes(1);
+ expect(confirm.mock.calls[0][0]).toMatchObject({ reason: 'unjournaled' });
+ });
+
+ // Closed exactly once, and before the turn is reported: a transaction left
+ // open would keep capturing the user's own edits into a checkpoint labelled
+ // with the model's prompt.
+ it('closes the transaction when the turn ends', async () => {
+ const journal = fakeJournal();
+ const s = fakeSession([asks(call('save_scene')), ends()]);
+ await runTurn({ ...deps(s), journal }, 'save it', null, new AbortController().signal);
+ expect(journal.begin).toHaveBeenCalledTimes(1);
+ expect(journal.end).toHaveBeenCalledTimes(1);
+ });
+
+ it('closes it even when the turn errored', async () => {
+ const journal = fakeJournal();
+ const s = fakeSession([]);
+ s.step = async function* () { throw new Error('gateway closed'); };
+ await runTurn({ ...deps(s), journal }, 'save it', null, new AbortController().signal);
+ expect(journal.end).toHaveBeenCalledTimes(1);
+ expect(events.at(-1)).toMatchObject({ type: 'turn_end', reason: 'error' });
+ });
+
+ // A turn that only wrote files ends with 0 undo steps. Reported with the
+ // files it wrote, so the checkpoint can still offer a revert instead of
+ // reading the turn as having changed nothing.
+ it('reports the files it wrote alongside the undo steps', async () => {
+ const journal = fakeJournal([{ path: 'src/HP.ts', kind: 'add', unjournaled: false }]);
+ stepsSince = 0;
+ const s = fakeSession([asks(call('save_scene')), ends()]);
+ const out = await runTurn({ ...deps(s), journal }, 'save it', null, new AbortController().signal);
+
+ expect(out.tx).toBe('tx-1');
+ expect(events.at(-1)).toMatchObject({
+ type: 'turn_end',
+ steps: 0,
+ tx: 'tx-1',
+ files: [{ path: 'src/HP.ts', kind: 'add', unjournaled: false }],
+ });
+ });
+ });
+
it('a decline is told to the model, not raised as a failure', async () => {
confirm.mockResolvedValue({ answer: 'no' });
const s = fakeSession([asks(call('export_game', { platform: 'web' })), ends()]);
diff --git a/desktop/tests/agent-queue.test.ts b/desktop/tests/agent-queue.test.ts
index 7ed7ddc95..b1bbceee7 100644
--- a/desktop/tests/agent-queue.test.ts
+++ b/desktop/tests/agent-queue.test.ts
@@ -114,7 +114,7 @@ describe('messages typed while a turn runs', () => {
describe('asking a run again', () => {
const turn = (id: number, prompt: string) => ({
id, prompt, model: 'm', entries: [], inputTokens: 0, outputTokens: 0, context: null,
- steps: 0, mark: null, reason: 'end_turn' as const, startedAt: 0, endedAt: 1,
+ steps: 0, mark: null, tx: null, files: [], reason: 'end_turn' as const, startedAt: 0, endedAt: 1,
});
beforeEach(() => {
diff --git a/desktop/tests/agent-replay.test.ts b/desktop/tests/agent-replay.test.ts
index cbd52e2bc..97bb9e7a6 100644
--- a/desktop/tests/agent-replay.test.ts
+++ b/desktop/tests/agent-replay.test.ts
@@ -21,10 +21,10 @@ const status: AgentStatus =
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_end', steps: 7, mark: { seq: 1 }, tx: null, files: [], 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' },
+ { type: 'turn_end', steps: 3, mark: { seq: 2 }, tx: null, files: [], reason: 'end_turn' },
];
let transcript: AgentEvent[];
diff --git a/desktop/tests/agent-store.test.ts b/desktop/tests/agent-store.test.ts
index 6114b3a71..0692d7f4d 100644
--- a/desktop/tests/agent-store.test.ts
+++ b/desktop/tests/agent-store.test.ts
@@ -21,7 +21,7 @@ afterEach(async () => { await rm(root, { recursive: true, force: true }); });
const turn = (index: number, prompt: string): AgentEvent[] => [
{ type: 'turn_start', prompt, model: 'fake-model', index },
{ type: 'text', delta: 'sure' },
- { type: 'turn_end', steps: 1, mark: { seq: index }, reason: 'end_turn' },
+ { type: 'turn_end', steps: 1, mark: { seq: index }, tx: null, files: [], reason: 'end_turn' },
];
const conversation = (over: Partial<Parameters<typeof saveConversation>[1]> = {}) => ({
@@ -63,7 +63,7 @@ describe('keeping a conversation', () => {
const withShot: AgentEvent[] = [
{ type: 'turn_start', prompt: 'look', model: 'm', index: 0 },
{ type: 'tool_end', id: 'c1', ok: true, summary: 'screenshot attached', image: 'data:image/png;base64,AAAA' },
- { type: 'turn_end', steps: 0, mark: null, reason: 'end_turn' },
+ { type: 'turn_end', steps: 0, mark: null, tx: null, files: [], reason: 'end_turn' },
];
await saveConversation(root, conversation({ events: withShot }));
const back = await loadConversation(root, 'abc-123');
diff --git a/desktop/tests/agent-transcript.test.ts b/desktop/tests/agent-transcript.test.ts
index 0625d9e7d..84d43c28f 100644
--- a/desktop/tests/agent-transcript.test.ts
+++ b/desktop/tests/agent-transcript.test.ts
@@ -20,7 +20,7 @@ const fold = (...events: AgentEvent[]): AgentTurn[] =>
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 });
+ ({ type: 'turn_end', steps: 0, mark: null, tx: null, files: [], reason: 'end_turn', ...over });
const call = (name: string): ToolCall => ({ id: `c-${name}`, name, input: { a: 1 } });
const tools = (t: AgentTurn): AgentToolEntry[] => t.entries.filter((e): e is AgentToolEntry => e.kind === 'tool');
@@ -300,7 +300,7 @@ describe('which entities a turn touched', () => {
});
const turn = (entries: AgentToolEntry[], id = 0): AgentTurn => ({
id, prompt: 'p', model: 'opus-5', entries, inputTokens: 0, outputTokens: 0, context: null,
- steps: 1, mark: { seq: 1 }, reason: 'end_turn', startedAt: 0, endedAt: 1,
+ steps: 1, mark: { seq: 1 }, tx: null, files: [], reason: 'end_turn', startedAt: 0, endedAt: 1,
});
it('reads the ids out of the argument names the catalog uses', () => {
diff --git a/desktop/tests/capabilities.test.ts b/desktop/tests/capabilities.test.ts
index 746b00efb..3b8feb71d 100644
--- a/desktop/tests/capabilities.test.ts
+++ b/desktop/tests/capabilities.test.ts
@@ -63,7 +63,7 @@ describe('the capability catalog', () => {
});
it('declares an effect no gentler than the steps it runs', () => {
- const severity: Record<string, number> = { read: 0, undoable: 1, irreversible: 2 };
+ const severity: Record<string, number> = { read: 0, undoable: 1, journaled: 2, irreversible: 3 };
const byName = new Map((ATOMS as Tool[]).map((t) => [t.name, t]));
for (const { name, effect, steps } of capabilityStepNames() as Array<{ name: string; effect: string; steps: string[] }>) {
for (const step of steps) {
diff --git a/tools/check-capabilities.mjs b/tools/check-capabilities.mjs
index ecc2cfa6d..f5cc38d29 100644
--- a/tools/check-capabilities.mjs
+++ b/tools/check-capabilities.mjs
@@ -18,10 +18,12 @@
* already half-built something.
*
* A capability's declared `effect` must be no gentler than its steps'. The tiers
- * are drawn where undo stops working, and the built-in agent confirms exactly
- * the irreversible ones. A capability that runs `create_script` while calling
- * itself `undoable` walks a model straight past that prompt, and the file it
- * wrote is not coming back.
+ * are drawn where going back stops working, and each one buys a different
+ * safety net: `undoable` is covered by the history checkpoint, `journaled` by
+ * the file journal, `irreversible` by nothing but the confirmation prompt. A
+ * capability that runs `create_script` while calling itself `undoable` claims a
+ * net that does not hold it — the turn's Revert would take the scene back and
+ * leave the file.
*/
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -34,7 +36,7 @@ const { CAPABILITIES, capabilityStepNames } = await import(
pathToFileURL(path.join(SHARED, 'capabilityCatalog.mjs')).href
);
-const SEVERITY = { read: 0, undoable: 1, irreversible: 2 };
+const SEVERITY = { read: 0, undoable: 1, journaled: 2, irreversible: 3 };
const atomByName = new Map(ATOMS.map((t) => [t.name, t]));
const problems = [];