@playcraft/cli 0.1.66 → 0.1.68

package/dist/workspace-runtime/workspaces/level-editor-agent.js

@@ -0,0 +1,410 @@
+import { randomUUID } from 'node:crypto';
+import JSON5 from 'json5';
+import { LevelEditorError, LEVEL_EDITOR_COMPONENT_CATALOG, LEVEL_EDITOR_AUTHORING_CONTRACT, levelEditorTaskRequestSchema, levelEditorTaskReportSchema, levelEditorVerifyPayloadSchema, WORKSPACE_FILE_CONTENT_MAX, } from '@playcraft/common/cloud-workspace/runtime';
+import { parameterInputSnapshot } from './parameter-agent-inputs.js';
+import { readLevelEditorFile, readWorkspaceLevelEditor, levelEditorDigest, } from './level-editor.js';
+import { validateLevelEditorExtensions, levelEditorExtensionPaths, } from './level-editor-extensions.js';
+import { revisionScope } from './registry.js';
+import { runDeveloperCommand } from './developer-command.js';
+import { prepareParameterProductionCheck, inspectParameterProductionCheck, } from './parameter-production.js';
+import { levelEditorTaskWorkspace, readPrivateLevelEditorTask, writePrivateLevelEditorTask, listPrivateLevelEditorTaskIds, preserveLevelEditorBaseline, } from './level-editor-agent-store.js';
+const current = (state, task) => task.record.generation === state.config.generation &&
+    task.record.runtimeEpoch === state.runtimeEpoch;
+const codeOf = (error) => error instanceof Error && 'code' in error && typeof error.code === 'string'
+    ? error.code
+    : 'level_editor_verification_failed';
+async function inputSnapshot(root, declaredPaths = [], readContext) {
+    const original = await parameterInputSnapshot(root), sources = new Map(original.sources.map((item) => [item.path, item.sha256]));
+    const explicit = new Set(declaredPaths);
+    const scope = readContext && ('operation' in readContext ? readContext.operation : readContext);
+    const revisions = readContext && scope
+        ? (readContext.state.journal.fileRevisions?.(revisionScope(readContext.state, scope.workspaceId, scope.directoryName)) ?? {})
+        : {};
+    const snapshot = await readWorkspaceLevelEditor(root, revisions, readContext);
+    if (snapshot.definition)
+        for (const path of [
+            snapshot.definitionPath,
+            ...Object.values(snapshot.definition.documents).flatMap((item) => [item.path, item.schema]),
+            ...Object.values(snapshot.definition.preview ?? {}),
+            ...levelEditorExtensionPaths(snapshot.definition),
+        ])
+            explicit.add(path);
+    try {
+        const manifest = JSON5.parse((await readLevelEditorFile(root, '.playcraft/workspace.json')).toString('utf8'));
+        for (const path of manifest.previewRuntime?.gameFilePaths ?? [])
+            explicit.add(path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    // The automatic source walk has its own 32 MiB budget. Explicit report/build inputs share
+    // an additional bounded read budget, including managed files excluded from that source walk.
+    let remaining = 32 * 1024 * 1024;
+    for (const path of explicit) {
+        if (remaining <= 0)
+            throw new LevelEditorError('level_editor_input_budget');
+        let bytes;
+        try {
+            bytes = await readLevelEditorFile(root, path, Math.min(WORKSPACE_FILE_CONTENT_MAX, remaining));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                throw new LevelEditorError('level_editor_evidence_missing', [path]);
+            throw error;
+        }
+        remaining -= bytes.byteLength;
+        sources.set(path, levelEditorDigest(bytes));
+    }
+    const sorted = [...sources]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([path, sha256]) => ({ path, sha256 }));
+    return { sources: sorted, digest: levelEditorDigest(JSON.stringify(sorted)) };
+}
+function owner(state, operation, session = true) {
+    if ((session && !operation.sessionId) ||
+        operation.directoryName === 'root' ||
+        operation.environment !== state.config.environment ||
+        operation.userId !== state.config.userId ||
+        (operation.generation !== undefined && operation.generation !== state.config.generation) ||
+        (operation.runtimeEpoch !== undefined && operation.runtimeEpoch !== state.runtimeEpoch))
+        throw new LevelEditorError('level_editor_scope_invalid');
+    return {
+        workspaceId: levelEditorTaskWorkspace(state, operation.workspaceId),
+        directoryName: operation.directoryName ?? 'basic',
+        sessionId: operation.sessionId ?? '',
+    };
+}
+async function update(state, task, patch, root) {
+    task.record = { ...task.record, ...patch, updatedAt: new Date().toISOString() };
+    await writePrivateLevelEditorTask(state, task, root);
+    return task.record;
+}
+async function inspectReport(root, task, readContext) {
+    const bytes = await readLevelEditorFile(root, task.record.reportPath, 1024 * 1024);
+    const report = levelEditorTaskReportSchema.parse(JSON.parse(bytes.toString('utf8')));
+    if (report.taskId !== task.record.taskId)
+        throw new LevelEditorError('level_editor_report_identity');
+    const inputs = await inputSnapshot(root, report.sources.map((source) => source.path), readContext), sourceMap = new Map(inputs.sources.map((item) => [item.path, item.sha256]));
+    const declared = new Set(report.sources.map((item) => item.path));
+    for (const source of report.sources)
+        if (sourceMap.get(source.path) !== source.sha256)
+            throw new LevelEditorError('level_editor_report_stale');
+    for (const consumer of report.consumers) {
+        if (consumer.path.startsWith('.playcraft/preview-runtime/'))
+            throw new LevelEditorError('level_editor_consumer_evidence_invalid');
+        if (!declared.has(consumer.path))
+            throw new LevelEditorError('level_editor_consumer_evidence_missing');
+        const text = (await readLevelEditorFile(root, consumer.path)).toString('utf8');
+        if (!text.trim() || (consumer.line && consumer.line > text.split('\n').length))
+            throw new LevelEditorError('level_editor_consumer_evidence_invalid');
+    }
+    return { report, digest: inputs.digest, reportHash: levelEditorDigest(bytes), sources: declared };
+}
+export async function prepareLevelEditorTask(state, operation, value, root, skill) {
+    const request = levelEditorTaskRequestSchema.parse(value), scope = owner(state, operation);
+    if (operation.kind !== 'session.turn' || request.taskId !== operation.clientRequestId)
+        throw new LevelEditorError('level_editor_task_identity');
+    if (!skill?.entryKey || !/^[a-f0-9]{64}$/.test(skill.lockHash) || !skill.path)
+        throw new LevelEditorError('level_editor_skill_unavailable');
+    const existing = await readPrivateLevelEditorTask(state, scope.workspaceId, scope.directoryName, request.taskId, root);
+    if (existing &&
+        (!current(state, existing) ||
+            existing.record.sessionId !== scope.sessionId ||
+            JSON.stringify(existing.request) !== JSON.stringify(request) ||
+            existing.record.initializationSkill?.entryKey !== skill.entryKey ||
+            existing.record.initializationSkill?.lockHash !== skill.lockHash))
+        throw new LevelEditorError('level_editor_task_conflict');
+    const snapshot = await readWorkspaceLevelEditor(root, state.journal.fileRevisions(revisionScope(state, operation.workspaceId, scope.directoryName)), { state, operation });
+    if (request.sourceFingerprint && request.sourceFingerprint !== snapshot.sourceFingerprint)
+        throw new LevelEditorError('level_editor_source_conflict');
+    if (request.editorId && snapshot.definition && request.editorId !== snapshot.definition.editorId)
+        throw new LevelEditorError('level_editor_target_mismatch');
+    const timestamp = new Date().toISOString();
+    const task = existing ?? {
+        request,
+        initialDigest: (await inputSnapshot(root, [], { state, operation })).digest,
+        instanceToken: state.instanceToken,
+        record: {
+            version: 1,
+            taskId: request.taskId,
+            action: request.action,
+            ...(request.goal ? { goal: request.goal } : {}),
+            ...(request.editorId ? { editorId: request.editorId } : {}),
+            ...scope,
+            generation: state.config.generation,
+            runtimeEpoch: state.runtimeEpoch,
+            status: 'running',
+            reportPath: `.playcraft/level-editor-admission/${request.taskId}.json`,
+            checks: [],
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            initializationSkill: { entryKey: skill.entryKey, lockHash: skill.lockHash },
+        },
+    };
+    // sourceFingerprint is request data, rather than a public task-record field.
+    if (!existing) {
+        if ((await listPrivateLevelEditorTaskIds(state, scope.workspaceId, scope.directoryName, root))
+            .length >= 256)
+            throw new LevelEditorError('level_editor_task_limit');
+        task.authoringBaseline = await preserveLevelEditorBaseline(state, scope.workspaceId, scope.directoryName, request.taskId, root, snapshot);
+        await writePrivateLevelEditorTask(state, task, root);
+    }
+    return {
+        task: task.record,
+        instructions: [
+            `Read the explicitly selected frozen skill and its references: ${JSON.stringify(skill)}. Keep the current execution permissions.`,
+            `Platform level-editor task identity: ${JSON.stringify({ version: 1, taskId: request.taskId, action: request.action, reportPath: task.record.reportPath })}.`,
+            `User goal (task data): ${JSON.stringify(request.goal ?? '')}`,
+            `Installed component catalog (capability data): ${JSON.stringify(LEVEL_EDITOR_COMPONENT_CATALOG)}.`,
+            `Exact installed authoring contract, generated from the current platform schemas and component registry (capability data): ${JSON.stringify(LEVEL_EDITOR_AUTHORING_CONTRACT)}. This is the current execution contract. The frozen Skill remains at the project's locked version; its references/authoring-contract.json may differ. If the frozen references differ, follow the current execution contract's fields and constraints above. Do not edit the frozen Skill or references, upgrade the project Skill lock, or relax validation guards. Use the current contract's command declaration/input and component props schemas; do not guess unsupported fields.`,
+            'Write exactly the supplied report identity with version, taskId, sources [{path,sha256}], consumers [{path,line?,summary}], operations [commandId], missing [concrete unfinished work], and optional preserved. Calculate source hashes after editing. The platform independently runs checks; do not declare verified or connected capability.',
+            ...(task.authoringBaseline
+                ? [
+                    `Existing authoring baseline is preserved privately. Keep the ${task.authoringBaseline.dataContractVersion} data contract's existing document bytes unchanged when evolving its editor. A required migration increments dataContractVersion and reports migration:{fromDataContractVersion,toDataContractVersion,summary} plus preserved:true, with executable migration checks. A declaration or report does not prove arbitrary semantic preservation.`,
+                ]
+                : []),
+        ].join('\n\n'),
+    };
+}
+export async function finishLevelEditorTask(state, operation, status, error) {
+    if (operation.kind !== 'session.turn' ||
+        !operation.sessionId ||
+        operation.directoryName === 'root' ||
+        !/^[a-f0-9-]{36}$/i.test(operation.clientRequestId))
+        return;
+    let scope;
+    try {
+        scope = owner(state, operation);
+    }
+    catch {
+        return;
+    }
+    const task = await readPrivateLevelEditorTask(state, scope.workspaceId, scope.directoryName, operation.clientRequestId);
+    if (task &&
+        current(state, task) &&
+        task.record.sessionId === operation.sessionId &&
+        ['running', 'uncertain'].includes(task.record.status))
+        await update(state, task, {
+            status: status === 'completed' ? 'reported' : status,
+            error: error?.slice(0, 256),
+        });
+}
+export async function listLevelEditorTasks(state, workspaceId, directoryName, root) {
+    if (directoryName === 'root')
+        return [];
+    const tasks = [];
+    for (const id of await listPrivateLevelEditorTaskIds(state, levelEditorTaskWorkspace(state, workspaceId), directoryName, root)) {
+        let task = await readPrivateLevelEditorTask(state, levelEditorTaskWorkspace(state, workspaceId), directoryName, id, root);
+        if (!task)
+            continue;
+        if (!current(state, task)) {
+            tasks.push({ ...task.record, status: 'stale' });
+            continue;
+        }
+        if (['running', 'uncertain'].includes(task.record.status)) {
+            const operation = state.journal
+                .listOperations?.()
+                .map((item) => item.operation)
+                .find((item) => item.kind === 'session.turn' &&
+                item.clientRequestId === id &&
+                item.sessionId === task.record.sessionId);
+            if (operation &&
+                ['completed', 'failed', 'interrupted', 'uncertain'].includes(operation.status)) {
+                await finishLevelEditorTask(state, operation, operation.status, operation.error);
+                task = (await readPrivateLevelEditorTask(state, levelEditorTaskWorkspace(state, workspaceId), directoryName, id, root));
+            }
+        }
+        if (task.instanceToken !== state.instanceToken && task.record.status === 'checking')
+            await update(state, task, {
+                status: 'needs-verification',
+                receiptId: undefined,
+                error: 'level_editor_check_interrupted',
+            }, root);
+        if (task.instanceToken !== state.instanceToken && task.record.status === 'running')
+            await update(state, task, {
+                status: 'uncertain',
+                receiptId: undefined,
+                error: 'level_editor_turn_unconfirmed_after_restart',
+            }, root);
+        try {
+            if (!['running', 'uncertain', 'interrupted'].includes(task.record.status)) {
+                const checked = await inspectReport(root, task, {
+                    state,
+                    workspaceId: task.record.workspaceId,
+                    directoryName: task.record.directoryName,
+                });
+                if ((task.record.sourceDigest && checked.digest !== task.record.sourceDigest) ||
+                    (task.reportHash && task.reportHash !== checked.reportHash))
+                    task.record = {
+                        ...task.record,
+                        status: 'stale',
+                        error: 'level_editor_sources_changed',
+                        receiptId: undefined,
+                    };
+                tasks.push({ ...task.record, report: checked.report });
+            }
+            else
+                tasks.push(task.record);
+        }
+        catch (error) {
+            const code = codeOf(error);
+            const stale = code === 'level_editor_report_stale' || code === 'level_editor_sources_changed';
+            tasks.push({
+                ...task.record,
+                status: stale ? 'stale' : 'invalid',
+                error: stale ? code : 'level_editor_report_invalid',
+                receiptId: undefined,
+            });
+        }
+    }
+    return tasks.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+export async function verifyLevelEditorTask(state, operation, value, root, options = {}) {
+    if (operation.kind !== 'level-editor.verify')
+        throw new LevelEditorError('level_editor_task_identity');
+    const { taskId } = levelEditorVerifyPayloadSchema.parse(value), scope = owner(state, operation, false);
+    const task = await readPrivateLevelEditorTask(state, scope.workspaceId, scope.directoryName, taskId, root);
+    if (!task ||
+        !current(state, task) ||
+        ['running', 'uncertain', 'interrupted'].includes(task.record.status))
+        throw new LevelEditorError('level_editor_task_unavailable');
+    const instance = state.instanceToken;
+    const active = () => {
+        options.signal?.throwIfAborted();
+        options.assertActive?.();
+        if (!current(state, task) || state.instanceToken !== instance || state.journal.destroyed())
+            throw new LevelEditorError('level_editor_task_stale');
+    };
+    try {
+        active();
+        const before = await inspectReport(root, task, { state, operation });
+        if (before.report.missing.length)
+            throw new LevelEditorError('level_editor_integration_incomplete');
+        const snapshot = await readWorkspaceLevelEditor(root, state.journal.fileRevisions(revisionScope(state, operation.workspaceId, scope.directoryName)), { state, operation });
+        if (snapshot.status !== 'ready' || !snapshot.definition?.preview)
+            throw new LevelEditorError('level_editor_preview_not_ready');
+        if (task.request.editorId && snapshot.definition.editorId !== task.request.editorId)
+            throw new LevelEditorError('level_editor_target_mismatch');
+        const baseline = task.authoringBaseline;
+        if (baseline) {
+            if (snapshot.definition.dataContractVersion === baseline.dataContractVersion) {
+                if (baseline.documents.some((document) => snapshot.definition.documents[document.documentId]?.path !== document.path ||
+                    snapshot.documentHashes[document.documentId] !== document.sha256))
+                    throw new LevelEditorError('level_editor_existing_data_changed');
+            }
+            else {
+                const migration = before.report.migration;
+                if (snapshot.definition.dataContractVersion <= baseline.dataContractVersion ||
+                    before.report.preserved !== true ||
+                    migration?.fromDataContractVersion !== baseline.dataContractVersion ||
+                    migration.toDataContractVersion !== snapshot.definition.dataContractVersion)
+                    throw new LevelEditorError('level_editor_migration_plan_missing');
+            }
+        }
+        if ((await validateLevelEditorExtensions(root, snapshot.definition, snapshot.documents)).some((item) => item.severity === 'error'))
+            throw new LevelEditorError('level_editor_validation_failed');
+        for (const commandId of before.report.operations)
+            if (!snapshot.definition.commands[commandId])
+                throw new LevelEditorError('level_editor_operation_evidence_invalid');
+        const spatial = (id) => {
+            const command = snapshot.definition.commands[id];
+            return (!!command &&
+                (['grid.paint', 'object.transform', 'path.edit'].includes(command.operation) ||
+                    (command.operation === 'command.batch' &&
+                        command.steps.some((step) => spatial(step.commandId)))));
+        };
+        const dedicated = Object.values(snapshot.definition.extensions?.views ?? {}).some((view) => view.commands.some((id) => before.report.operations.includes(id)));
+        if (!before.report.operations.some(spatial) && !dedicated)
+            throw new LevelEditorError('level_editor_space_consumer_missing');
+        const required = [
+            '.playcraft/workspace.json',
+            snapshot.definitionPath,
+            'package.json',
+            ...Object.values(snapshot.definition.documents).flatMap((item) => [item.path, item.schema]),
+            ...Object.values(snapshot.definition.preview),
+            ...levelEditorExtensionPaths(snapshot.definition),
+        ];
+        if (required.some((path) => !before.sources.has(path)))
+            throw new LevelEditorError('level_editor_evidence_missing');
+        const pkg = JSON.parse((await readLevelEditorFile(root, 'package.json')).toString('utf8'));
+        if (['test:level-editor', 'build'].some((name) => typeof pkg.scripts?.[name] !== 'string'))
+            throw new LevelEditorError('level_editor_check_script_missing');
+        await update(state, task, {
+            status: 'checking',
+            checks: [],
+            report: before.report,
+            receiptId: undefined,
+            productionCheck: undefined,
+        }, root);
+        const scripts = [
+            'test:level-editor',
+            'build',
+            ...(typeof pkg.scripts?.typecheck === 'string' ? ['typecheck'] : []),
+        ];
+        let production;
+        for (const script of scripts) {
+            active();
+            const plan = script === 'build' ? await prepareParameterProductionCheck(root) : undefined;
+            const chunks = [];
+            let size = 0;
+            const startedAt = new Date().toISOString();
+            const result = await (options.runCommand ?? runDeveloperCommand)(state, {
+                cwd: root,
+                command: `pnpm run ${script}`,
+                processId: `level-editor-${taskId}-${script.replace(':', '-')}`,
+                timeoutMs: script === 'build' ? 300_000 : 120_000,
+                signal: options.signal,
+                onOutput(chunk) {
+                    const data = Buffer.from(chunk);
+                    size += data.length;
+                    if (size <= 1024 * 1024)
+                        chunks.push(data);
+                },
+            });
+            active();
+            task.record.checks.push({
+                script: script,
+                code: result.code ?? null,
+                timedOut: result.timedOut,
+                ...(result.canceled ? { canceled: true } : {}),
+                logDigest: levelEditorDigest(Buffer.concat(chunks)),
+                startedAt,
+                finishedAt: new Date().toISOString(),
+            });
+            await writePrivateLevelEditorTask(state, task, root);
+            if (result.code !== 0 || result.timedOut || result.canceled)
+                throw new LevelEditorError('level_editor_check_failed');
+            if (plan)
+                production = await inspectParameterProductionCheck(plan, active);
+        }
+        active();
+        const after = await inspectReport(root, task, { state, operation });
+        if (before.digest !== after.digest || before.reportHash !== after.reportHash)
+            throw new LevelEditorError('level_editor_sources_changed');
+        task.reportHash = after.reportHash;
+        task.instanceToken = state.instanceToken;
+        return update(state, task, {
+            status: 'verified',
+            sourceDigest: after.digest,
+            receiptId: randomUUID(),
+            error: undefined,
+            ...(production
+                ? { productionCheck: { ...production, checkedAt: new Date().toISOString() } }
+                : {}),
+        }, root);
+    }
+    catch (error) {
+        const code = codeOf(error);
+        return update(state, task, {
+            status: /stale|changed/.test(code)
+                ? 'stale'
+                : /incomplete|missing|not_ready/.test(code)
+                    ? 'needs-verification'
+                    : 'failed',
+            error: code,
+            receiptId: undefined,
+            productionCheck: undefined,
+        }, root);
+    }
+}