361 lines
22 KiB
Markdown
361 lines
22 KiB
Markdown
# 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 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.
|
||
|
||
| 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.
|
||
Hashes MAY supplement but MUST NOT replace pixels. No desktop/window screenshot,
|
||
temporary-image-file transport or continuous video is permitted.
|
||
|
||
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.
|