feat(studio): integrate memcard persistence and headless controls
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good

Persist cartridge identity and slot configuration, add MemcardBoot and the MemcardBuffer SDK, and consume the runtime's negotiated memcard host controls with protected teardown.

Qualify save/reopen and version upgrades through distinct configured runtime processes. Include specs, examples, regression evidence and the consolidated discussion lesson.
This commit is contained in:
2026-10-30 11:01:02 +00:00
parent 3a3417eb44
commit 1d8b8c2101
110 changed files with 6502 additions and 85 deletions
@@ -143,6 +143,36 @@ class McpTaskToolsTest {
error("SESSION_NOT_FOUND", call("studio_headless_state", args()));
assertEquals(ControlState.AGENT_WORKING, session.snapshot().state());
}
@Test void memcardOptionsAndNativeShutdownRefusalSurviveMcpWithoutDetachingSession() throws Exception {
var bootOptions = new AtomicReference<Map<String, Object>>();
service = new DefaultTaskTools(access, catalog, (project, sink) -> new ShipperPrepareResult(
ShipperPreparationStatus.SUCCESS, List.of(), root.resolve("build/manifest.json"), List.of(), List.of()),
Optional.of(new HeadlessGateway() {
public Session boot(p.studio.api.project.ProjectReference project, String id, ShipperPrepareResult build) { throw new AssertionError("Options lost"); }
public Session boot(p.studio.api.project.ProjectReference project, String id, ShipperPrepareResult build, Map<String, Object> options) {
bootOptions.set(options); runtime = new FakeRuntime(id); return runtime;
}
}));
tools = new McpToolRegistry(new McpToolCatalog(mapper), mapper, McpTaskTools.handlers(service, mapper, true));
acquire(); call("studio_build_start", args().put("clientRequestId", "mem-build"));
String build = completed("mem-build").path("result").path("buildId").asText();
var boot = args().put("buildId", build).put("memcardChoice", "persistent");
boot.putObject("memcard").put("action", "open").put("access", "read_write");
value(call("studio_headless_boot", boot));
assertEquals("persistent", bootOptions.get().get("memcardChoice"));
assertEquals(Map.of("action", "open", "access", "read_write"), bootOptions.get().get("memcard"));
runtime.refuseShutdown = true;
var refusal = call("studio_headless_shutdown", args());
error("MEMCARD_ERROR", refusal);
assertEquals("unsaved_changes", refusal.path("structuredContent").path("error").path("runtimeError").path("details").path("reason").asText());
assertFalse(runtime.stopped); assertEquals(task, session.snapshot().task().value());
value(call("studio_headless_memcard_state", args()));
assertEquals(TaskTools.HeadlessAction.MEMCARD_STATE, runtime.lastAction);
value(call("studio_headless_shutdown", args().put("discardUnsaved", true).put("pendingWrites", "cancel")));
assertEquals(Map.of("discardUnsaved", true, "pendingWrites", "cancel"), runtime.stopPolicy);
assertTrue(runtime.stopped);
error("SESSION_NOT_FOUND", call("studio_headless_state", args()));
}
@Test void runtimeFaultAndBoundsDoNotRevokeTaskAndRebuildStopsRuntimeFirst() throws Exception {
acquire(); String oldBuild = buildAndBoot(); runtime.kind = AutomationOutcome.Kind.GUEST_FAULT;
@@ -291,7 +321,7 @@ class McpTaskToolsTest {
assertEquals(401, client.send(unauthorized, java.net.http.HttpResponse.BodyHandlers.discarding()).statusCode());
String first = connect(client, server), second = connect(client, server);
var list = mapper.createObjectNode().put("jsonrpc", "2.0").put("id", 1).put("method", "tools/list");
assertEquals(17, mapper.readTree(post(client, server, first, list).body()).path("result").path("tools").size());
assertEquals(22, mapper.readTree(post(client, server, first, list).body()).path("result").path("tools").size());
var context = value(httpCall(client, server, first, "studio_project_context", rootOnly()));
assertTrue(context.path("languages").toString().contains("pbs"));
value(httpCall(client, server, first, "studio_reference_read", rootOnly().put("referenceId", "pbs:quickstart").put("limit", 100)));
@@ -391,12 +421,21 @@ class McpTaskToolsTest {
CompletableFuture<Void> shutdownGate = CompletableFuture.completedFuture(null);
TaskTools.HeadlessAction lastAction;
volatile boolean stopped, hold, cancelled;
boolean refuseShutdown;
Map<String, Object> stopPolicy;
volatile AutomationOutcome.Kind kind = AutomationOutcome.Kind.SUCCEEDED;
Map<String, Object> input;
FakeRuntime(String build) { this.build = build; }
public String sessionId() { return id; }
public void cancel() { cancelled = true; }
public CompletionStage<Void> shutdown() { shutdownEntered.countDown(); return shutdownGate.thenRun(() -> stopped = true); }
public CompletionStage<TaskTools.HeadlessReply> stop(Map<String, Object> policy) {
stopPolicy = policy;
if (refuseShutdown && !Boolean.TRUE.equals(policy.get("discardUnsaved")))
return CompletableFuture.failedFuture(new AutomationException(new AutomationFailure(AutomationFailure.Code.MEMCARD_ERROR,
"Unsaved changes", Map.of("code", "memcard_error", "details", Map.of("reason", "unsaved_changes")))));
return shutdown().thenApply(v -> new TaskTools.HeadlessReply(Map.of("sessionId", id), null));
}
public long maxFramesPerAdvance() { return 600; }
CanonicalCapture capture(long logical) { return new CanonicalCapture(id, build, logical, 900, 1, 1, 1,
Base64.getDecoder().decode("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aK1kAAAAASUVORK5CYII=")); }