Files
prometeu-studio/docs/specs/studio/11. MCP Tools and Project Knowledge Contract.md
T
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
Add shared human/task asset batches with reviewed atomic publication, explicit
reference rebinds, ownership inspection and qualified glyph/scene budgets.
Expose the same authoring and capacity results through Assets and MCP.

Deliver isolated guest test targets, retained visual evidence and immutable
runtime lifecycle/control observations. Preserve provider qualification and
installed authoring examples alongside the completed discussion lessons.

Close AGD-106 coordination and the delivered discussion workflows through
housekeeping, updating lesson references and preserving qualification limits.
Sound remains outside the asset delivery wave.

Validation: 579 module tests and 31 additional desktop, process and installed
checks passed; native glyph/scene 16/17 boundaries qualified. Discussion
validation passed after housekeeping.
2026-11-11 01:21:25 +00:00

57 KiB
Raw Blame History

MCP Tools and Project Knowledge Contract

Status, Scope and Authority

Owner: studio, application adapter and neutral automation API. This document formalizes DEC-0060 B5–B9 and the integrated connection revision in DEC-0061 (PLN-0140). It complements DEV and Automation, which owns project authority, lifecycle, captures and phase gates. It does not change those rules or the runtime-owned headless protocol.

The packaged machine-readable input schemas, authority classification and examples are in prometeu-app/src/main/resources/mcp/studio-tools-v1.json. Contract version is 1.0. Catalog membership is not runtime availability: HTTP tools/list MUST expose only composed handlers, never placeholder implementations. The offline Studio stdio entry MUST advertise the packaged catalog and report unavailable live capabilities explicitly. Steps 17–21 connect the functional providers and DEV configuration assistance; steps 22–28 provide the real runtime gateway and integrated acceptance.

1. Connection Contract

The app hosts /mcp on 127.0.0.1 with an OS-assigned port, using the JSON response form of MCP Streamable HTTP, protocol revision 2025-06-18. The initialization exchange negotiates that supported revision; no compatibility with other revisions or deprecated HTTP+SSE transport is claimed. An offered unsupported revision receives the supported revision in InitializeResult.

Each desktop start generates a new instance identity. Each human project grant publishes a fresh 256-bit bearer credential scoped to that canonical project root. Every HTTP request MUST include Authorization: Bearer <credential>; missing, wrong or revoked credentials return 401. Initialized HTTP sessions MUST be bound to that credential/root; mixing another credential with an existing session returns 403. All tools, including knowledge reads, MUST enforce the authenticated root before dispatch. No instance-wide credential bypass is permitted.

There is no query-string token, OAuth, cookie authentication, remote bind option or wildcard listener. The endpoint has no query parameters. Studio also provides its own stdio mode, described below; it is part of the same artifact.

Native clients may omit Origin. If present, it MUST exactly equal the live endpoint's origin (http://127.0.0.1:<port>); null, other ports/hosts/schemes and multiple Origin headers fail. Host MUST match the live loopback authority. Unexpected origins/hosts return 403. No permissive browser CORS policy is emitted. Credentials MUST NOT appear in diagnostics, exception messages, object string representations, generated reports or versioned configuration. The project discovery file is the only secret-bearing setup output; persistent client configuration and clipboard assistance MUST NOT export secrets.

Initialization assigns a separate random Mcp-Session-Id. Subsequent requests include this header and the negotiated MCP-Protocol-Version. The server can recover the negotiated version from its connection session if the version header is absent; an explicitly unsupported header returns 400. Missing required session returns 400; an unknown/closed session returns 404. The client sends notifications/initialized before tools. ping is available after initialization.

POST requires UTF-8 JSON and Accept support for application/json and text/event-stream. Responses use JSON, not SSE. GET returns 405. DELETE closes only the connection session, not project authority. Accepted notifications and client responses return 202 without a body. Notification/disconnection alone MUST NOT revoke a task or cancel an operation already returned by operationId.

The transport bounds incoming bodies to 1 MiB, sessions to 128 and request handling to a bounded worker queue. Oversized bodies return 413; exhausted session capacity returns 503. Stalled exchanges close after 15 seconds. These are HTTP resource protections, not task expiration or guest/runtime timeouts. Build/advance MUST return operation identities promptly. A lost response is resolved by authorized lookup, not by assuming cancellation or replay.

These details follow the official MCP transport, lifecycle and tools contracts. Optional SSE, server-initiated requests, sampling, prompts, resource subscriptions and list-change notifications are not advertised.

1.1 Integrated Studio Entry and Offline Catalog

StudioLauncher mcp --project <absolute-root> MUST dispatch before JavaFX or Spring desktop startup. The root MUST be canonicalized once, contain the project manifest and remain bound for the process lifetime, independently of client cwd. The mode MUST NOT open a desktop, LSP, runtime or another HTTP listener. It uses newline-framed UTF-8 JSON-RPC on stdin/stdout; stdout is protocol-only. Requests are bounded to 1 MiB. EOF closes transport resources without releasing task control.

Initialize, initialized notification, ping and tools/list MUST work before the desktop, descriptor or grant exists. Offline descriptors come from the same packaged catalog as HTTP. A deterministic fingerprint covers protocol and tool schemas. Before forwarding, the connector MUST validate the descriptor, initialize HTTP, check instance/root/fingerprint metadata, and compare live descriptors with the packaged catalog. Missing handlers return unsupported capability; incompatible protocol/schema fails explicitly rather than silently changing the client's tools.

Tool calls MUST preserve structuredContent, text/error blocks and native image blocks. Response bounds MUST support images above the 1 MiB request limit; the current response cap is 32 MiB, including a bounded body-read deadline. Network redirects MUST NOT be followed. The connector MUST reject another project root.

