# DEV and Automation Specification ## Status Active normative baseline; implementation is delivered in ordered phases. This status does not claim that the DEV workspace, MCP endpoint or integrated agent loop is already available in an installed Studio. ## Scope and Ownership Owner: **studio**, including neutral API/Core services, the JavaFX DEV workspace and application/infrastructure adapters. Runtime owns execution and its external headless protocol. Compiler, language/SDK references, LSP and Packer retain their existing domain ownership. ## Purpose Allow a developer to grant control of an open project to an external coding agent, observe managed operations and canonical runtime images, and explicitly reclaim control. Studio provides specialized project services through MCP, not an embedded agent or a second editor. ## Authority and Normative Inputs This specification implements accepted **DEC-0060**, including D1–D7 and B1–B9. PLN-0139 sequences its implementation; it does not redefine this contract. - [Core and Adapter Architecture](9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md): dependency direction, composition and shared operations. - [Shell and Workspace Layout](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md): workspace mounting and project lifetime. - [Project-Local State](8.%20Project-Local%20Studio%20State%20Specification.md): configuration and restoration exclusions. - [Runtime Headless Automation Protocol](../../../../runtime/docs/specs/runtime/11a-headless-automation-protocol.md): runtime-owned wire, commands, framing, limits and execution meanings. MUST, MUST NOT and MAY express requirements, prohibitions and permissions. Implementation MUST NOT weaken this accepted baseline; substantive ambiguity requires explicit decision review rather than a guessed implementation rule. ## 1. Shared Services and Protocol Boundaries JavaFX and MCP MUST consume the same neutral API/Core authority, sessions, operations and orchestration. Neither adapter MAY simulate UI actions or implement a parallel permission/build/pack/execution system. | Boundary | Owner and responsibility | | --- | --- | | Studio API | Plain-Java contracts, identities, snapshots, typed outcomes, diagnostics and ports; no toolkit, framework or concrete wire DTOs | | Studio Core | Project/session authority, guards, operations, build/pack/runtime coordination and ordered cleanup; testable without JavaFX or Spring | | JavaFX DEV | Human grant/reclaim actions, presentation, localization, canvas, subscriptions and FX-thread projection | | Application/infrastructure | MCP HTTP transport, process supervision, runtime JSONL translation, existing project LSP client, lifecycle and packaging | | Runtime | Firmware/VM execution, input sampling, logical frames, ticks, rendering, watchdogs and faults | | External coding client | Agent/chat, model/provider credentials, native file editing, budget, iterations and simple task stopping criteria | MCP Streamable HTTP, runtime JSONL/stdio, and human Debug/DevTools MUST remain distinct protocols with distinct lifecycles. A native Rust/Java binding is not the chosen runtime boundary. Compiler, LSP, Packer and runtime semantics MUST NOT be reimplemented in Studio. The functional dependency graph in spec 9 MUST remain unchanged. Services requiring guards MUST receive shared authority through neutral contracts and composition, not depend on concrete session implementations or UI state. ## 2. Project Authority and Control States Authority MUST belong to an open project session, not a tab, focused window, HTTP connection or UI component. The agent MUST supply a project root; Studio MUST validate it against an open project and use explicit project identity. Window focus MUST NOT implicitly select a call's target. Connection authentication, human project grant and task control identity MUST be separate checks. At most one task MAY own a project's grant. Acquisition without a prior human grant MUST fail. A task identity MUST be required for authorized work and MUST NOT be reusable for another project or revoked task. | State | Admission and permitted behavior | Exit | | --- | --- | --- | | Manual control | Human editing/Debug; grant only with no active Debug or conflicting managed work, and successful document handoff | Human grant enters waiting | | Waiting for agent | Grant already blocks conflicting manual work; authenticated agent can acquire; human can reclaim without an agent connection | Acquisition enters working; reclaim enters returning | | Agent working | One acquired task uses its valid identity; developer can inspect, navigate and reclaim | Explicit task release or human revoke enters returning | | Returning control | Prior authority is invalid; stop managed work and refresh documents; manual conflicting actions remain blocked | Manual control only after cleanup/handoff | Grant and acquisition MUST be enforced atomically with conflicting operation admission. Concurrent acquisition MUST NOT create two owners. Project-local authority MUST NOT become a global Studio lock. Human Debug active MUST prevent grant. From grant onward, including waiting and silence, Studio MUST prevent manual editing, Debug, build and other conflicting project mutation. Guards MUST apply at service entry points as well as UI bindings. Navigation, inspection and monitoring remain available. An operation finishing, failing compilation, raising a guest fault or losing its runtime session MUST NOT release task authority. Silence, client disconnection and waiting MUST NOT cause expiration or automatic resumption. There is no heartbeat or silence timeout in this baseline. ## 3. Grant and Saved-Document Handoff Grant MUST cover Studio-owned unsaved buffers/drafts, including dirty asset editing surfaces; it MUST NOT assume that source files are the only editable project content. If such content is dirty, DEV MUST offer **Save all and grant** or **Cancel**. Grant MUST follow successful saves; user cancellation or save failure MUST NOT cede control. Clean projects do not require a code snapshot, clean Git tree or commit. Document participants MUST use neutral handoff contracts without moving presentation buffers or JavaFX types into Core. The agent edits the actual project folder with native external tools. Build MUST use saved files, and the existing project LSP client MUST synchronize saved content before semantic queries. Studio MUST NOT claim to save external unsaved buffers or protect against concurrent external writes. On authority return, Studio MUST refresh open documents from disk and MUST NOT reapply stale buffers over agent changes. Revocation/cancellation MUST preserve edits already made. There is no later Apply/merge step or Studio-owned code rollback. Review, integrity, Git commits and recovery remain developer duties. SDK/external libraries MUST be consultable but MUST NOT be edited by the game-authoring task. Editable local libraries MUST be inside project scope. Unsupported capabilities or required SDK changes MUST be reported as limitations, not silently implemented outside that scope. This does not prohibit the runtime engineering delivery that prepared this integration. ## 4. Return, Revocation and Closure Explicit release and human reclaim MUST follow this order: 1. Invalidate task authority and reject new or delayed calls under the old identity. 2. Cancel/stop managed work and shut down owned runtime processes. 3. Refresh open documents from saved project content, without stale writeback. 4. Release conflicting manual operations and present manual control. Late completions MUST NOT resurrect a revoked task or restore its authority. Cleanup MUST NOT advertise manual control before managed work is stopped and document refresh is complete. Diagnostics MUST distinguish cleanup failure from a successful return; operation outcome and authorization state are not the same. Reclaim MUST also work while waiting for an agent or after an operation failure. Another task MUST require a new human grant. Closing/hiding/switching DEV MUST NOT release control. Closing the project or Studio MUST revoke authority and stop managed processes before teardown of their providers/executors. Reopening MUST start in manual control, even when restoring DEV as the selected workspace. Studio cannot stop direct writes by the external coding client. The UI and connection instructions MUST tell the developer to stop that client separately; reclaim is not an operating-system filesystem lock or a rollback guarantee. ## 5. DEV Workspace Contract DEV MUST expose: - **Grant control to AI** (`Ceder controle à IA`) and **Interrupt and reclaim control** (`Interromper e retomar controle`); - the four control states, project identity, current managed operation and diagnostics; - a canonical-image canvas with session/build/logical-frame/render-frame identity and stale status; - a short history of Studio calls, not an independent code history; - **Copy MCP configuration**, plus short connection/use instructions when the real MCP composition is available. Actions MUST reflect shared service authority. DEV MUST NOT own a duplicate lock or release authority when disposing visual subscriptions. Presentation updates MUST follow the existing FX-thread, theme, localization and workspace lifecycle rules. DEV MUST NOT contain chat, provider settings, manual headless Play/input or concurrent human control of the agent's execution. Human play/testing remains in Debug with its existing host/protocol/lifecycle, subject to symmetric guards. “Agent working” means the task has been acquired; it is not a claim to observe all external edits, reasoning or conversation. Without a real composed MCP endpoint, configuration copy MUST be unavailable rather than produce a fabricated endpoint or token. Test doubles MAY supply operations/captures to isolated tests, never masquerade as product execution. ## 6. Operations and Lost Responses Automation MUST reuse the neutral operation executor/handle boundary: stable operation identity, observable snapshots/progress, cancellation, asynchronous completion and typed results. Build/pack diagnostics MUST be preserved. Success, lifecycle termination, guest fault, infrastructure/host failure and cancellation MUST remain distinguishable, including known partial progress. Build and advance starts MUST return `operationId` promptly. Each start MUST accept `clientRequestId` and allow authorized lookup by that identity if the initial response is lost. Within the task: - same identifier and same parameters MUST return the existing operation without reexecution; - same identifier with different parameters MUST fail; - deduplication and lookup MUST still validate project/task authority; - the registry MUST stay in memory only, without restart recovery or replay. Runtime `requestId` correlates a wire call; it is not Studio operation deduplication. Neither transport error nor lost response authorizes blindly retrying an advance. A runtime crash requires an explicit new session, not restoration/replay; task authority remains governed by section 2. ## 7. Runtime Supervision and Canonical Capture Studio MUST resolve `prometeu headless --stdio` from the configured runtime installation. It MUST NOT discover/download another runtime over the network. Missing or incompatible installations MUST fail explicitly. Each process owns one session; each task MUST have at most one active headless session. The gateway MUST validate the runtime's protocol major/minor, real version, required capabilities and effective limits. Incompatible major or missing mandatory capability MUST block the session; compatible minor additions are permitted. It MUST obey complete UTF-8 JSONL framing and separate protocol stdout from stderr diagnostics. Invalid input/schema MUST not disappear silently. The application adapter resolves the executable from `ProjectLocalStudioSetup`, launches it without a shell in the project root, and passes all six effective limits explicitly. Hello and initialize share one handshake deadline. Required hello limits must match the launch configuration; request IDs and session IDs are checked on every subsequent response. Partial lines, invalid UTF-8, duplicate JSON keys, uncorrelated replies and non-monotonic progress invalidate the process. Stderr is drained independently into bounded diagnostics. The runtime-owned surface covers boot/reset, set/clear normalized input, advance, capture, state/fault, cancel and shutdown. Conflicting execution work MUST NOT execute concurrently or be silently queued. Advance MUST preserve requested/completed counts and stop reasons. Cancellation is observed between frames; the current frame retains its deterministic watchdog, not a wall-clock guest deadline. No background realtime game loop is introduced for automation. Reset leaves the runtime unbooted and clears its capture. It does not implicitly boot the cartridge again. A subsequent explicit boot may reuse the session's known build cartridge; an invalidated process requires an explicit new session. | Configurable, handshake-advertised limit | Default | | --- | --- | | Frames per advance | 600 | | Command message | 64 KiB | | Complete response including image/envelope | 32 MiB | | Handshake wait | 5 s | | Headless-call timeout | 60 s | | Cancel/shutdown grace before process termination | 5 s | Oversized requests MUST fail, not be silently clamped. Responses MUST respect their complete serialized limit. Studio MUST supervise external-process deadlines and terminate only its owned process tree if cancellation/shutdown does not respond within the configured grace. Report infrastructure failure and only known progress. EOF closes the headless process; it never resumes it. Screenshot means the runtime's canonical **RGBA8888 framebuffer bitmap**. Capture MUST use lossless PNG/base64 with dimensions, original stride/layout, runtime session, `logical_frame_index` and `FrameId`. These two frame identities MUST NOT be assumed numerically equal. Studio MUST attach build correlation. Both identities retain the full unsigned 64-bit range: Java uses `BigInteger`, and MCP serializes integer JSON values without conversion through floating point. Hashes MAY supplement but MUST NOT replace pixels. No desktop/window screenshot, temporary-image-file transport or continuous video is permitted. The adapter validates base64, PNG signature, RGBA8 header, dimensions and decoded image consistency in memory, then forwards the original PNG bytes unchanged. Its decoder currently guards allocations at 16,777,216 pixels; exceeding this bound fails explicitly rather than resizing or substituting the image. Agent and DEV MUST receive the same capture and correlation for requested advances. DEV MUST identify images from an older build/session as stale during edits/rebuilds. The previous execution MUST stop before rebuilding artifacts that it uses. Capture/build correlation MUST NOT introduce code snapshots. ## 8. Local MCP Admission and Functional Surface Concrete tool names, input schemas, response envelopes and HTTP lifecycle are specified in [MCP Tools and Project Knowledge Contract](11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md). The app MUST host Streamable HTTP at `127.0.0.1:/mcp` while Studio is open. It MUST generate a random token per Studio start, require it on connections, validate Origin and reject unexpected origins. No remote binding, accounts, OAuth or stdio MCP bridge is part of this baseline. Copied configuration MUST contain the actual endpoint/token and MUST NOT be written to versioned files. Instructions MUST explain that restart requires refreshing client configuration. Copying configuration and authenticating MUST NOT grant control. | Tool group | Required capabilities | Required authority | | --- | --- | --- | | Context/references | Project identity, languages, versions, capabilities and paginated references | Authenticated connection; no grant required | | Control | Acquire task and release control | Prior human grant for acquisition; valid task identity for release | | Language | Existing LSP diagnostics/navigation and supported capabilities | Valid project/task identity | | Build | Compile and pack | Valid project/task identity | | Headless | Boot/reset, input, advance, capture, state/fault and shutdown | Valid project/task identity | | Operations | Query, lookup by client request identity and cancel | Valid project/task identity | MCP capture responses MUST expose image content plus structured metadata; clients MUST NOT need to parse logs or fetch a temporary file to obtain pixels. Generic shell, generic file editing, Git, publication and out-of-project changes MUST NOT be exposed as shortcuts around these specialized services. Studio grant does not override the external client's own permission policy or require a new human confirmation for every authorized Studio operation. ## 9. Project Language Context and References The project manifest MUST be authoritative for primary language and dependencies; there is no parallel AI-only language configuration. PBS is the project-creation default, not a fallback for an unknown declared language. Installed compiler/LSP integrations MUST advertise their actual capabilities; unknown versions or capabilities MUST be reported as unknown, not invented. Context MUST include: - explicit project identity/root; - language list and primary designation, with separately identified known language/compiler/SDK versions; - source extensions/scope and actual LSP/build capabilities; - references, examples, libraries and editable versus read-only roots. A one-entry PBS list is valid; extensibility does not require another language or a multilingual compiler. LSP MUST use the existing project server and support project/library navigation through the diagnostics, definitions, references, symbols and other queries/refactorings it actually supports. It MUST NOT advertise nonexistent features or apply edits outside authorized scope. The matching language/SDK distribution MUST ship indexed local quickstart, syntax, semantics, examples and SDK reference material. Consultation MUST work without Studio/compiler checkouts. MCP MUST read references by identifier with pagination, not arbitrary paths. Documentation ownership remains with its language/SDK/library owner; packaging does not create parallel language semantics. Connection guidance MUST describe: connect → consult current project/languages/ references → acquire after human grant → work using saved files and validate through LSP/build → release. The agent need not know PBS in advance. Missing documentation or unsupported language MUST appear as explicit limitations; static copied instructions MUST NOT substitute for current project context. ## 10. Delivery Phases and Conformance Gates The accepted slicing is runtime → DEV/shared services → MCP → integration. No intermediate phase constitutes complete delivery of this specification. | Phase / plan steps | Required gate and limit | | --- | --- | | Runtime, 01–07 | Independent process client proves external contract, deterministic execution, canonical pixels, limits/failures and installed CLI; no Studio/AI dependency | | DEV/shared services, 08–14 | Neutral authority/operations and document handoff first, then DEV; test grant/reclaim, Debug exclusion, dirty buffers, revocation/closure, late calls and FX lifecycle; desktop navigation smoke; doubles only in tests, no fake product endpoint | | MCP, 15–21 | Automated MCP client proves authenticated discovery, real configuration, unauthorized rejection, exclusive acquisition, context/references, operations/deduplication, revocation and image contracts; no model required for this gate | | Integration, 22–28 | Real runtime/LSP/build and an external coding client prove edit → build/pack → boot/input/advance → matching agent/DEV image → release; corrective loops and cleanup preserve manual Debug | Cross-phase conformance MUST prove API/Core neutrality, the unchanged Modulith dependency graph, application startup/shutdown, installed/offline references, packaging and desktop behavior. Real-client tool/image compatibility MUST be verified with the selected client, not promised uniformly across providers. The vertical slice MAY use a simple existing PBS program; a complete game or mature gameplay library is not a prerequisite. ### Decision Traceability | Accepted requirement | Normative location | | --- | --- | | D1 architecture | Section 1 and spec 9 | | D2 runtime; B1–B3 entry/wire/order | Sections 6–7 and runtime-owned protocol | | D3 capture; B4 capture/limits | Sections 5 and 7 | | D4 DEV/authority | Sections 2–5; shell spec and state-restoration exclusions | | D5 files/LSP/write scope | Sections 3 and 9 | | D6 MCP/operations; B5–B7 | Sections 6 and 8; spec 9's HTTP exception | | D7 languages/onboarding; B8–B9 | Sections 8–9 | | Ordered slicing and acceptance | Section 10 | | Accepted exclusions | Section 11 | ## 11. Non-Goals - Embedded agent, chat, provider adapter, provider credentials or cost/budget accounting. - Mirroring external conversation, reasoning or all filesystem activity. - Pixel-art generation, full-game libraries, audio capture or deep guest introspection. - Shared editing, isolated worktrees, code snapshots/journals/checkpoints, merge/apply, divergence recovery, undo/rollback or automatic commits/clean-tree gates. - Replacing compiler, Packer, LSP, VM or human Debug semantics; a new general-purpose Studio source editor. - Remote MCP, accounts/OAuth, stdio MCP bridge, network runtime discovery or provider-specific connection wizard. - Additional language implementation, persistent operation recovery or automatic task resumption. - Integrated discussion-framework agendas/decisions/plans in the product; those are future work, not this runtime/DEV/MCP contract. ## Exit Criteria Implementation is conformant only when all phase gates hold and: 1. Human grant, task acquisition, operation outcome and authority return are distinct and tested. 2. Service-level guards prevent conflicting manual work from grant through cleanup without blocking read-only navigation globally. 3. Save failure prevents grant; successful return refreshes documents without overwriting agent edits. 4. Revoke invalidates old calls first, works while waiting and preserves edits; project/application closure cleans owned processes and never restores authority. 5. DEV and the agent see the same canonical image with explicit build/session/frame correlation and stale labeling. 6. Local transport authentication does not bypass project/task authorization or scope restrictions. 7. Lost operation responses cannot duplicate execution; runtime crash cannot trigger replay or implicit authority release. 8. Language context and indexed local references reflect real installed support and work without source checkouts. 9. Manual Debug, architecture boundaries, packaging and real-client integration pass their regression gates.