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.
846 lines
57 KiB
Markdown
846 lines
57 KiB
Markdown
# 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](10.%20DEV%20and%20Automation%20Specification.md), 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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports),
|
||
[lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle)
|
||
and [tools](https://modelcontextprotocol.io/specification/2025-06-18/server/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](<8. Project-Local Studio State Specification.md#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](../../../discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md)
|
||
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](12.%20Animation%20Authoring%20Specification.md).
|
||
|
||
## 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:
|
||
|
||
```json
|
||
{"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.
|