refactor(harness): freeze single-agent contracts

src/main/java/com/superbiz/agent/harness/contract/AnalysisKind.java

@@ -0,0 +1,13 @@
+package com.superbiz.agent.harness.contract;
+
+public enum AnalysisKind {
+    NORMAL,
+    NEGATIVE_OBSERVATION;
+
+    public boolean accepts(EvidenceStatus evidenceStatus) {
+        return switch (this) {
+            case NORMAL -> evidenceStatus == EvidenceStatus.EVIDENCE_FOUND;
+            case NEGATIVE_OBSERVATION -> evidenceStatus == EvidenceStatus.NO_EVIDENCE;
+        };
+    }
+}

src/main/java/com/superbiz/agent/harness/contract/ContractCollections.java

@@ -0,0 +1,13 @@
+package com.superbiz.agent.harness.contract;
+
+import java.util.List;
+
+final class ContractCollections {
+
+    private ContractCollections() {
+    }
+
+    static <T> List<T> immutable(List<T> values) {
+        return values == null ? List.of() : List.copyOf(values);
+    }
+}

src/main/java/com/superbiz/agent/harness/contract/DiagnosisDraft.java

@@ -0,0 +1,67 @@
+package com.superbiz.agent.harness.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public record DiagnosisDraft(
+        @JsonProperty("conclusion") Conclusion conclusion,
+        @JsonProperty("analysis") List<AnalysisItem> analysis,
+        @JsonProperty("action_plan") List<ActionPlanItem> actionPlan,
+        @JsonProperty("recommendations") List<Recommendation> recommendations,
+        @JsonProperty("limitations") Limitations limitations) {
+
+    public DiagnosisDraft {
+        analysis = ContractCollections.immutable(analysis);
+        actionPlan = ContractCollections.immutable(actionPlan);
+        recommendations = ContractCollections.immutable(recommendations);
+    }
+
+    public record Conclusion(
+            @JsonProperty("text") String text,
+            @JsonProperty("based_on_analysis_ids") List<String> basedOnAnalysisIds) {
+
+        public Conclusion {
+            basedOnAnalysisIds = ContractCollections.immutable(basedOnAnalysisIds);
+        }
+    }
+
+    public record AnalysisItem(
+            @JsonProperty("analysis_id") String analysisId,
+            @JsonProperty("kind") AnalysisKind kind,
+            @JsonProperty("text") String text,
+            @JsonProperty("tool_call_ids") List<String> toolCallIds) {
+
+        public AnalysisItem {
+            toolCallIds = ContractCollections.immutable(toolCallIds);
+        }
+    }
+
+    public record ActionPlanItem(
+            @JsonProperty("action") String action,
+            @JsonProperty("based_on_analysis_ids") List<String> basedOnAnalysisIds,
+            @JsonProperty("requires_human_confirmation") boolean requiresHumanConfirmation) {
+
+        public ActionPlanItem {
+            basedOnAnalysisIds = ContractCollections.immutable(basedOnAnalysisIds);
+        }
+    }
+
+    public record Recommendation(
+            @JsonProperty("text") String text,
+            @JsonProperty("based_on_analysis_ids") List<String> basedOnAnalysisIds) {
+
+        public Recommendation {
+            basedOnAnalysisIds = ContractCollections.immutable(basedOnAnalysisIds);
+        }
+    }
+
+    public record Limitations(
+            @JsonProperty("scope") String scope,
+            @JsonProperty("missing_info") List<String> missingInfo) {
+
+        public Limitations {
+            missingInfo = ContractCollections.immutable(missingInfo);
+        }
+    }
+}

src/main/java/com/superbiz/agent/harness/contract/EvidenceStatus.java

@@ -0,0 +1,7 @@
+package com.superbiz.agent.harness.contract;
+
+public enum EvidenceStatus {
+    EVIDENCE_FOUND,
+    NO_EVIDENCE,
+    ERROR
+}

src/main/java/com/superbiz/agent/harness/contract/FallbackType.java

@@ -0,0 +1,7 @@
+package com.superbiz.agent.harness.contract;
+
+public enum FallbackType {
+    EVIDENCE_VALIDATION_FAILED,
+    SEMANTIC_UNSUPPORTED,
+    SEMANTIC_UNAVAILABLE
+}

src/main/java/com/superbiz/agent/harness/contract/IntentType.java

@@ -0,0 +1,7 @@
+package com.superbiz.agent.harness.contract;
+
+public enum IntentType {
+    SYSTEM_CHAT,
+    KNOWLEDGE_QUERY,
+    DIAGNOSIS
+}

src/main/java/com/superbiz/agent/harness/contract/InvocationStatus.java

