bquarkz 546c6d1ee5
Test / Build occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
docs: consolidate Studio AI-first acceptance and lessons
2026-09-29 15:55:09 +01:00
2026-04-07 06:17:51 +01:00
2026-04-08 08:44:42 +00:00
2026-05-14 17:59:04 +01:00
2026-07-14 16:33:59 +01:00
2026-07-15 08:24:56 +01:00
2026-05-08 10:30:54 +01:00
2026-03-24 13:42:13 +00:00
2026-09-24 07:41:17 +01:00
2026-04-07 06:17:51 +01:00
2026-03-24 13:42:13 +00:00
2026-03-24 13:42:13 +00:00
2026-03-24 13:42:13 +00:00

Prometeu Studio

Prometeu Studio is the desktop development environment for the Prometeu toolchain.

This repository packages the Studio shell together with the embedded services it depends on: compiler pipeline integration, asset packing, runtime/debug orchestration, and project-local Studio state. The current implementation is a Java/JavaFX multi-module Gradle build.

What Lives Here

The root project is a monorepo with these main areas:

  • prometeu-app: Spring Boot non-web composition, concrete adapters, packaging, and JavaFX entry point (p.studio.app.StudioLauncher).
  • prometeu-studio-api: toolkit-neutral Studio contracts and operation surfaces.
  • prometeu-studio-core: JavaFX-free project, session, assets, shipper, runtime, and execution services.
  • prometeu-studio-ui-javafx: the current human-facing JavaFX adapter.
  • prometeu-packer: embedded packer APIs and implementation used by Studio.
  • prometeu-compiler: compiler core, build pipeline, frontend APIs, and the PBS frontend.
  • prometeu-infra: shared infrastructure used across modules.
  • docs/: normative specifications and architectural references.
  • discussion/: workflow artifacts for agendas, decisions, plans, and lessons.
  • test-projects/: sample workspaces used for local development and tests.

Current Product Shape

The Studio shell currently organizes the product around four workspaces:

  • Assets
  • Debug
  • DEV (external-agent authorization and observation)
  • Shipper

At runtime, the app boots an embedded packer, restores project-local Studio state, and opens the Studio launcher window. Project creation currently scaffolds a Prometeu workspace with prometeu.json, src/, assets/, build/, cartridge/, .workspace/, and local Studio metadata.

External Coding Agents (MCP)

Open a project and select DEV → Copy MCP configuration. The copied JSON is a provider-neutral connection descriptor: use its url and headers.Authorization in your external client's Streamable HTTP MCP setup, and provide its projectRoot and instructions to the agent. Adapt the configuration syntax to your client; there is no embedded chat or provider-specific setup wizard.

Keep the descriptor/token private and out of versioned files and logs. The endpoint is local to this computer. After restarting Studio, copy it again and update the client: both the port and token are ephemeral. Copying or connecting does not authorize edits or start a task.

  1. Connect, discover tools, read project context and applicable language/SDK references.
  2. In DEV, grant control (save all first if prompted). Active Debug prevents granting.
  3. The agent acquires a task, edits saved project files using its own tools, and validates through LSP/build. SDK and external libraries are consultable, read-only.
  4. Poll operations by operationId or clientRequestId. Recover a lost start receipt by lookup; never retry frame advancement blindly with a new ID.
  5. The agent explicitly releases control. To interrupt, use DEV's reclaim button and stop the external client separately: Studio cannot prevent its direct file writes.

The current production tools cover context, references, task control, LSP, build/pack, operation lookup/cancellation and headless execution (17 tools). Headless requires a runtime installation configured for the project; missing or incompatible installations fail explicitly. DEV is an observation panel, not manual Play/input for the agent's session; Debug retains the human testing workflow. Edits are preserved on cancellation; Git/review/recovery remain the developer's responsibility.

See the MCP contract for schemas, authorization, limits and delivery boundaries.

Troubleshooting automation

Symptom Action
Connection rejected after Studio restarts Copy DEV's configuration again: the token and OS-assigned endpoint are session-local. Do not publish the token.
Acquisition rejected or project busy Grant control in DEV first; stop manual Debug before granting. Query an existing operation instead of starting another; serialize headless calls.
RUNTIME_UNAVAILABLE or handshake incompatibility Check the project's configured runtime installation and its packaged headless command. Studio does not download a substitute.
NO_FRAME_AVAILABLE Advance at least one frame before requesting a capture.
Advance/page limit rejected Respect advertised limits and use reference pagination. Runtime's default maximum is 600 frames per advance; requests are not silently clamped.
Unknown language or missing reference Inspect project context and the declared manifest language; use only advertised capabilities/reference IDs. PBS is a creation default, not an unknown-language fallback.
Returning control reports cleanup failure Stop the external client's direct editing separately, then retry DEV reclaim after owned-process cleanup. Do not bypass the lock or restore stale editor buffers.

