add MCP tool contracts and authenticated local HTTP transport
This commit is contained in:
@@ -0,0 +1,15 @@
|
||||
package p.studio.api.automation;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/** Stable domain failure codes, independent of HTTP status and JSON-RPC errors. */
|
||||
public record AutomationFailure(Code code, String message) {
|
||||
public enum Code {
|
||||
PROJECT_NOT_OPEN, NOT_GRANTED, INVALID_TASK, BUSY, CLOSED, CLEANUP_FAILED,
|
||||
UNSUPPORTED_LANGUAGE, UNSUPPORTED_CAPABILITY, REFERENCE_NOT_FOUND, DOCUMENTATION_UNAVAILABLE,
|
||||
OUTSIDE_PROJECT_SCOPE, READ_ONLY_SCOPE, OPERATION_NOT_FOUND, CLIENT_REQUEST_CONFLICT,
|
||||
RUNTIME_UNAVAILABLE, RUNTIME_INCOMPATIBLE, SESSION_NOT_FOUND, BUILD_NOT_FOUND,
|
||||
NO_FRAME_AVAILABLE, LIMIT_EXCEEDED, NOT_CANCELABLE, INFRASTRUCTURE_FAILURE
|
||||
}
|
||||
public AutomationFailure { Objects.requireNonNull(code); Objects.requireNonNull(message); }
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
package p.studio.api.automation;
|
||||
|
||||
/** Exactly one lookup key, always scoped to a separately validated project/task identity. */
|
||||
public record OperationLookup(String operationId, String clientRequestId) {
|
||||
public OperationLookup {
|
||||
if ((operationId == null) == (clientRequestId == null)
|
||||
|| (operationId != null && operationId.isBlank())
|
||||
|| (clientRequestId != null && clientRequestId.isBlank()))
|
||||
throw new IllegalArgumentException("Supply exactly one nonblank operationId or clientRequestId");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,63 @@
|
||||
package p.studio.api.automation;
|
||||
|
||||
import java.nio.file.Path;
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/** Installed, owner-maintained knowledge. Authentication belongs to the calling adapter. */
|
||||
public interface ProjectKnowledge {
|
||||
Context context(Path openProjectRoot);
|
||||
ReferencePage readReference(Path openProjectRoot, String referenceId, int offset, int limit);
|
||||
|
||||
record Version(String value, String source) {
|
||||
public Version {
|
||||
Objects.requireNonNull(source, "source");
|
||||
if (source.isBlank() || value != null && value.isBlank()) throw new IllegalArgumentException("Blank version provenance");
|
||||
}
|
||||
public boolean known() { return value != null; }
|
||||
public static Version unknown() { return new Version(null, "unknown"); }
|
||||
}
|
||||
enum Support { SUPPORTED, UNSUPPORTED, UNKNOWN }
|
||||
record Capability(String name, Support support, String limitation) {
|
||||
public Capability { Objects.requireNonNull(name); Objects.requireNonNull(support); }
|
||||
}
|
||||
record Language(String id, boolean primary, Version languageVersion, Version compilerVersion,
|
||||
Version sdkVersion, List<String> extensions, List<Path> sourceRoots,
|
||||
List<Capability> capabilities, List<String> referenceIds) {
|
||||
public Language {
|
||||
Objects.requireNonNull(id); Objects.requireNonNull(languageVersion);
|
||||
Objects.requireNonNull(compilerVersion); Objects.requireNonNull(sdkVersion);
|
||||
extensions = List.copyOf(extensions); sourceRoots = List.copyOf(sourceRoots);
|
||||
capabilities = List.copyOf(capabilities); referenceIds = List.copyOf(referenceIds);
|
||||
}
|
||||
}
|
||||
enum ReferenceKind { QUICKSTART, SYNTAX, SEMANTICS, EXAMPLE, SDK, LIBRARY }
|
||||
record Reference(String id, String title, String owner, ReferenceKind kind, Version version) {
|
||||
public Reference { Objects.requireNonNull(id); Objects.requireNonNull(title); Objects.requireNonNull(owner); Objects.requireNonNull(kind); Objects.requireNonNull(version); }
|
||||
}
|
||||
record Library(String id, Version version, List<Path> roots, boolean editable) {
|
||||
public Library { Objects.requireNonNull(id); Objects.requireNonNull(version); roots = List.copyOf(roots); }
|
||||
}
|
||||
record Context(Path projectRoot, String projectName, List<Language> languages,
|
||||
List<Library> libraries, List<Path> editableRoots, List<Path> readOnlyRoots,
|
||||
List<Reference> references, List<String> limitations) {
|
||||
public Context {
|
||||
projectRoot = Objects.requireNonNull(projectRoot).toAbsolutePath().normalize();
|
||||
Objects.requireNonNull(projectName);
|
||||
languages = List.copyOf(languages); libraries = List.copyOf(libraries);
|
||||
editableRoots = List.copyOf(editableRoots); readOnlyRoots = List.copyOf(readOnlyRoots);
|
||||
references = List.copyOf(references); limitations = List.copyOf(limitations);
|
||||
}
|
||||
}
|
||||
/** Offsets and limits count Unicode code points, not bytes or UTF-16 code units. */
|
||||
record ReferencePage(String referenceId, int offset, int total, Integer nextOffset, String text) {
|
||||
public ReferencePage {
|
||||
Objects.requireNonNull(referenceId); Objects.requireNonNull(text);
|
||||
int count = text.codePointCount(0, text.length());
|
||||
if (offset < 0 || total < offset || count > total - offset
|
||||
|| (nextOffset == null && count != total - offset)
|
||||
|| (nextOffset != null && (nextOffset != offset + count || nextOffset >= total || count == 0)))
|
||||
throw new IllegalArgumentException("Invalid reference page");
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
package p.studio.api.automation;
|
||||
|
||||
import p.studio.api.operation.OperationSnapshot;
|
||||
import p.studio.api.shipper.ShipperPrepareResult;
|
||||
import java.util.Objects;
|
||||
|
||||
/** An operation outcome is not task authority. Null result means it is not available yet. */
|
||||
public record TrackedOperation(OperationSnapshot operation, String clientRequestId, Progress progress,
|
||||
String buildId, ShipperPrepareResult buildResult, AutomationOutcome runtimeResult, AutomationFailure failure) {
|
||||
public TrackedOperation {
|
||||
Objects.requireNonNull(operation); Objects.requireNonNull(clientRequestId); Objects.requireNonNull(progress);
|
||||
if (clientRequestId.isBlank()) throw new IllegalArgumentException("Empty client request identity");
|
||||
if (buildResult != null && runtimeResult != null) throw new IllegalArgumentException("Mixed operation result kinds");
|
||||
}
|
||||
/** Unknown progress stays null. Never infer completion from cancellation acknowledgement. */
|
||||
public record Progress(Long requestedFrames, Long completedFrames) {
|
||||
public Progress {
|
||||
if (requestedFrames != null && requestedFrames < 0 || completedFrames != null && completedFrames < 0
|
||||
|| requestedFrames != null && completedFrames != null && completedFrames > requestedFrames)
|
||||
throw new IllegalArgumentException("Invalid frame progress");
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user