Discovery runs on calls and bounded background checks. Missing publication means waiting for access, not proof that the desktop is closed. Distinguish invalid file/permissions, stale credentials/instance, catalog incompatibility and transport reconnection. Calls cannot wait indefinitely for a grant. No reconnect path may resubmit a tool call. An uncertain response MUST retain available clientRequestId correlation and instruct receipt lookup within the same authorized task. A new desktop/task has no old receipt registry and requires a fresh human grant.

1.2 Stable Installation and Project Preparation

The initial delivery targets Codex on macOS. Studio owns a versioned installation under ~/Library/Application Support/Prometeu/Studio, with an atomic current reference. Each version includes lib dependencies and a compatible Java runtime under runtime. Validate a staged version before switching current; retain previous versions for rollback and already-running processes. Failed validation MUST leave the existing reference intact. Registered commands MUST work without an interactive shell PATH, external JDK or developer checkout.

The client command is the absolute current/runtime/bin/java, with argument-array values -cp, <current>/lib/*, p.studio.app.StudioLauncher, mcp, --project, and the canonical root. No project-local executable, generated transport script, helper binary or separate launcher installation is allowed. The desktop and connector use the same Studio artifact. JDWP is an explicit development-only JVM option; IntelliJ attaches to the client-owned connector process separately from the desktop Debug configuration.

New-project scaffolding and existing-project preparation MUST use the same neutral preparation port. .studio/setup.json stores integration schema/enabled/profile intent, preserving runtime/editor settings; it contains no endpoint/credential/task. Application infrastructure owns .codex/config.toml serialization. Its managed mcp_servers.prometeu_studio table stores the stable command, arguments, project cwd and cold-start timeout. Preserve all unrelated tables, comments, approval policy and server entries byte-for-byte; validate edits with a TOML parser. Repetition with identical values MUST be a no-op. User-owned or modified managed entries and tracked client configuration MUST produce an actionable conflict, never an overwrite. Keep a protected recovery copy of the previous owned block without copying unrelated secrets. Precise ignore rules protect machine-local client configuration and transient discovery without deleting existing rules.

Preparation MUST report incomplete writes/installations truthfully. Trust/reload instructions apply to initial client registration only; no client trust or tool approval may be bypassed. Grant and desktop restart MUST NOT require changing the client configuration. A clone is prepared locally to resolve its own installation and project paths. No global client configuration is rewritten.

1.3 DEV Connection Assistance

DEV MUST expose preparation/readiness through neutral API contracts and show connection status separately from Core authority. Waiting for access, connected and reconnecting derive from project-scoped initialization/ping activity with a bounded liveness window; a retained HTTP session ID alone is insufficient. Working remains an authority/operation state. DEV MUST NOT invent knowledge of a client before it connects. A transport drop MUST NOT revoke a task or grant new control.

Preparation, labels, clipboard, diagnostics and history MUST NOT expose secrets. Closing/hiding DEV only unsubscribes visual listeners. Human grant/reclaim and project/application teardown retain their shared Core semantics. Instructions cover native file edits, project knowledge, grant/acquire, validation, receipt lookup, images and explicit release without generated transport clients.

2. Identity and Admission

All tool inputs require projectRoot: an absolute filesystem root resolving to an open project. UI focus never supplies it. Core services resolve the actual project, including canonical-path/scope checks; syntactic validation does not prove authorization.

The authority levels in the packaged catalog are:

  • authenticated: connection authentication only; project/context/reference reads need no acquired task. HTTP access still requires the project credential published by human grant. Offline catalog discovery returns no task token.
  • granted: acquisition validates the prior human grant and atomically creates the sole task identity. The transport session ID is not that identity.
  • task: projectRoot and taskId must identify the current acquired task. Revalidate before admission, lookup and deduplication, including read-only LSP.

No MCP tool grants human permission or simulates pressing the DEV button. There are no arbitrary-file read/write, shell, Git or publication tools. Editing uses the external client's native tools within the context's editable scope.

3. v1 Tool Catalog

Fields below supplement projectRoot, and taskId where authority is task. Input objects reject undeclared fields. IDs are nonempty opaque strings.

Tool Authority Additional input Successful value
studio_project_context authenticated none Project context in section 5
studio_reference_read authenticated referenceId; optional offset/limit Indexed reference page
studio_control_acquire granted none taskId, state=AGENT_WORKING
studio_control_release task none state=MANUAL, only after ordered cleanup
studio_language_query task operation, parameters Supported LSP query/proposal result
studio_build_start task clientRequestId operationId, clientRequestId, state
studio_headless_boot task buildId, optional memcard/memcardChoice sessionId, buildId; boot uses the task's known build
studio_headless_reset task optional discardUnsaved/pendingWrites Current session/reset state and negotiated memcard state
studio_headless_set_input task input Current session acknowledgement
studio_headless_clear_input task none Current session acknowledgement
studio_headless_advance task clientRequestId, frames operationId, clientRequestId, state
studio_headless_capture task none Canonical image and metadata in section 6
studio_headless_state task none Current session and runtime state
studio_headless_fault task none fault object or null, preserving structural fault details
studio_headless_shutdown task optional discardUnsaved/pendingWrites Session shutdown acknowledgement/final memcard state after managed cleanup; native refusal preserves session
studio_headless_memcard_state task none Native media/session/dirty/request/IO/recovery state
studio_headless_memcard_mount task action, access, optional path Explicit idle open/create through the provider
studio_headless_memcard_unmount task none Explicit idle media release
studio_headless_memcard_reconcile task none Runtime-owned same-card revalidation while suspended
studio_headless_memcard_continue_in_memory task none Explicit runtime-owned RAM continuation while suspended
studio_operation_get task exactly one of operationId/clientRequestId State, known progress, typed result/failure
studio_operation_cancel task operationId operationId, cancellationRequested

Boot MUST NOT accept an arbitrary cartridge path. The shared service resolves buildId to known project artifacts. Runtime limits/capabilities come from the actual runtime, not fixed MCP promises. Frames is a nonnegative integer (zero is valid); values beyond effective limits fail rather than being clamped.

Input is a replacement snapshot: booleans up/down/left/right/a/b/x/y/l/r/start/ select/touch, signed 32-bit touchX/touchY. Omitted fields reset to false/zero. It preserves the runtime's normal sampling/edge semantics, not UI keyboard events.

Language queries use the capabilities returned by project context. Parameters may contain URI, zero-based UTF-16 position/range/positions, workspace query, newName, includeDeclaration or task-local itemId for multi-stage queries. The provider MUST validate the parameters needed by the selected operation and reject unsupported operations explicitly. Diagnostics, definitions, references and symbols reuse the existing project LSP. Other queries/refactoring proposals are exposed only when supported; returned edits MUST respect project versus read-only SDK/library scope. No query applies filesystem edits.

3.1 Language Query Operations

studio_language_query uses the existing project's LSP server via a real client, not a parallel language implementation or a direct call into compiler semantics. Its successful value is {operation, result, limitations}. result is the JSON projection of the existing LSP response (including null or an empty list when appropriate); LSP union wrappers are unwrapped. Provider classes remain inside the application adapter. Studio API/Core use maps, lists and scalar values only.

Operation Required parameters beyond projectRoot/taskId
diagnostics, documentSymbols, documentLinks, foldingRanges, formatting, semanticTokens parameters.uri
hover, completion, signatureHelp, definition, references, prepareRename, prepareCallHierarchy uri, position; references optionally accepts includeDeclaration
rename uri, position, newName
workspaceSymbols optional query; no document URI is needed
selectionRanges uri, nonempty positions
codeActions uri, ordered range; diagnostics are obtained from the current saved file
incomingCalls, outgoingCalls task-local itemId from a hierarchy result

Support MUST be checked against the running server's initialize response before dispatch. Unknown operations, including currently unsupported type hierarchy, return UNSUPPORTED_CAPABILITY. Context publishes the installed provider's capabilities, including semantic tokens; hierarchy and rename preparations use their corresponding server capability. Positions are zero-based UTF-16 offsets, must fit the saved file and must not split surrogate pairs. Reversed ranges and missing operation-specific parameters are rejected.

The application lifecycle supplies each open project's bound loopback LSP endpoint. Studio uses OS-assigned ports so different open projects do not compete for one fixed port. The public LSP configuration default remains unchanged for other hosts. A manifest language change requires reopening that project's server; the adapter MUST NOT send queries to a server bound to another language/root.

Each query uses a short-lived client connection. For physical document requests, the adapter opens exactly the saved UTF-8 text and waits for that connection's published diagnostics before issuing the semantic query. Other dependency files are read from disk by the existing compiler bridge. A fresh connection prevents reuse of stale overlays from previous requests or the human editor. Unsaved or concurrent external writes remain the developer's responsibility.

Queries require the current task, share the project's work admission/cancellation and DEV operation observation, and do not silently queue behind conflicting work. Return/reclaim invalidates the task immediately, waits for worker termination, then clears task-local hierarchy items before manual control is restored. Item IDs from another task or project cannot be used. Client sockets/listeners close on success, failure, timeout or cancellation; project-server shutdown closes its accepted sockets and executor. A lost client does not independently grant control.

The adapter bounds connect time to 2 seconds within the shared 10-second admission-relative execution budget, followed by a 2-second cleanup response window; Core bounds the request worker wait to 12 seconds. Documents are limited to 4 MiB of UTF-8 and task-local hierarchy state to 1024 items. These are adapter resource guards, unrelated to the runtime's deterministic frame/watchdog semantics.

Document URIs must resolve to known physical project/dependency source files or to an external identity owned by the current task and project. Symlink targets are canonicalized before admission. External sources may be queried, but edit-producing queries on read-only roots are rejected. Every URI in returned workspace-edit proposals is checked against the same editable/read-only scope; an unsafe proposal is rejected as a whole. File-operation edits and executable commands are not offered; workspace/applyEdit is always refused. No query writes a file. readExternalSource reads the exact registered external revision; hover and definition on its URI use the retained frontend semantic context. Indexed SDK reference tools remain separate and available. MCP needs no VS Code connection and MUST retain its consumer across short-lived query sockets. Task return/cancellation releases that task's external uses; project shutdown invalidates all identities. Cross-task/project replay is refused.

External-source protocol (DEC-0062)

Initialize negotiates capabilities.experimental.prometeuExternalSources: true; the server advertises the same flag only when supported. External definitions use prometeu-source: URIs minted by the project host. A descriptor carries uri, revision (content digest), origin, name, languageId and readOnly: true. Locations carry ordinary LSP UTF-16 ranges over that exact source text.

The prometeu/readExternalSource, prometeu/retainExternalSource, prometeu/releaseExternalSource and prometeu/revalidateExternalSource requests carry uri and a server-issued consumerId. Initialize returns that identity in capabilities.experimental.prometeuExternalConsumerId. Reconnecting clients pass it as initializationOptions.prometeuExternalConsumerId; MCP also requests initializationOptions.prometeuExternalPersistentConsumer: true on first use. releaseExternalSource with uri: null releases the consumer and all its sources. A read or explicit retain acknowledges a navigation result; unacknowledged results are released when the socket closes. MCP acknowledges returned definitions before closing its query connection and rolls back newly retained results on failure. Read-only edit refusal uses LSP error -32010, mapped to MCP READ_ONLY_SCOPE. Consumer identity is scoped to the project session; the MCP adapter additionally binds it to its authorized task. Read returns the descriptor plus text. Retain/release are idempotent per consumer. Revalidation confirms the same admitted origin and revision before queries resume; a changed revision reports unavailable and requires new navigation. Unknown, expired, unauthorized and unreadable sources are explicit errors, never disk reads chosen by client paths. Consumers are created by the server, not caller-selected.

VS Code uses a read-only text content provider, with the source language and no save-back path. Disconnect may leave the immutable text visible, but blocks semantic queries until revalidation. No content-change event may replace the old revision under old positions. Closing the last consumer releases the snapshot; one reader closing must not invalidate another reader. Edit operations and mixed workspace edits are rejected in their entirety, including physical aliases. Packaged Studio validation is excluded from this delivery; development tests must exercise both VS Code and independent MCP navigation.

4. Result, Error and Operation Contracts

Successful tools return isError:false with structuredContent {"status":"ok","value":{...}}. Domain/admission failures return isError:true with {"status":"error","error":{"code":"...","message":"..."}}. Both include a text content block serializing the same structured data for clients that do not render structuredContent. Clients use error codes, not parsed prose.

AutomationFailure.Code defines domain codes, including project-not-open, not-granted, invalid-task, busy, unsupported language/capability, missing reference/documentation, out-of-scope/read-only scope, missing operation/build/ runtime session, duplicate-ID parameter conflict, unavailable/incompatible runtime, missing frame, exceeded limit, not-cancelable and infrastructure failure. Unknown methods, malformed JSON-RPC and schema-invalid arguments remain protocol errors (-32601, -32600/-32700 and -32602); unexpected internals use sanitized -32603 responses, never request bodies, stack traces or credentials.

Build failure and guest fault are operation outcomes, not implicit release. TrackedOperation carries the existing OperationSnapshot, clientRequestId, known progress and either the existing typed build result or runtime outcome. Unknown requested/completed frame counts are null. Terminal infrastructure failure/cancellation MUST preserve only known progress. Cancellation acknowledgement does not assert worker termination or grant manual control.

The wire receipt flattens operationId/state from the neutral operation snapshot. Polling additionally returns progress and typed result/failure; incomplete results are null. Build results retain diagnostics/artifact correlation. Runtime results retain requested/completed frames and distinguish success, guest fault, termination, cancellation and infrastructure failure. Captured results include the same MCP image block used by direct capture.

clientRequestId deduplication is task-local and in-memory. Same ID plus same effective parameters returns the same operation; changed parameters fail with CLIENT_REQUEST_CONFLICT. Operation lookup accepts exactly one key. Revoked, cross-project or old task identities cannot read/cancel cached work. Neither MCP JSON-RPC IDs nor runtime requestIds replace this identity. Restart never restores the registry, replays an advance or recovers authorization.

4.1 Task Work and Correlation

TaskTools is the neutral service surface; MCP only validates schemas and projects its results. The Core implementation admits work through AutomationSession.submit and the existing operation executor, sharing DEV's busy state and cancellation. Acquisition requires the prior human grant. Release reports MANUAL only after managed cleanup and document refresh succeed; cleanup failures remain explicit.

Admission and request registration are atomic per project. Deduplication uses the operation kind and effective parameters, including requested frames. It is checked after task authority and before busy/active-runtime validation, so a repeated accepted start still resolves its original operation after that work has ended. Rejected starts do not reserve clientRequestIds. Distinct requests cannot silently queue behind busy work. Other projects remain independent.

Polling returns workerTerminated separately from operation state. CANCELLED may acknowledge interruption before the worker exits; it does not permit another conflicting operation or manual control. Final results remain null until worker termination. Progress contains only provider-reported counts and can be unknown. A cooperative final capture is published to DEV before termination while the task is still valid. A revoked task cannot publish a late frame or retrieve cached work. Historical operation images are marked stale when they no longer match DEV's current session/build/frame, or DEV has marked that capture stale.

Build executes the same saved-project compiler/packer preparation as manual Shipper, under task admission rather than a manual lease. It checks cancellation between compilation, validation and packaging phases. A successful build receives a task-local buildId; failed builds retain typed diagnostics and do not release control. Before rebuilding, the managed runtime must finish shutdown and detach. Old buildIds are invalidated before overwriting artifacts, including when the new build fails. This is artifact correlation, not source snapshots or recovery.

Headless handlers consume a neutral HeadlessGateway session port. Boot accepts only a current successful task build; one runtime session may be attached at a time. Input is normalized to a complete replacement snapshot. Advance limits come from that session and are enforced without clamping. Shutdown detaches only after managed cleanup finishes. Runtime process supervision and protocol mapping belong to the application gateway delivered in step 22, not to MCP or the test doubles.

Reset leaves the attached process unbooted, marks the previous capture stale and retains its build association. A subsequent explicit studio_headless_boot with that same current buildId reboots the known cartridge within the session. Boot without reset while a runtime is attached is rejected as busy. Reset does not change task authority or implicitly start execution. Rebuilding ends and detaches that process, invalidates previous buildIds and requires a fresh explicit boot. Synchronous headless failures finish their worker before returning the error, so a corrective call cannot race the failed worker's admission lock.

Memcard boot options are local host configuration, never an arbitrary cartridge path. memcard contains explicit action/access and optional image path; memcardChoice is an explicit provider choice. Protocol 1.1 plus capability memcard is required before mutation. MEMCARD_ERROR preserves native operation/reason/state in runtimeError. Refused reset/shutdown keep the attached session and task available for inspection and a later explicit choice. discardUnsaved and pendingWrites are forwarded only when supplied. Neither ordinary Stop/task release nor connection loss supplies discard consent. See published memcard host integration for local paths, protected human reclaim and ACTION_REQUIRED outcomes.

Task-local operation/build records are discarded after worker termination on return, revocation or project closure. Cleanup failures never restore authority; the records are still discarded after managed work stops. Neither connection disconnect nor polling silence discards an authorized task's records.

Structured runtime observation and recovery

studio_operation_get.value.observation is the immutable operation-final observation, published after worker termination. currentObservation is a separate passive session snapshot and may describe later reset/rebuild/shutdown. Both retain available project/task/operation/request and session/build identity; native request identity remains separately correlated. A follow-up lookup MUST NOT execute another advance or rewrite the original frame/progress/cause.

Headless replies and failures include an observation when available. Its fields are sessionId, buildId, lifecycle, source, observedAt, progress, lastFrame, captureStale, nativeDetails, context, unavailable and recovery. Native snapshots in nativeDetails retain their own observation provenance. Unsigned frame identities are lossless; unknown completed progress is null. unavailable preserves failed inspection separately from the original error. Human diagnostics do not replace structured fault/error/media payloads.

Lifecycle values are ABSENT, UNKNOWN, UNBOOTED, BOOTED, GUEST_OBSERVED, LOST and TERMINATED; the last two describe process availability. Native guest status remains a separate observed fact. Every recovery action has preconditions and automatic: false. Available actions describe inspection, original-operation lookup, explicit boot after reset or explicit new-session creation after loss. They never authorize replay or media discard.

Acquire/release successes expose control; release failures preserve the same authority/cleanup facts in error.details.control and the native cleanup cause where available. Task revocation is independent of cleanup success. The authenticated studio_project_context includes current control and runtime without admitting work under a revoked task; unavailable connection authentication still requires human inspection/fresh grant. Embedded read-only contexts without an automation service report null observations and an explicit limitation.

The installed guide MUST cover reset → boot with the same buildId → intentional advance, explicit disposable media, known zero versus unknown progress and lost response lookup with the original clientRequestId. A native refusal is not success; RAM-only continuation or accepted commit is not proof of durable persistence.

5. Project Knowledge DTOs

Neutral ProjectKnowledge.Context contains projectRoot/projectName, languages, libraries, editableRoots/readOnlyRoots, indexed references and explicit limitations. Its source is the project manifest and installed providers, never an AI-only file.

Each language includes id/primary, separately identified languageVersion, compilerVersion and sdkVersion, source extensions/roots, real capabilities and reference IDs. Version has value and source; unknown value is null with source unknown. Capability support distinguishes SUPPORTED/UNSUPPORTED/UNKNOWN and can explain a limitation. Unknown declared language MUST NOT fall back to PBS.

Libraries include identity, known version, roots and whether they belong to the editable project. External libraries and SDK remain read-only. Reference entries identify id/title/owner/kind/version; kinds include QUICKSTART, SYNTAX, SEMANTICS, EXAMPLE, SDK and LIBRARY. Indexed content belongs to its language/SDK owner.

Reference reads take an opaque ID from that index, not a path or arbitrary URI. Offset defaults to 0; limit defaults to 4000 and accepts 1–16000 Unicode code points. A page returns referenceId, offset, total, text and nextOffset (null at end). Invalid pagination fails; unknown/traversal-like IDs cannot escape the index. Installed reference content is resolved through the frontend's owner-maintained reference provider, not a Studio-maintained language specification.

5.1 Manifest and Provider Resolution

studio_project_context resolves an exact, canonical root registered by an open project session. It does not use the focused window, accept a source-directory path as a project root, acquire a manual lease, or acquire task authority. The HTTP boundary separately requires the grant-published project credential. A session is discoverable only after successful opening and until closure begins. Unregistered/closed roots return PROJECT_NOT_OPEN.

Each call reads the saved prometeu.json and dependency manifests again. Missing or invalid primary manifests fail explicitly instead of returning cached language metadata. Languages are grouped by declared ID, with the primary flag derived from the main manifest. Unknown IDs retain their identity and expose unsupported build/LSP support; no default frontend is consulted.

Extensions and source roots come from the installed frontend specification. LSP feature support comes from the same compiler bridge description used by the existing LSP server, not from a duplicated PBS capability list. If that provider cannot describe its LSP, support is UNKNOWN with an explicit limitation. These are installed-provider capabilities, not a promise that the MCP language-query tool is already composed or that any particular source file will compile.

Language versions remain unknown when no owner metadata exists. Compiler versions use the installed frontend package's Implementation-Version only when present. The requested SDK version has manifest provenance; the context distinguishes versions supported by the installed provider from unsupported requests. Multiple SDK requests for the same language yield an unknown aggregate version, an explicit limitation and separate SDK library entries. These identifiers MUST NOT be substituted for one another.

Dependency paths and registry entries use the compiler's existing resolver, including its main-root-relative local path semantics and registry requirement. Discovery does not create a registry, install dependencies or build sources. Unresolved declarations remain visible with empty roots and limitations. Mixed language graphs are described but reported as unsupported for the current build pipeline. Discovery is bounded to 256 projects and 256 declarations per manifest.

The editable scope is the canonical project root minus read-only roots. Read-only scope takes precedence: external/registry libraries and their transitive dependencies remain protected even when stored beneath the project root or also reachable through a local declaration. Source roots are canonicalized, including symlink targets. SDK entries are always read-only; packaged SDK resources need not have filesystem roots. Scope metadata does not sandbox an external agent's own filesystem tools; the developer remains responsible for those tools and Git.

Paths in MCP results are absolute filesystem strings, not file: URIs.

5.2 Installed References and Pagination

An installed frontend MAY implement FrontendReferenceProvider through FrontendProvider.documentation(). That compiler-side contract supplies indexed, owner-maintained texts for an SDK major and project target. It does not depend on Studio API or MCP. Studio projects these into neutral reference descriptors; full texts MUST NOT be included in project context. Reference IDs are namespaced by language (<languageId>:), unique within the selected project index and opaque to callers. Studio MUST NOT interpret an ID as a filename, URI or URL.

PBS packages its numbered specifications and informative quickstart from their owner directory, plus a compilable Game example and actual SDK sources/barrels. A build-generated index binds these texts to the installed frontend using content hashes. Distribution-only reads MUST work without a checkout or network. SDK and example references identify their SDK major and target; unsupported selections MUST NOT silently reuse another SDK/target. Numbered spec/draft revisions and the reference-index schema revision MUST NOT be reported as language/compiler versions.

studio_reference_read is authenticated but does not require an acquired task; the transport still requires a grant-published project credential. It resolves the explicit open root and its current saved manifest selection on every read. Changing SDK/target can invalidate previously advertised IDs. Only IDs in that project's installed index can be read, including when other languages/providers are installed globally. SDK and external-library texts remain consultable, not editable through this surface.

Pagination counts Unicode code points: an astral character occupies one offset, not two UTF-16 units. Offset 0/limit 4000 are defaults; limit MUST be 1–16000. An offset equal to total returns empty text and null nextOffset. Offsets beyond total, negative offsets, nonintegral values and integers beyond the implementation's signed 32-bit range are invalid parameters, never wrapped/truncated to another page.

Missing or unreadable provider documentation yields DOCUMENTATION_UNAVAILABLE limitations, not promised references. An uninstalled primary language yields UNSUPPORTED_LANGUAGE for reference reads; an available index without the requested ID yields REFERENCE_NOT_FOUND. Closed projects yield PROJECT_NOT_OPEN before reference lookup. These failures do not grant/revoke task authority.

6. Image Contract

MCP image content has type:image, mimeType:image/png, and base64 data of the unchanged CanonicalCapture.png bytes. No screenshot, log scraping, temporary path or network fetch is required. The structured value includes sessionId, buildId, logicalFrameIndex, frameId, width, height, stridePixels, pixelFormat RGBA8888, mimeType and stale. Stride describes the original framebuffer, not PNG compression/padding. Logical and render frame counters are independent.

The adapter MUST NOT invent a frame when none exists or substitute another session's image. The same neutral capture feeds DEV and MCP. Real runtime production/cross-language equality is verified by the phase 4 desktop integration gate below; encoding test pixels in contract tests alone does not satisfy it.

7. Conformance and Delivery Boundary

Contract tests validate every tool's example, authority level, required project/ task IDs, invalid types/unknown fields, exclusive operation lookup, input ranges, pagination, result envelopes, PNG bytes and independent frame identities. HTTP tests use a real loopback listener/client and exercise initialization, authentication, Origin, endpoint/method/version handling, tool dispatch, malformed or oversized input, closure, restart and old-token rejection. Provider doubles exist only in tests. Composition starts/closes transport with Studio.

The production registry composes 22 tools, including five negotiated memcard controls and the original headless handlers bound to the actual HeadlessProcessGateway. Missing project runtime configuration fails at boot with RUNTIME_UNAVAILABLE; tool discovery does not grant authority or launch a process. No fake runtime is shipped. The former configuration-copy flow is superseded by DEC-0061 permanent preparation and grant-time discovery. The automated HTTP conformance gate exercises all 17 tool contracts using real project knowledge/LSP and test-only build/runtime ports; a separate HTTP test uses the real compiler/packer. This completes MCP-phase conformance. The packaged-runtime gate additionally exercises actual app composition, project LSP, compiler/packer, saved edits, explicit reset/reboot, build identity invalidation and corrective loops after compile errors/guest faults.

Step 24 adds headlessMcpDesktopTest: a real HTTP client drives the composed app, installed compiler/packer/LSP and packaged Rust runtime, while the actual JavaFX DEV view observes the shared session. An independent test-only JSONL client runs the same saved cartridge and input timeline in another real process, without the Studio process adapter or capture DTOs. Raw PNG bytes and each capture metadata field match MCP; all decoded framebuffer pixels and the visible identity/stale labels match DEV. State/fault and deterministic reset/fresh-session repetitions are also checked. Rebuilding changes pixels/build identity and visibly marks the old capture stale. Images remain in memory; window screenshots are not evidence.

The fixture uses supported project-source LSP definition/symbol navigation and indexed SDK reads. The historical probe of the former SDK Input.pad() definition returned an empty result (the current facade is Pad/Button and Touch); the gate does not claim SDK symbol navigation where no location is returned. This is a language tooling limitation, not a headless or MCP execution fallback.

Step 25 extends that real desktop/HTTP gate with active-operation cancellation, connection deletion/reconnection and duplicate receipts, waiting/active revoke, late-call rejection, project closure/reopening and application-context shutdown. A controlled document participant delays refresh acknowledgement to prove that manual control remains blocked until process cleanup and disk refresh complete; it also checks that no revoked frame or old source buffer is applied afterward. The real runtime is killed or suspended in test-owned processes to verify known progress, no implicit restart/replay, forced cleanup and explicit human retry. Compile errors and guest faults are corrected over HTTP within the same task. The normal desktop Debug process starts after release and blocks a new grant. The suspension/manual-Debug scenarios require a POSIX desktop and a free Debug port 7777; the gate never attaches to an existing user's Debug process.

The automated client is not an external coding agent. Separate acceptance on 2026-09-29 used Codex CLI 0.158.0 against the packaged Studio and runtime 0.1.0 on macOS ARM64. The agent consulted references/LSP, edited saved PBS source, built/packed, consumed native MCP PNGs, tested 1,110 frames of directional input, and explicitly released authority. The developer confirmed DEV and then ran the edited game through manual Debug Play. This establishes compatibility for that client/platform, not uniform compatibility across providers or operating systems.

Full regression and distribution gates also passed: installed offline references, real runtime protocol tests, architecture/Modulith, and two isolated startup/stop cycles using the extracted Studio ZIP. The latter verified listener closure and old-credential rejection after restart. API/Core and JavaFX MUST NOT import MCP/HTTP implementations; architecture tests enforce it. Consolidated acceptance evidence and deferred findings live in the DSC-0068 lesson, not in temporary logs.

Integrated Connection Acceptance (DEC-0061)

Prior DSC-0068 native-client evidence covers the original HTTP flow only. The integrated flow additionally requires a real native Codex session initialized before grant, unchanged configuration through desktop restart/new grant, native images/build/release, scaffold and existing-project preparation, installation update and graphical launch, plus IntelliJ connector attachment. Automated fixtures cannot substitute for these gates. PLN-0140 completed automated validation and the user confirmed all outstanding manual gates on 2026-09-29. The manual confirmation is user-reported acceptance, not an independently observed test run. LSN-0077 preserves the result and evidence provenance after workflow housekeeping.

Automatic preparation when opening a project

Opening a project MUST prepare its enabled MCP integration using the same neutral port as scaffold and DEV retry. Desktop composition MUST start the shared loopback server before project sessions become available; no external command or separate per-project desktop Run is required. Explicitly disabled integration MUST remain disabled. Preparation failure MUST remain visible in DEV readiness without blocking project use. Opening MUST NOT publish credentials or grant/acquire agent control. The coding client continues to own its configured stdio process and initial trust.

Animation integration contract

Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.

See the complete animation contract.

Explained diagnostics and same-analysis LSP extension

The existing tools remain the entry points. studio_operation_get adds issues/summary/context to its build result; studio_language_query preserves operation/result/limitations and adds analysis/context. AutomationFailure adds neutral details. runtimeError remains reserved for native runtime data. Result fields and errors are declared in mcp/studio-tools-v1.json.

Correlation uses the applicable projectRoot/taskId/operationId/clientRequestId/queryId/analysisId/buildId. queryId identifies the admitted synchronous language query; it does not imply a new persisted operation registry. source FileId remains compilation-local and is qualified by analysis/input identity. Context identifies actual observed source inputs with SHA-256, language/SDK/target/profile values and honest partial coverage. A per-connection version=1 is not a global disk revision. Configuration values without a captured manifest-byte revision and pack/assets inputs MUST remain explicitly limited.

The LSP client advertises experimental.prometeuDiagnosticAnalysis={version:1}. A supporting real compiler-backed project server returns:

{"prometeuDiagnosticAnalysis":{"version":1,"method":"prometeu/documentAnalysis","diagnosticDataVersion":1}}

For each didOpen/didChange, the server retains one analysisId and its complete analysis result. Located standard diagnostics contain data.prometeu={version:1,analysisId,issueId,issue}. Under the shared detail budget, identity and an explicit omission limitation replace the omitted issue. Locationless/project issues remain in the complementary analysis envelope and MUST NOT be coerced into standard zero ranges.

The request prometeu/documentAnalysis accepts {textDocument:{uri,version},contentSha256}. It returns {analysisId,document,issues,summary,inputs,configuration} from that retained analysis, without running a second backend/semantic analysis to produce details. document identifies the exact opened content. Current URI/version/digest mismatch returns JSON-RPC -32020 with reason ANALYSIS_REVISION_MISMATCH; unavailable retained analysis returns -32021 with ANALYSIS_UNAVAILABLE. Closing/disconnecting clears retained data. Analysis execution failure is an error, never successful empty diagnostics.

When the capability is absent, preserve standard results, report ANALYSIS_DETAILS_UNAVAILABLE, and use limited/unavailable rich coverage with not-evaluated validation. This fallback does not qualify the enriched integration. Empty standard diagnostics alone cannot establish project/build validity.

Failure code Mechanism
LANGUAGE_QUERY_TIMEOUT Admission-relative execution deadline expired.
LANGUAGE_QUERY_CANCELLED Query interrupted or cancelled.
LANGUAGE_SERVER_UNAVAILABLE Project endpoint absent/unreachable.
LANGUAGE_QUERY_PROTOCOL_FAILURE Unexpected JSON-RPC/protocol failure.
LANGUAGE_QUERY_INTERNAL_FAILURE Analysis/query execution failed internally or advertised analysis is unavailable.
LANGUAGE_QUERY_CLEANUP_FAILED Owned query resource cleanup failed.
LANGUAGE_QUERY_REVISION_MISMATCH Analysis document identity differs from requested revision.

Details retain component, operation/method, queryId, applicable identity, executionBudgetMs, cleanupBudgetMs, workerTerminated and cleanup. Preserve existing authority, read-only, unsupported and parameter errors. The first failure wins; cleanup status is attached independently. The default budget is 10000+2000 ms as specified by Studio 10. This does not alter runtime deadlines.

Conformance: StructuredDiagnosticsIntegrationTest exercises all eight unchanged PBS sources (now corrected positives), F1-local and the file-private negative control through authenticated HTTP MCP and the real project LSP; McpTaskToolsTest controlled invalid common IR exercises RET/join through the production backend/gateway/build tool. DiagnosticAnalysisProtocolTest checks retained identity/mismatch/unavailable; LanguageFailureContractTest checks real-socket controlled faults, fallback and delayed child termination. Existing task tests retain deduplication, cross-project isolation and revocation gates.

Visual checkpoint evidence tools

The existing authenticated project MCP endpoint MUST expose studio_evidence_persist, studio_evidence_import, studio_evidence_compare, studio_evidence_list, studio_evidence_metadata, studio_evidence_read, studio_evidence_image and studio_evidence_delete. Each tool MUST require the explicit projectRoot and current taskId. Artifact ID knowledge MUST NOT bypass authority or project scope. No extra server or arbitrary-path binary download route is permitted. Human-only baseline approval and external-path authorization MUST NOT be MCP tools.

Persist identifies the original operation with exactly one operationId or sourceClientRequestId and a distinct publication clientRequestId. Import/compare also require a publication clientRequestId; same parameters recover the retained publication, and changed parameters conflict. List MUST return at most 100 records per page with offset/nextOffset/total, including request identity for lost-response recovery. Read MUST validate offset/length and permit at most 1 MiB per call; image MUST return integrity-checked PNG image content directly, bounded to 32 MiB. Metadata MUST expose historical artifact identity separately from current staleness.

Compare MUST require explicit alpha compare/ignore; omitted channelLimit and allowedDifferentPixels default to zero. It MUST return the full shared report; passed/rejected/dimension_mismatch are comparison verdicts, while operational failures use the structured error envelope. Image/bytes and report inspection MUST use IDs inside this endpoint and require no agent transport/comparison scripts.

Isolated test target and transcript contract

The installed task-scoped surface is studio_tests_targets, studio_tests_start, studio_tests_get, studio_tests_cancel, studio_tests_transcript and studio_tests_shutdown. Start takes a declared targetId, maxFrames (1..1000000), blockFrames (1..60), timeoutMs (1..3600000), explicit media and discardUnsaved. Media is memory_fresh, disposable_create or disposable_reopen; reopen requires the creating run's UUID. These are bounded host policies, not guest budget changes.

Get returns run/request/operation identity, progress, workerTerminated, case/run result, transcriptTotal and the transcript paging tool. It MUST NOT inline the whole transcript into the summary response. Transcript returns offset/nextOffset, total and at most 1024 original native/decoded entries. Paging and repeated summary queries are non-executing. runtimeRetained reports current ownership separately from the immutable original run's cleanup observation. Shutdown requires actual worker termination and explicit discardUnsaved; it preserves native refusal.

The existing project endpoint MUST support explicit build target selection and shared guest test start/query/cancel/transcript access under current task authority, operationId/clientRequestId deduplication and actual worker termination. Omitted build target MUST be production; a changed target under the same request ID MUST conflict. Tests MUST refuse before guest execution unless the installed provider negotiates protocol 1.2 log_read. Availability MUST reflect implemented advertised handlers, not the existence of these accepted requirements.

Run results MUST correlate project/task/request/operation/run/target/build/session, retain immutable source/configuration/dependency/asset provenance and separate completion, timeout, cancellation, native failure and infrastructure loss. Case results MUST retain passed/failed/not_run/infrastructure_failure, explicit assertions and original checkpoint IDs. Transcript pages MUST preserve source sequences and loss evidence; requery MUST NOT reapply events or execute another advance. The mandatory success conditions and tagged JSON envelope are defined in the PBS dynamic semantics and common guest-test contracts. Tests MUST use explicit fresh RAM or a disposable run image, never default/personal media implicitly. Delivery uses the shared installed provider; any additional provider correction requires separate scoped authorization before runtime repository writes.

Structured assertion detail and host retention

Optional expected/actual values MUST retain independent availability flags, so an omitted value differs from an observed null. Native sequence/frame/timestamp, source/tag/application and the original event MUST remain correlated in transcript entries. Wall timestamps MUST NOT determine the verdict. An optional boolean passed on case_end/suite_end MAY explicitly reject that case/suite; it MUST NOT override a failed assertion. Non-boolean completion flags are invalid. Checkpoint artifact IDs MUST pass current project admission before inclusion as valid links.

The initial host accumulator retains at most 16 MiB and 100000 native records per run. Exceeding a host retention bound MUST report explicit infrastructure failure with the bound and retained position, never silently discard records or pass. These are host transcript bounds and do not alter firmware budgets. The installed isolated-tests example uses target-only helpers with complete versioned JSON literals and predicate booleans; it assumes no new guest string formatting ABI.

Shared asset authoring contract

Task-scoped asset operations MUST expose catalog, revision, dependency/ownership and budget queries plus preview, explicit commit and retained result queries over the shared service. Agent requests use stable asset/artifact identities, explicit semantic mutations and request IDs; they do not edit registry or asset-manifest persistence internals. Human external-PNG authorization is not issued by an MCP tool. Project-contained inputs still use normal task read authority and byte validation.

Preview returns the expected revision, all proposed changed files/assets, before/after hashes, affected references, available producer facts, ownership and conflicts. Commit supplies the batch ID and expected revision. Deduplicate each operation by authenticated project/task/request ID and its complete parameters. Revoke/cross-project checks apply to queries and retries as well as mutations. Cancellation before commit reports no publication; after commit, query/retry returns applied or recovered truth.

Results preserve producer/code, assetRoot/path/type, missing/duplicate indices, affected references and available used/required/limit facts. FE and MCP MUST show those same values. Budgets distinguish bank content, existing assets, build-included assets, effective final preloads and potential dynamic residency. Unknown profile status and its reason are explicit. A supplied profile or numeric count from an untrusted request does not establish qualification.

The installed task-scoped tools are studio_assets_catalog, studio_assets_artifacts, studio_assets_inspect, studio_assets_revision, studio_assets_dependencies, studio_assets_budget, studio_assets_preview, studio_assets_preview_get, studio_assets_commit and studio_assets_result. Each requires current projectRoot and taskId. Catalog pagination is bounded; studio_assets_artifacts accepts an optional batchId to inspect replacement targets in a retained preview. Mutation discriminators are create, register, import, compose_bank, compose_palettes, compose_scene, update_contract and build_participation. Scene tiles name stable bank/artifact identities; only the canonical packer adapter resolves them to runtime glyph indices. External PNG grants can be issued only through human source selection. The catalog is extended only when shared implementation, authority, recovery, FE parity and qualification gates are present. The existing tool catalog remains authoritative during implementation.

Guest producer continuity and native retention

Every structured guest event payload MUST include a zero-based contiguous integer ordinal; suite_end MUST include eventCount counting all unique events including itself. Retries with the same event identity/content are idempotent. Missing or inconsistent ordinals/final counts fail as infrastructure errors, even if native sequences remain contiguous. Native overflow records historical eviction; only unread gap or actual continuity loss causes a retention failure. Preserve the overflow observation separately.

Encoded guest messages MUST fit 256 UTF-8 bytes and stay within the unchanged 10 messages/application/frame budget, including ordinary application logs. The runner drains every pending native page before another bounded advance. Native continuity alone cannot detect events dropped before ring insertion. No new guest ABI, formatting facility or increased execution/logging budget is introduced.