implement DEV workspace and project automation authority

This commit is contained in:
2026-09-29 07:09:37 +01:00
parent 0ddf3ef70d
commit e3c3b2cbb7
62 changed files with 2180 additions and 354 deletions
@@ -0,0 +1,7 @@
package p.studio.api.automation;
import java.util.List;
public record AutomationOutcome(Kind kind, long requestedFrames, long completedFrames,
List<String> diagnostics, CanonicalCapture capture) {
public enum Kind { SUCCEEDED, TERMINATED, GUEST_FAULT, INFRASTRUCTURE_FAILURE, CANCELLED }
public AutomationOutcome { diagnostics = List.copyOf(diagnostics); }
}
@@ -0,0 +1,20 @@
package p.studio.api.automation;
import java.util.concurrent.Callable;
import java.util.concurrent.CompletionStage;
import java.util.function.Consumer;
import p.studio.api.operation.OperationHandle;
import p.studio.api.operation.OperationSubscription;
public interface AutomationSession {
AutomationSnapshot snapshot();
OperationSubscription subscribe(Consumer<AutomationSnapshot> listener);
OperationSubscription registerDocuments(DocumentHandoff documents);
CompletionStage<ControlResult> grant(boolean saveUnsavedDocuments);
ControlResult acquire();
CompletionStage<ControlResult> release(TaskIdentity task);
CompletionStage<ControlResult> reclaim();
CompletionStage<ControlResult> closeAsync();
/** Internal specialized service work, not a generic MCP shell/tool endpoint. */
OperationHandle<AutomationOutcome> submit(TaskIdentity task, String summary, Callable<AutomationOutcome> work);
void attachRuntime(TaskIdentity task, ManagedHeadlessSession runtime);
void markCaptureStale();
}
@@ -0,0 +1,12 @@
package p.studio.api.automation;
import java.nio.file.Path;
import java.util.List;
import p.studio.api.operation.OperationSnapshot;
public record AutomationSnapshot(Path projectRoot, ControlState state, boolean handoffPending,
boolean closed, int manualOperations, TaskIdentity task, OperationSnapshot operation,
CanonicalCapture capture, boolean stale, List<String> diagnostics, List<String> calls) {
public AutomationSnapshot { diagnostics = List.copyOf(diagnostics); calls = List.copyOf(calls); }
public boolean manualAllowed() { return !closed && !handoffPending && state == ControlState.MANUAL; }
public boolean canGrant() { return manualAllowed() && manualOperations == 0; }
public boolean canReclaim() { return !closed && state != ControlState.MANUAL; }
}
@@ -0,0 +1,12 @@
package p.studio.api.automation;
import java.util.Objects;
/** Lossless PNG bytes; stride describes the original RGBA8888 buffer, not PNG padding. */
public record CanonicalCapture(String sessionId, String buildId, long logicalFrameIndex,
long frameId, int width, int height, int stridePixels, byte[] png) {
public CanonicalCapture {
Objects.requireNonNull(sessionId); Objects.requireNonNull(buildId); Objects.requireNonNull(png);
if (width <= 0 || height <= 0 || stridePixels < width) throw new IllegalArgumentException("invalid frame layout");
png = png.clone();
}
@Override public byte[] png() { return png.clone(); }
}
@@ -0,0 +1,10 @@
package p.studio.api.automation;
/** A typed admission failure; adapters must preserve the domain status. */
public final class ControlDeniedException extends IllegalStateException {
private final ControlResult.Status status;
public ControlDeniedException(ControlResult.Status status) {
super("Project control: " + status);
this.status = status;
}
public ControlResult.Status status() { return status; }
}
@@ -0,0 +1,6 @@
package p.studio.api.automation;
public record ControlResult(Status status, TaskIdentity task, String diagnostic) {
public enum Status { GRANTED, ACQUIRED, RETURNED, BUSY, DIRTY_DOCUMENTS, SAVE_FAILED, NOT_GRANTED, INVALID_TASK, CLOSED, CLEANUP_FAILED }
public boolean success() { return status == Status.GRANTED || status == Status.ACQUIRED || status == Status.RETURNED; }
public static ControlResult of(Status status, String message) { return new ControlResult(status, null, message); }
}
@@ -0,0 +1,2 @@
package p.studio.api.automation;
public enum ControlState { MANUAL, WAITING_FOR_AGENT, AGENT_WORKING, RETURNING_CONTROL }
@@ -0,0 +1,10 @@
package p.studio.api.automation;
import java.util.concurrent.CompletionStage;
/** A participant must complete only after saves/refreshes, not when they are scheduled. */
public interface DocumentHandoff extends AutoCloseable {
CompletionStage<Boolean> hasUnsavedChanges();
CompletionStage<Void> saveAll();
CompletionStage<Void> refreshFromDisk();
/** Disposes presentation work on project closure; must not write buffered content. */
@Override default void close() { }
}
@@ -0,0 +1,8 @@
package p.studio.api.automation;
import java.util.concurrent.CompletionStage;
/** Lifecycle port implemented by the process adapter, never by JavaFX. */
public interface ManagedHeadlessSession {
String sessionId();
void cancel();
CompletionStage<Void> shutdown();
}
@@ -0,0 +1,7 @@
package p.studio.api.automation;
/** Keeps grant admission closed until the actual manual work has finished. */
@FunctionalInterface
public interface ManualLease extends AutoCloseable {
@Override void close();
default void onProjectClose(Runnable cancellation) { }
}
@@ -0,0 +1,17 @@
package p.studio.api.automation;
import java.nio.file.Path;
/** Shared service guard. Paths may be project roots or contained asset paths. */
public interface ProjectAccess {
ManualLease enterManual(Path path);
default <R> p.studio.api.operation.OperationHandle<R> submitManual(Path path,
p.studio.api.operation.OperationExecutor executor, String summary, java.util.concurrent.Callable<R> work) {
ManualLease lease = enterManual(path);
try {
var operation = executor.submit(summary, work);
lease.onProjectClose(operation::cancel);
operation.termination().whenComplete((result, failure) -> lease.close());
return operation;
} catch (RuntimeException failure) { lease.close(); throw failure; }
}
}
@@ -0,0 +1,9 @@
package p.studio.api.automation;
import java.nio.file.Path;
import java.util.Objects;
public record TaskIdentity(Path projectRoot, String value) {
public TaskIdentity {
projectRoot = Objects.requireNonNull(projectRoot).toAbsolutePath().normalize();
if (Objects.requireNonNull(value).isBlank()) throw new IllegalArgumentException("empty task identity");
}
}