Files
prometeu-studio/docs/specs/studio/10. DEV and Automation Specification.md

393 lines
24 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
The application-owned project-session factory tracks sessions and closes all of
them before its LSP/executor dependencies are destroyed, including sessions not
currently represented by a window. Closing one project removes it from that set;
application teardown rejects new opens and attempts every remaining project even
if another close reports failure.
If shutdown required forced termination, the first return attempt reports cleanup
failure and retains the manual guard. A subsequent explicit human reclaim may
acknowledge cleanup only after the gateway confirms that its owned process tree
is dead. A cached failed shutdown must not make a dead session permanently
unreclaimable. Cancellation racing a process crash must still allow the owner to
await worker termination and shutdown; it must not bypass that cleanup sequence.
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:<OS-assigned-port>/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.