A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(agent): a tier for the writes something is holding
esengine05c4f780bf05
diff --git a/desktop/electron/agent/host.ts b/desktop/electron/agent/host.tsindex 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 conversationdiff --git a/desktop/electron/agent/kernel.ts b/desktop/electron/agent/kernel.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.mjsindex 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.tsxindex 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.tsindex 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.tsindex 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.cssindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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 = [];