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): claims the project makes, which no run can weaken

esengine4b9fac81bacd
diff --git a/desktop/electron/agent/acceptance.ts b/desktop/electron/agent/acceptance.ts
index 6d18a2442..7e76abb14 100644
--- a/desktop/electron/agent/acceptance.ts
+++ b/desktop/electron/agent/acceptance.ts
@@ -16,28 +16,45 @@
* criterion with neither is refused rather than recorded as passing.
*/
import type { KernelDeps } from './types';
+import type { AcceptanceCriterion } from '../../src/project/format';
-/** One claim about the finished work, and the thing that settles it. */
-export interface Criterion {
- /** What is claimed, in the words the user would use. */
- says: string;
- /** A JS expression evaluated in the RUNNING game; truthy means it held. */
- probe?: string;
- /** Only a person can settle this one. Says why a machine cannot. */
- manual?: string;
-}
+/**
+ * One claim, and the thing that settles it. The project's standing claims are
+ * the same shape (see {@link AcceptanceCriterion}) — one vocabulary, two owners.
+ */
+export type Criterion = AcceptanceCriterion;
+
+/**
+ * Who the claim belongs to, which is what decides whether it can PASS a turn.
+ *
+ * Only `turn` can: the editor's checks and the project's standing claims say
+ * the game is not broken, and a game that is not broken is not a turn that did
+ * something. Both of the others can still fail one.
+ */
+export type CriterionOwner = 'editor' | 'project' | 'turn';
-/** What became of one criterion. `unsettled` is neither pass nor fail: nothing
- * was in a position to answer it. */
-export interface CriterionResult {
- says: string;
+/**
+ * A criterion and what became of it. It carries the claim WHOLE — the probe
+ * included — because a reader wants to know what was actually checked, and
+ * because keeping one means writing it into the project as it stands.
+ * `unsettled` is neither pass nor fail: nothing was in a position to answer it.
+ */
+export interface CriterionResult extends Criterion {
state: 'held' | 'broke' | 'unsettled';
/** What it answered, or why nothing could answer it. */
detail?: string;
- /** The editor's own checks, which no turn declares — see {@link FLOOR}. */
- floor?: boolean;
+ owner: CriterionOwner;
+ /**
+ * Which of the editor's own checks this is. A CODE, not a sentence, for the
+ * reason ConfirmReason is: the editor renders the words, because it is the
+ * side that knows the reader's language. `says` stays the English the MODEL
+ * reads. Absent on anything a person or a turn wrote.
+ */
+ check?: EditorCheck;
}
+export type EditorCheck = 'diagnostics' | 'scripts';
+
/**
* `failed` — something the turn claimed, or the editor itself, did not hold.
* `passed` — every claim that could be settled held, and at least one was.
@@ -84,22 +101,20 @@ export function criteriaProblem(criteria: unknown): string | null {
}
/**
- * What the editor checks whatever the turn claims. It can only ever FAIL a
- * turn: a project with nothing wrong is not a project where the work happened,
- * so a passing floor never counts towards a verdict.
+ * Run every claim over the work and say what became of it: the editor's own
+ * checks, the project's standing claims, and the ones this turn declared.
*/
-const FLOOR = 'floor';
-
-/** Run every criterion and say what became of the work. */
export async function evaluate(
deps: KernelDeps,
criteria: readonly Criterion[],
): Promise<Acceptance> {
+ const standing = deps.standing?.() ?? [];
const results: CriterionResult[] = [
...await editorChecks(deps),
- ...await declaredChecks(deps, criteria),
+ ...await declaredChecks(deps, standing, 'project'),
+ ...await declaredChecks(deps, criteria, 'turn'),
];
- const claims = results.filter((r) => !r.floor);
+ const claims = results.filter((r) => r.owner === 'turn');
const verdict: Verdict = results.some((r) => r.state === 'broke') ? 'failed'
: claims.some((r) => r.state === 'held') ? 'passed'
: 'unverified';
@@ -115,11 +130,12 @@ async function editorChecks(deps: KernelDeps): Promise<CriterionResult[]> {
}>;
const errors = issues.filter((i) => i.problem !== 'notice');
out.push(errors.length === 0
- ? { says: 'the editor flags nothing in the scene', state: 'held', floor: true }
+ ? { says: 'the editor flags nothing in the scene', state: 'held', owner: 'editor', check: 'diagnostics' }
: {
says: 'the editor flags nothing in the scene',
state: 'broke',
- floor: true,
+ owner: 'editor',
+ check: 'diagnostics',
detail: errors.slice(0, 6).map((i) => `${i.entityName}: ${i.detail}`).join('; '),
});
} catch {
@@ -132,11 +148,12 @@ async function editorChecks(deps: KernelDeps): Promise<CriterionResult[]> {
};
const errors = (res?.diagnostics ?? []).filter((d) => d.category !== 'warning');
out.push(errors.length === 0
- ? { says: "the project's scripts compile", state: 'held', floor: true }
+ ? { says: "the project's scripts compile", state: 'held', owner: 'editor', check: 'scripts' }
: {
says: "the project's scripts compile",
state: 'broke',
- floor: true,
+ owner: 'editor',
+ check: 'scripts',
detail: errors.slice(0, 6).map((d) => `${d.file}:${d.line} ${d.message}`).join('; '),
});
} catch {
@@ -148,6 +165,7 @@ async function editorChecks(deps: KernelDeps): Promise<CriterionResult[]> {
async function declaredChecks(
deps: KernelDeps,
criteria: readonly Criterion[],
+ owner: CriterionOwner,
): Promise<CriterionResult[]> {
if (criteria.length === 0) return [];
const probes = criteria.filter((c) => c.probe);
@@ -159,14 +177,14 @@ async function declaredChecks(
const out: CriterionResult[] = [];
for (const c of criteria) {
if (c.manual) {
- out.push({ says: c.says, state: 'unsettled', detail: `only a person can settle this: ${c.manual}` });
+ out.push({ ...c, state: 'unsettled', owner, detail: `only a person can settle this: ${c.manual}` });
continue;
}
if (!playing) {
- out.push({ says: c.says, state: 'unsettled', detail: 'the game was not running, so nothing could answer this' });
+ out.push({ ...c, state: 'unsettled', owner, detail: 'the game was not running, so nothing could answer this' });
continue;
}
- out.push(await runProbe(deps, c));
+ out.push(await runProbe(deps, c, owner));
}
return out;
}
@@ -185,15 +203,19 @@ async function isPlaying(deps: KernelDeps): Promise<boolean> {
* holding. The value is reported either way — "it broke" that cannot say what it
* got is a verdict nobody can act on.
*/
-async function runProbe(deps: KernelDeps, c: Criterion): Promise<CriterionResult> {
+async function runProbe(
+ deps: KernelDeps,
+ c: Criterion,
+ owner: CriterionOwner,
+): Promise<CriterionResult> {
try {
const value = await deps.driver.op('play_probe', { code: c.probe });
const answered = unwrap(value);
return answered
- ? { says: c.says, state: 'held' }
- : { says: c.says, state: 'broke', detail: `the probe answered ${brief(answered ?? value)}` };
+ ? { ...c, state: 'held', owner }
+ : { ...c, state: 'broke', owner, detail: `the probe answered ${brief(answered ?? value)}` };
} catch (e) {
- return { says: c.says, state: 'broke', detail: (e as Error)?.message ?? String(e) };
+ return { ...c, state: 'broke', owner, detail: (e as Error)?.message ?? String(e) };
}
}
diff --git a/desktop/electron/agent/host.ts b/desktop/electron/agent/host.ts
index ac4b01343..b1ce1f747 100644
--- a/desktop/electron/agent/host.ts
+++ b/desktop/electron/agent/host.ts
@@ -85,6 +85,9 @@ export interface AgentHostDeps {
* construction would be the empty one, since plugins load after main does.
*/
contributedTools?(): readonly ContributedTool[];
+ /** The PROJECT's standing acceptance claims, which every turn is measured
+ * against on top of whatever it declared for itself. */
+ standing?: KernelDeps['standing'];
/** 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'];
@@ -344,7 +347,8 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
await runTurn(
{
driver: deps.driver, session: session!, model: model ?? '',
- acceptsImages, confirm, emit, journal: deps.journal,
+ acceptsImages, confirm, emit,
+ standing: deps.standing, journal: deps.journal,
},
text,
context,
diff --git a/desktop/electron/agent/prompt.ts b/desktop/electron/agent/prompt.ts
index 5513fbf4e..778e5e6b5 100644
--- a/desktop/electron/agent/prompt.ts
+++ b/desktop/electron/agent/prompt.ts
@@ -27,6 +27,7 @@ How work lands here:
- What still stops to ask is what the checkpoint does not reach: making a project somewhere else, building an export, running code you wrote (run_editor_command, play_probe). If the user declines, do not retry: work around it, or say what you need and why.
- Do not treat that safety net as licence to be careless. It puts the project back, not the user's attention — a turn they have to take back has cost them the time they spent reading it.
- Before your first write, say what would prove the work done: \`done_when\` with a few criteria, each naming the thing that settles it — \`probe\`, an expression evaluated in the running game that is true when the claim holds, or \`manual\` for something only a person can judge, saying why. A claim nothing can check is refused. This is the ONE part of the turn you do not grade: the editor runs them at the end and reports the verdict, and it is what the user reads instead of your closing paragraph. Declare it first — criteria written after the work are shaped by whatever you happened to build, and the tool refuses them once you have changed something.
+- The project may already make claims of its OWN (its manifest's \`acceptance\`), kept there by the user. Every turn is measured against them and you cannot add to, weaken or remove one — breaking a standing claim fails your turn no matter how well your own did. Read them (read_project_file on project.esproject) before you change anything they are about.
- After you change the scene you will be shown any problems the editor now flags. Silence means it is clean. Fix what you broke before reporting the work as done.
Working style:
diff --git a/desktop/electron/agent/types.ts b/desktop/electron/agent/types.ts
index 7c942722b..cff742b2e 100644
--- a/desktop/electron/agent/types.ts
+++ b/desktop/electron/agent/types.ts
@@ -14,7 +14,7 @@
* about a vendor reaches the kernel, and no editor policy reaches a provider.
*/
import type { HistoryMark } from '../../src/engine/EditorHistory';
-import type { Acceptance } from './acceptance';
+import type { Acceptance, Criterion } from './acceptance';
/** A tool as the catalog declares it (the .mjs registry is untyped). */
export interface CatalogTool {
@@ -312,6 +312,12 @@ export interface KernelDeps {
* 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.
*/
+ /**
+ * The PROJECT's standing claims (its manifest's `acceptance`), which a turn
+ * cannot add to, weaken or retract. Read per evaluation so an edit to them
+ * takes effect without reopening the project.
+ */
+ standing?(): readonly Criterion[];
journal?: {
/** Open one around this turn; null when it could not be opened. */
begin(): string | null;
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index b58fa3c9c..a809d8fd7 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -23,6 +23,7 @@ import {
resolveInRoot,
META_EXT,
} from './projectFs';
+import { PROJECT_MANIFEST_FILE, type AcceptanceCriterion } from '../src/project/format';
import { isInsideRoot } from './pathSandbox';
import * as journal from './fileJournal';
import { syncAutosave, listAutosave, restoreAutosave, clearAutosave, type AutosaveEntry } from './autosave';
@@ -771,6 +772,10 @@ const agentHost = createAgentHost({
void saveConversation(projectRoot, conversation)
.catch((e) => console.error('[agent] could not save the conversation:', e));
},
+ // The PROJECT's standing claims, read fresh each evaluation so editing them
+ // takes effect without reopening. Never a throw: a manifest that will not
+ // parse is a project problem, not a reason to fail every turn's verdict.
+ standing: () => standingCriteria,
// 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.
@@ -888,12 +893,27 @@ const platformRuntimeDirs = (): PlatformRuntimeDirs => ({
// .esengine/sdk so the project's tsconfig resolves `esengine` in the IDE.
// Staging failure does NOT block the open — but it is returned so the renderer
// can say it loudly (Output Log + toast), never swallowed into a console.warn.
+/**
+ * The open project's standing acceptance claims. Cached because the evaluator
+ * asks per turn and the manifest is on disk; refreshed whenever the file
+ * changes, so a hand edit or a promotion from the transcript is live.
+ */
+let standingCriteria: readonly AcceptanceCriterion[] = [];
+
+async function refreshStanding(): Promise<void> {
+ if (!projectRoot) { standingCriteria = []; return; }
+ standingCriteria = await readManifest(projectRoot)
+ .then((m) => m.acceptance ?? [])
+ .catch(() => standingCriteria);
+}
+
async function adoptRoot(root: string): Promise<string | undefined> {
// Held copies name paths under the OLD root; nothing about them is restorable
// into this one, and offering a revert that would write into a project the
// user has left is worse than losing the offer.
if (projectRoot !== root) await journal.discardAll();
projectRoot = root;
+ await refreshStanding();
if (win) startProjectWatch(root, win.webContents);
// The compiler follows the project. Built lazily on the first question, so an
// open pays nothing for a service it may never be asked one.
@@ -1000,9 +1020,12 @@ ipcMain.handle('project:thumbnail', async (_e, rect: { x: number; y: number; wid
ipcMain.handle('fs:read', (_e, relPath: string, offset?: number, limit?: number) =>
readSliceInRoot(requireRoot(), relPath, offset, limit));
ipcMain.handle('fs:readOptional', (_e, relPath: string) => readOptionalInRoot(requireRoot(), relPath));
-ipcMain.handle('fs:write', (_e, relPath: string, contents: string) =>
- writeInRoot(requireRoot(), relPath, contents),
-);
+ipcMain.handle('fs:write', async (_e, relPath: string, contents: string) => {
+ await writeInRoot(requireRoot(), relPath, contents);
+ // Rewriting the manifest is how a standing claim is added or removed, and the
+ // evaluator reads them from here — so this is where the two stay in step.
+ if (relPath === PROJECT_MANIFEST_FILE) await refreshStanding();
+});
ipcMain.handle('fs:readdir', (_e, relPath: string) => readDirInRoot(requireRoot(), relPath));
ipcMain.handle('fs:listFiles', (_e, relDir: string) => listFilesInRoot(requireRoot(), relDir));
ipcMain.handle('fs:rename', (_e, fromRel: string, toRel: string) =>
diff --git a/desktop/src/components/AgentDrawer.tsx b/desktop/src/components/AgentDrawer.tsx
index c4f53f807..9f289b118 100644
--- a/desktop/src/components/AgentDrawer.tsx
+++ b/desktop/src/components/AgentDrawer.tsx
@@ -38,7 +38,7 @@ import {
type AgentTurn, type AgentEntry, type AgentToolEntry, type AgentProseEntry,
} from '@/store/AgentStore';
import { COMPACT_AT, shouldCompact } from '@/settings/agentIds';
-import type { ConfirmAnswer } from '../../electron/agent/types';
+import type { ConfirmAnswer, CriterionResult } from '../../electron/agent/types';
import {
agentProviders, agentKeyId, subscribeProviders, providersRevision,
} from '@/agent/providers';
@@ -56,6 +56,8 @@ import { EditorControlSurface } from '@/engine/EditorSession';
import { previewSceneOps, withoutDeclined, type PreviewScene } from '@/engine/sceneOpsPreview';
import type { SceneOp } from '@/engine/sceneOps';
import { AssetRegistry } from '@/project/AssetRegistry';
+import { ProjectStore } from '@/project/ProjectStore';
+import { Toasts } from '@/store/Toasts';
import { t } from '@/i18n';
/**
@@ -524,7 +526,7 @@ function Skeleton() {
function Verdict({ turn }: { turn: AgentTurn }) {
const [open, setOpen] = useState(false);
const { verdict, results } = turn.acceptance;
- const claims = results.filter((r) => !r.floor);
+ const claims = results.filter((r) => r.owner === 'turn');
if (verdict === 'unverified' && claims.length === 0 && results.length === 0) return null;
const broke = results.filter((r) => r.state === 'broke').length;
return (
@@ -540,23 +542,64 @@ function Verdict({ turn }: { turn: AgentTurn }) {
</button>
<Fold open={open}>
<div className="ag-verdict-l">
- {results.map((r, i) => (
- <div className={`ag-claim s-${r.state}`} key={i}>
- <span className="ag-claim-s">
- {r.state === 'held' ? '✓' : r.state === 'broke' ? '✗' : '·'}
- </span>
- <span className="ag-claim-t">
- {r.says}
- {r.detail && <span className="ag-claim-d">{r.detail}</span>}
- </span>
- </div>
- ))}
+ {results.map((r, i) => <Claim key={i} result={r} />)}
</div>
</Fold>
</div>
);
}
+/**
+ * One claim, and who it belongs to.
+ *
+ * A claim the TURN proved can be kept: from then on the project makes it, every
+ * later run is measured against it, and no run can weaken or remove it. That is
+ * how a project accumulates the checks nobody sat down to write.
+ */
+const OWNER: Record<'editor' | 'project', string> = {
+ editor: t('hist.owner.editor'),
+ project: t('hist.owner.project'),
+};
+
+/** The editor's own checks send a code; the sentence is written here, where the
+ * reader's language is known. Everything else is the words its author chose. */
+const CHECK: Record<string, string> = {
+ diagnostics: t('hist.check.diagnostics'),
+ scripts: t('hist.check.scripts'),
+};
+
+function Claim({ result }: { result: CriterionResult }) {
+ const [kept, setKept] = useState(false);
+ const canKeep = result.owner === 'turn' && result.state === 'held' && !kept;
+ return (
+ <div className={`ag-claim s-${result.state} o-${result.owner}`}>
+ <span className="ag-claim-s">
+ {result.state === 'held' ? '✓' : result.state === 'broke' ? '✗' : '·'}
+ </span>
+ <span className="ag-claim-t">
+ {result.owner !== 'turn' && <span className="ag-claim-o">{OWNER[result.owner]}</span>}
+ {(result.check && CHECK[result.check]) ?? result.says}
+ {result.detail && <span className="ag-claim-d">{result.detail}</span>}
+ </span>
+ {canKeep && (
+ <button
+ type="button"
+ className="ag-claim-keep"
+ title={t('hist.keep.why')}
+ onClick={() => {
+ setKept(true);
+ const { says, probe, manual } = result;
+ void ProjectStore.keepCriterion({ says, ...(probe ? { probe } : {}), ...(manual ? { manual } : {}) })
+ .then((ok: boolean) => { if (ok) Toasts.push(t('hist.keep.kept'), 'success'); });
+ }}
+ >
+ {t('hist.keep')}
+ </button>
+ )}
+ </div>
+ );
+}
+
/**
* What the turn actually changed — the work product of a run, so it gets
* first-class presentation rather than a popover hung off the undo bar.
diff --git a/desktop/src/i18n/messages/history.ts b/desktop/src/i18n/messages/history.ts
index 50b231e90..789031fac 100644
--- a/desktop/src/i18n/messages/history.ts
+++ b/desktop/src/i18n/messages/history.ts
@@ -37,6 +37,20 @@ export const historyMessages = defineMessages({
zh: '这些太大没留备份,会保持现状:{paths}',
},
'hist.rewind.go': { en: 'Go back', zh: '退回' },
+ // Promoting a claim a run proved into one the project makes.
+ 'hist.keep': { en: 'Keep this check', zh: '保留这条检查' },
+ 'hist.keep.why': {
+ en: 'Every later run is measured against it, and no run can weaken or remove it.',
+ zh: '之后每一轮都要过这一条,而且没有哪一轮能弱化或删掉它。',
+ },
+ 'hist.keep.kept': { en: 'The project checks this from now on', zh: '从现在起项目会检查这一条' },
+ 'hist.keep.failed': { en: 'Could not write it to the project', zh: '没能写进项目' },
+ // Shorter than the sentence the MODEL reads: the row already says whose
+ // check it is, and repeating "the editor" beside "编辑器的" reads as a stutter.
+ 'hist.check.diagnostics': { en: 'nothing is flagged in the scene', zh: '场景里没有标出问题' },
+ 'hist.check.scripts': { en: 'the scripts compile', zh: '脚本能编译' },
+ 'hist.owner.project': { en: "the project's", zh: '项目的' },
+ 'hist.owner.editor': { en: 'the editor’s', zh: '编辑器的' },
'hist.revert.why': {
en: 'Take the whole run back — the scene edits and the files it wrote.',
zh: '整轮撤回 —— 场景改动和它写的文件一起。',
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 9f2b2b2f7..e1078133f 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -44,7 +44,7 @@ import { confirm } from '@/components/confirm';
import { previewApply } from './applyPreview';
import { t } from '@/i18n';
import { ASSET_SLOTS, metaTypeToSlot } from '@/project/assetSlots';
-import { resolveLayout, orientationFromDesignResolution, resolveOrientation, cameraScaleModeValue, resolveScripts, DEFAULT_SCRIPTS, WORKSPACE_DIR, PROJECT_MANIFEST_FILE, SORTING_LAYER_COUNT, trimSortingLayers, type OpenedProject, type ProjectFeatures, type ProjectLayout, type ProjectPackaging, type SteamPackaging, type ProjectScripts, type WorkspaceState, type DesignResolution, type ScreenPreset, type ScreenOrientation, type CameraScaleMode, type ExportPlatform } from './format';
+import { resolveLayout, orientationFromDesignResolution, resolveOrientation, cameraScaleModeValue, resolveScripts, DEFAULT_SCRIPTS, WORKSPACE_DIR, PROJECT_MANIFEST_FILE, SORTING_LAYER_COUNT, trimSortingLayers, type OpenedProject, type ProjectFeatures, type ProjectLayout, type ProjectPackaging, type SteamPackaging, type ProjectScripts, type WorkspaceState, type DesignResolution, type ScreenPreset, type ScreenOrientation, type CameraScaleMode, type ExportPlatform, type AcceptanceCriterion } from './format';
import { useEditorMode } from '@/store/editorModeStore';
import { PlayInspect } from '@/engine/PlayInspect';
import { useEditorStore } from '@/store/editorStore';
@@ -1823,6 +1823,30 @@ class ProjectStoreImpl {
*
* Patches queue on one chain, so each sees what the previous one wrote.
*/
+ /**
+ * Keep a claim a turn proved, as one the PROJECT now makes — every later turn
+ * is measured against it, and none can weaken or retract it. A person deciding
+ * it stands is the whole of what makes it theirs: the model wrote the words,
+ * and could have written weak ones; this list is the part it cannot reach.
+ */
+ async keepCriterion(criterion: AcceptanceCriterion): Promise<boolean> {
+ return this.patchManifest((raw) => {
+ const kept = Array.isArray(raw.acceptance) ? raw.acceptance as AcceptanceCriterion[] : [];
+ // By its words: the same claim proved twice is one claim, and a list that
+ // grew a duplicate every time it was re-proved is one nobody reads.
+ if (kept.some((c) => c.says === criterion.says)) return;
+ raw.acceptance = [...kept, criterion];
+ }, t('hist.keep.failed'));
+ }
+
+ /** Drop one, by what it says — the only handle the UI has on it. */
+ async dropCriterion(says: string): Promise<boolean> {
+ return this.patchManifest((raw) => {
+ const kept = Array.isArray(raw.acceptance) ? raw.acceptance as AcceptanceCriterion[] : [];
+ raw.acceptance = kept.filter((c) => c.says !== says);
+ }, t('hist.keep.failed'));
+ }
+
private manifestWrites: Promise<void> = Promise.resolve();
private patchManifest(apply: (raw: Record<string, unknown>) => void, failMessage: string): Promise<boolean> {
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index 20d00f347..84e9af9c8 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -354,6 +354,23 @@ export interface ProjectManifest {
features?: ProjectFeatures;
/** Persisted Package Project settings; see {@link ProjectPackaging}. */
packaging?: ProjectPackaging;
+ /** What must go on holding about this game; see {@link AcceptanceCriterion}. */
+ acceptance?: AcceptanceCriterion[];
+}
+
+/**
+ * One claim about the game that should keep holding, in the same shape a turn
+ * declares its own (electron/agent/acceptance.ts) — one vocabulary, two owners.
+ * A person put these here, so no turn can add, weaken or retract one, and they
+ * can only ever FAIL a turn: leaving them holding is not having succeeded.
+ */
+export interface AcceptanceCriterion {
+ /** What is claimed, in the words the user would use. */
+ says: string;
+ /** A JS expression evaluated in the RUNNING game; truthy means it held. */
+ probe?: string;
+ /** Only a person can settle this one. Says why a machine cannot. */
+ manual?: string;
}
/** A New-project template (a project directory used as a starting point). */
@@ -460,6 +477,19 @@ export function parseManifest(raw: unknown): ProjectManifest {
if (o.layout && typeof o.layout === 'object') {
manifest.layout = o.layout as Partial<ProjectLayout>;
}
+ if (Array.isArray(o.acceptance)) {
+ // Dropped rather than failing the load, like the presets above: a
+ // hand-edited claim must not cost anyone their project. A claim that
+ // settles nothing must never survive as one that silently holds.
+ const criteria = (o.acceptance as unknown[]).flatMap((raw): AcceptanceCriterion[] => {
+ const c = raw as Partial<AcceptanceCriterion> | null;
+ if (!c || typeof c.says !== 'string' || c.says.trim() === '') return [];
+ if (typeof c.probe === 'string' && c.probe.trim() !== '') return [{ says: c.says, probe: c.probe }];
+ if (typeof c.manual === 'string' && c.manual.trim() !== '') return [{ says: c.says, manual: c.manual }];
+ return [];
+ });
+ if (criteria.length > 0) manifest.acceptance = criteria;
+ }
if (o.scripts && typeof o.scripts === 'object') {
const s = o.scripts as Record<string, unknown>;
const scripts: ProjectScripts = {};
diff --git a/desktop/src/theme/agent.css b/desktop/src/theme/agent.css
index f91c2fb54..5495f1185 100644
--- a/desktop/src/theme/agent.css
+++ b/desktop/src/theme/agent.css
@@ -1006,6 +1006,29 @@
/* The reason on its own line: a probe's answer or a compiler message is where
the whole value is, and clipping it to a cell is where it used to go. */
.ag-claim-d { display: block; color: var(--text-faint); margin-top: 2px; }
+/* Whose claim it is. Only on the ones the RUN did not make, because that is the
+ surprising case — a check it had to pass but did not write. */
+.ag-claim-o { color: var(--text-faint); margin-right: 6px; }
+/* Top-aligned: a claim that wraps to two lines would otherwise centre its
+ sigil and its Keep against the block rather than against the first line. */
+.ag-claim { grid-template-columns: 12px minmax(0, 1fr) auto; align-items: start; }
+.ag-claim-keep {
+ align-self: start;
+ margin-top: -1px;
+ padding: 1px 7px;
+ border: 1px solid var(--border);
+ border-radius: var(--r-sm);
+ background: none;
+ color: var(--text-faint);
+ font: var(--fs-2xs) var(--font-ui);
+ cursor: pointer;
+ opacity: 0;
+ transition: opacity var(--t-fast), color var(--t-fast);
+}
+/* Offered on hover: it is a deliberate act, not something to be clicked past
+ while reading, and a row of buttons down the list would read as the point. */
+.ag-claim:hover .ag-claim-keep { opacity: 1; }
+.ag-claim-keep:hover { color: var(--text-hi); border-color: var(--text-dim); }
.ag-chg {
display: grid;
grid-template-columns: 14px minmax(0, 1fr) auto;
diff --git a/desktop/tests/agent-acceptance.test.ts b/desktop/tests/agent-acceptance.test.ts
index ee05b4de3..19aeb6112 100644
--- a/desktop/tests/agent-acceptance.test.ts
+++ b/desktop/tests/agent-acceptance.test.ts
@@ -11,7 +11,7 @@ import { describe, it, expect, vi } from 'vitest';
import {
criteriaProblem, evaluate, failureReport, MAX_CRITERIA,
} from '../electron/agent/acceptance';
-import type { KernelDeps } from '../electron/agent/types';
+import type { Criterion, KernelDeps } from '../electron/agent/types';
/** A driver whose editor is clean and whose game answers `probe` with `answer`. */
function fakeDriver(over: {
@@ -19,6 +19,7 @@ function fakeDriver(over: {
scripts?: unknown;
playing?: boolean;
probe?: (code: string) => unknown;
+ standing?: Criterion[];
} = {}) {
const driver = vi.fn(async (method: string) => {
if (method === 'getDiagnostics') return over.diagnostics ?? [];
@@ -35,7 +36,7 @@ function fakeDriver(over: {
return null;
});
(driver as { js: unknown }).js = vi.fn(async () => null);
- return { driver } as unknown as KernelDeps;
+ return { driver, standing: () => over.standing ?? [] } as unknown as KernelDeps;
}
describe('a claim has to name what settles it', () => {
@@ -104,7 +105,7 @@ describe('the verdict', () => {
// wrong is not a project where the work happened.
it('does not pass a turn on the editor checks alone', async () => {
const out = await evaluate(fakeDriver(), []);
- expect(out.results.every((r) => r.floor)).toBe(true);
+ expect(out.results.every((r) => r.owner !== 'turn')).toBe(true);
expect(out.results.some((r) => r.state === 'held')).toBe(true);
expect(out.verdict).toBe('unverified');
});
@@ -143,8 +144,8 @@ describe('what nothing was in a position to answer', () => {
const deps = fakeDriver({ playing: false, probe: () => true });
const out = await evaluate(deps, [{ says: 'the bar empties', probe: 'true' }]);
expect(out.verdict).toBe('unverified');
- expect(out.results.find((r) => !r.floor)).toMatchObject({ state: 'unsettled' });
- expect(out.results.find((r) => !r.floor)?.detail).toContain('not running');
+ expect(out.results.find((r) => r.owner === 'turn')).toMatchObject({ state: 'unsettled' });
+ expect(out.results.find((r) => r.owner === 'turn')?.detail).toContain('not running');
});
// Owned by a person, and reported as owned — never quietly counted as passed,
@@ -153,7 +154,7 @@ describe('what nothing was in a position to answer', () => {
const deps = fakeDriver();
const out = await evaluate(deps, [{ says: 'it reads at 1080p', manual: 'a judgement about legibility' }]);
expect(out.verdict).toBe('unverified');
- expect(out.results.find((r) => !r.floor)?.detail).toContain('only a person');
+ expect(out.results.find((r) => r.owner === 'turn')?.detail).toContain('only a person');
});
it('still passes on the claims a machine could settle', async () => {
@@ -182,3 +183,50 @@ describe('what the model is told to fix', () => {
expect(report).not.toContain('the good one');
});
});
+
+
+/**
+ * The project's own claims — the ones a turn did not write, cannot weaken and
+ * cannot retract. This is what makes the verdict worth reading over a long run:
+ * the bar stops being whatever the model thought to set that turn.
+ */
+describe("the project's standing claims", () => {
+ const standing = [{ says: 'the player can always reach the exit', probe: 'reachable' }];
+
+ it('fails a turn that broke one, however well its own claims did', async () => {
+ const deps = fakeDriver({ standing, probe: (code) => code !== 'reachable' });
+ const out = await evaluate(deps, [{ says: 'the new door opens', probe: 'door' }]);
+ expect(out.verdict).toBe('failed');
+ expect(out.results.find((r) => r.owner === 'project')).toMatchObject({ state: 'broke' });
+ });
+
+ // Not broken is not done. A run measured only against standing claims would
+ // pass by changing nothing at all.
+ it('does not pass a turn on standing claims alone', async () => {
+ const deps = fakeDriver({ standing, probe: () => true });
+ expect((await evaluate(deps, [])).verdict).toBe('unverified');
+ });
+
+ it("names them as the project's, so a reader knows who set the bar", async () => {
+ const deps = fakeDriver({ standing, probe: () => true });
+ const out = await evaluate(deps, [{ says: 'the new door opens', probe: 'door' }]);
+ expect(out.results.map((r) => r.owner)).toEqual(['editor', 'editor', 'project', 'turn']);
+ expect(out.verdict).toBe('passed');
+ });
+
+ it('tells the model about a standing claim it broke', async () => {
+ const deps = fakeDriver({ standing, probe: () => false });
+ const report = failureReport(await evaluate(deps, []))!;
+ expect(report).toContain('the player can always reach the exit');
+ });
+
+ // Kept whole, because keeping one means writing it into the project exactly
+ // as it was run — a claim that lost its probe on the way is not keepable.
+ it('carries the probe through, so a proven claim can be kept', async () => {
+ const deps = fakeDriver({ probe: () => true });
+ const out = await evaluate(deps, [{ says: 'the bar starts full', probe: 'hp === 100' }]);
+ expect(out.results.find((r) => r.owner === 'turn')).toMatchObject({
+ says: 'the bar starts full', probe: 'hp === 100', state: 'held',
+ });
+ });
+});
diff --git a/desktop/tests/project-acceptance.test.ts b/desktop/tests/project-acceptance.test.ts
new file mode 100644
index 000000000..5b6d62b64
--- /dev/null
+++ b/desktop/tests/project-acceptance.test.ts
@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The claims a PROJECT makes about itself, in its manifest.
+ *
+ * The reader is a whitelist, so a field with no branch persists and does
+ * nothing — which for this one would mean a project whose standing checks were
+ * silently never run, while the file said they were there.
+ */
+import { describe, it, expect } from 'vitest';
+import { parseManifest } from '@/project/format';
+
+const project = (acceptance: unknown) =>
+ parseManifest({ formatVersion: '1', name: 'Platformer', acceptance });
+
+describe('standing acceptance in the manifest', () => {
+ it('survives the read — it is not a field that persists and does nothing', () => {
+ const m = project([{ says: 'the player can always reach the exit', probe: 'reachable()' }]);
+ expect(m.acceptance).toEqual([
+ { says: 'the player can always reach the exit', probe: 'reachable()' },
+ ]);
+ });
+
+ it('keeps one only a person can settle, with the reason', () => {
+ const m = project([{ says: 'the HUD reads at 1080p', manual: 'a judgement about legibility' }]);
+ expect(m.acceptance).toEqual([
+ { says: 'the HUD reads at 1080p', manual: 'a judgement about legibility' },
+ ]);
+ });
+
+ // A hand-edited claim that settles nothing must not become a claim that
+ // silently holds. Dropped here rather than failing the load: a bad line must
+ // not cost anyone their project (the same rule screenPresets follows).
+ it('drops a claim that names nothing to settle it', () => {
+ expect(project([{ says: 'it feels good' }]).acceptance).toBeUndefined();
+ });
+
+ it('drops a claim that says nothing', () => {
+ expect(project([{ probe: 'true' }]).acceptance).toBeUndefined();
+ expect(project([{ says: ' ', probe: 'true' }]).acceptance).toBeUndefined();
+ });
+
+ it('keeps the good ones when one is bad', () => {
+ const m = project([
+ { says: 'good', probe: 'ok' },
+ { says: 'bad' },
+ { says: 'also good', manual: 'a look' },
+ ]);
+ expect(m.acceptance?.map((c) => c.says)).toEqual(['good', 'also good']);
+ });
+
+ // One criterion, one thing that settles it — the probe wins, because it is
+ // the half a machine can act on.
+ it('keeps one settler for a claim that gave two', () => {
+ const m = project([{ says: 'x', probe: 'ok', manual: 'also a look' }]);
+ expect(m.acceptance).toEqual([{ says: 'x', probe: 'ok' }]);
+ });
+
+ it('leaves a project with none alone', () => {
+ expect(project(undefined).acceptance).toBeUndefined();
+ expect(project([]).acceptance).toBeUndefined();
+ expect(project('nonsense').acceptance).toBeUndefined();
+ });
+});