@@ -0,0 +1,7 @@
+package com.superbiz.agent.harness.contract;
+
+public enum InvocationStatus {
+    PROJECTING,
+    READY,
+    ERROR
+}

src/main/java/com/superbiz/agent/harness/contract/KnowledgeAnswerDraft.java

@@ -0,0 +1,25 @@
+package com.superbiz.agent.harness.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public record KnowledgeAnswerDraft(
+        @JsonProperty("answer_items") List<AnswerItem> answerItems,
+        @JsonProperty("limitations") List<String> limitations) {
+
+    public KnowledgeAnswerDraft {
+        answerItems = ContractCollections.immutable(answerItems);
+        limitations = ContractCollections.immutable(limitations);
+    }
+
+    public record AnswerItem(
+            @JsonProperty("text") String text,
+            @JsonProperty("tool_call_id") String toolCallId,
+            @JsonProperty("document_ids") List<String> documentIds) {
+
+        public AnswerItem {
+            documentIds = ContractCollections.immutable(documentIds);
+        }
+    }
+}

src/main/java/com/superbiz/agent/harness/contract/PreviousTurn.java

@@ -0,0 +1,27 @@
+package com.superbiz.agent.harness.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public record PreviousTurn(
+        @JsonProperty("user_query") String userQuery,
+        @JsonProperty("published_conclusion") String publishedConclusion,
+        @JsonProperty("scope") String scope,
+        @JsonProperty("limitations") List<String> limitations,
+        @JsonProperty("source_documents") List<SourceDocument> sourceDocuments) {
+
+    public PreviousTurn {
+        limitations = ContractCollections.immutable(limitations);
+        sourceDocuments = ContractCollections.immutable(sourceDocuments);
+    }
+
+    public static PreviousTurn from(PublishedResult result) {
+        return new PreviousTurn(
+                result.userQuery(),
+                result.publishedConclusion(),
+                result.scope(),
+                result.limitations(),
+                result.sourceDocuments());
+    }
+}

src/main/java/com/superbiz/agent/harness/contract/PublishedResult.java

@@ -0,0 +1,18 @@
+package com.superbiz.agent.harness.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public record PublishedResult(
+        @JsonProperty("user_query") String userQuery,
+        @JsonProperty("published_conclusion") String publishedConclusion,
+        @JsonProperty("scope") String scope,
+        @JsonProperty("limitations") List<String> limitations,
+        @JsonProperty("source_documents") List<SourceDocument> sourceDocuments) {
+
+    public PublishedResult {
+        limitations = ContractCollections.immutable(limitations);
+        sourceDocuments = ContractCollections.immutable(sourceDocuments);
+    }
+}

src/main/java/com/superbiz/agent/harness/contract/ReleaseOutcome.java

@@ -0,0 +1,8 @@
+package com.superbiz.agent.harness.contract;
+
+public enum ReleaseOutcome {
+    SUCCESS,
+    FALLBACK,
+    FAILED,
+    CANCELLED
+}

src/main/java/com/superbiz/agent/harness/contract/SafeFallback.java

@@ -0,0 +1,26 @@
+package com.superbiz.agent.harness.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public record SafeFallback(
+        @JsonProperty("type") FallbackType type,
+        @JsonProperty("conclusion") String conclusion,
+        @JsonProperty("message") String message,
+        @JsonProperty("verified_sources") List<VerifiedSource> verifiedSources,
+        @JsonProperty("limitations") List<String> limitations,
+        @JsonProperty("next_steps") List<String> nextSteps) {
+
+    public SafeFallback {
+        verifiedSources = ContractCollections.immutable(verifiedSources);
+        limitations = ContractCollections.immutable(limitations);
+        nextSteps = ContractCollections.immutable(nextSteps);
+    }
+
+    public record VerifiedSource(
+            @JsonProperty("source_type") String sourceType,
+            @JsonProperty("source") String source,
+            @JsonProperty("scope") String scope) {
+    }
+}

src/main/java/com/superbiz/agent/harness/contract/SemanticVerdict.java

@@ -0,0 +1,6 @@
+package com.superbiz.agent.harness.contract;
+
+public enum SemanticVerdict {
+    SUPPORTED,
+    UNSUPPORTED
+}

src/main/java/com/superbiz/agent/harness/contract/SourceDocument.java

@@ -0,0 +1,8 @@
+package com.superbiz.agent.harness.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record SourceDocument(
+        @JsonProperty("document_id") String documentId,
+        @JsonProperty("title") String title) {
+}

src/main/java/com/superbiz/agent/harness/contract/SseOutcome.java

@@ -0,0 +1,7 @@
+package com.superbiz.agent.harness.contract;
+
+public enum SseOutcome {
+    SUCCESS,
+    FALLBACK,
+    FAILED
+}