Language and SDK references are bundled locally; reading them does not require a compiler checkout or network download. SDK/external-library changes remain outside the game-authoring task, even when a reference exposes a limitation.

The real headless process adapter and task-service composition can be verified using an extracted runtime distribution:

./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime

This gate builds an installed PBS example, launches the actual runtime, checks canonical PNGs and explicit reset/reboot, cancels an advance and verifies process cleanup. It also runs the actual app composition through saved-file LSP queries, rebuilds and corrective loops after compile errors and guest faults. It does not download a runtime or substitute a protocol fixture.

To verify the complete HTTP-to-runtime-to-DEV image path, run this separate gate in a desktop environment:

./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2

It opens the real DEV view, grants control, uses an HTTP MCP client to query LSP, edit/build the installed PBS example and execute a fixed input timeline. PNG bytes, frame identities, state and fault are compared with a separate direct-JSONL runtime process; every decoded ImageView pixel and its visible identity/stale label are checked. Reset, fresh-session repetition and rebuild are included. This automated client is not the external coding-agent acceptance gate.

The same suite also exercises cancellation, disconnect/reconnect, revocation, project/app closure, crash and forced shutdown, corrective builds, and return to the real manual Debug host. These scenarios require a POSIX desktop (validated on macOS ARM64) and free port 7777. Only processes created by the test are killed or suspended. After a forced-shutdown error, an explicit second reclaim can acknowledge completed cleanup; control stays locked until cleanup is confirmed.

Follow-ups after the AI-first implementation

The following findings are recorded for investigation after implementation; they are not considered fixed by the passing integration tests:

  • PBS/LSP SDK navigation: definition lookup for the bundled SDK's Input.pad() currently returns no location. Project-source navigation and indexed SDK reference reads work. Investigate SDK symbol resolution separately; an empty definition result is not evidence of missing runtime support or permission to edit the SDK.
  • Build tooling: the validation environment's JDK 25 triggers Kotlin's target-24 fallback and Java/Kotlin target compatibility warnings in buildSrc. The targeted regression passes, but the toolchain/target alignment needs separate review.

Cross-platform desktop coverage remains a validation boundary, not a confirmed product defect. Desktop acceptance so far covers macOS ARM64 and Codex CLI only.

The first real Codex CLI acceptance run exercised editing, LSP, build/pack, input, 1,110 frames, native MCP images and explicit release. The developer confirmed the DEV result and successfully ran the edited game using manual Debug Play afterward. Additional follow-ups from that run: clearer errors for oversized reference pages, guidance for sequential headless queries after BUSY, and easier discovery of framebuffer dimensions. Capture before the first completed frame correctly returns NO_FRAME_AVAILABLE; it is not a runtime defect. Noninteractive clients must also provide an approval path for MCP work calls; the acceptance used Codex's approval review with a project-scoped workspace-write sandbox.

The completed baseline's architecture, acceptance evidence and post-implementation follow-ups are consolidated in LSN-0076.

Requirements

  • JDK 21 or newer recommended for local development
  • Gradle wrapper (./gradlew) included in the repository
  • A desktop environment capable of running JavaFX

Common Commands

Run the full project graph listing:

./gradlew projects

Run the desktop application:

./gradlew :prometeu-app:run

Run the test suite:

./gradlew test

Generate the aggregated coverage report:

./gradlew jacocoTestReport

Repository Reading Guide

If you are new to the codebase, this order is usually the fastest path:

  1. Start at prometeu-app to see application bootstrap.
  2. Read prometeu-studio-api and prometeu-studio-core for Studio contracts and application services.
  3. Read prometeu-studio-ui-javafx for the current shell, workspaces, and human-facing flows.
  4. Read prometeu-app for Spring composition and provider gateways.
  5. Read prometeu-packer for asset and packaging boundaries.
  6. Read prometeu-compiler when you need compiler or PBS language behavior.

Specs And Architecture

Important reference surfaces:

  • docs/specs/compiler/: shared compiler specifications
  • docs/specs/packer/: packer specifications
  • docs/vm-arch/: VM and ISA architecture references

These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.

S
Description
No description provided
Readme
15 MiB
Languages
Java 94.5%
Rust 3%
Python 1%
TypeScript 0.6%
CSS 0.6%
Other 0.3%