Skip to content
Merged
Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
256e648
feat(groups): follow-up, continuation, and close for group conversations
ginccc Jul 8, 2026
89da643
fix(groups): address PR #595 review findings for follow-up/continue/c…
ginccc Jul 13, 2026
f477cb1
fix(groups): fix CI + address multi-agent review findings on PR #595
ginccc Jul 13, 2026
05b6d64
test(groups): cover continueDiscussionStreaming (403 rethrow, SSE err…
ginccc Jul 13, 2026
8341fed
Merge origin/main into feat/group-followups
ginccc Jul 14, 2026
ff90745
fix(groups): resolve cross-feature review findings from the main merge
ginccc Jul 14, 2026
cd2040a
fix(groups): MCP ownership, CLOSED-blindness, atomic CAS + review bac…
ginccc Jul 14, 2026
516be0c
fix(groups): MCP owner resolution + honest /continue attachment contract
ginccc Jul 14, 2026
1e0858f
fix(groups): address CodeQL, Copilot and CodeRabbit PR review findings
ginccc Jul 14, 2026
e387b3e
Merge remote-tracking branch 'origin/main' into feat/group-followups
ginccc Jul 14, 2026
b3f945f
fix(groups): terminal-state integrity + no exception text in client b…
ginccc Jul 14, 2026
5b1328c
test(groups): mutation-audited regression coverage for the merge fixes
ginccc Jul 14, 2026
d1338a3
feat(groups): split follow-up/continue HTTP status codes by failure c…
ginccc Jul 15, 2026
38dfc45
fix(groups): mid-round member timeout maps to 504, not 502
ginccc Jul 15, 2026
9875e46
fix(groups): address Copilot PR review — MCP error curation, TEXT_PLA…
ginccc Jul 15, 2026
5268a72
fix(tools): make ToolExecutionTrace recording thread-safe
ginccc Jul 15, 2026
796fc08
Merge origin/main into feat/group-followups — resolve PR #595 conflicts
ginccc Jul 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 171 additions & 0 deletions docs/changelog.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,15 @@ public interface IGroupConversationStore {

List<GroupConversation> listByGroupId(String groupId, int index, int limit) throws IResourceStore.ResourceStoreException;

/**
* Atomically transition a group conversation from expectedState to newState.
* Returns true if the transition succeeded (state matched), false if the state
* had already changed (concurrent modification).
*/
boolean compareAndSetState(String id, GroupConversation.GroupConversationState expectedState,
GroupConversation.GroupConversationState newState)
throws IResourceStore.ResourceStoreException, IResourceStore.ResourceNotFoundException;

/**
* Update the group conversation only if it is currently in the expected state.
* Throws {@link IResourceStore.ResourceModifiedException} if the conversation
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,12 @@
import ai.labs.eddi.configs.hitl.HitlTimeoutPolicy;
import ai.labs.eddi.engine.memory.model.Attachment;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonProperty;

import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
Expand All @@ -28,12 +30,29 @@ public class GroupConversation {
private String userId;
private GroupConversationState state;
private String originalQuestion;
/**
* The question driving the CURRENT run's phases. Equals
* {@link #originalQuestion} for the initial round; a continuation round sets it
* to the follow-up question so an HITL resume re-runs the remaining phases with
* the right question. Kept separate from {@code originalQuestion} (which the UI
* renders as the conversation title) so continuations don't rewrite that title.
* {@code null} on legacy documents — resume falls back to
* {@code originalQuestion}.
*/
private String resumeQuestion;
private List<TranscriptEntry> transcript = Collections.synchronizedList(new ArrayList<>());
private Map<String, String> memberConversationIds = new ConcurrentHashMap<>();
/**
* Maps agentId → displayName for all group members. Populated at discussion
* start.
*/
private Map<String, String> memberDisplayNames = new LinkedHashMap<>();
private int currentPhaseIndex;
private String currentPhaseName;
private String synthesizedAnswer;
private int depth;
/** Current discussion round (1-based). Incremented by continueDiscussion(). */
private int round = 1;
private SharedTaskList taskList;
/** Agents dynamically added during the discussion (recruited or created). */
private List<AgentGroupConfiguration.GroupMember> dynamicMembers = Collections.synchronizedList(new ArrayList<>());
Expand Down Expand Up @@ -155,15 +174,22 @@ public enum TranscriptEntryType {
/** Task execution result from the EXECUTE phase. */
TASK_RESULT,
/** Verification assessment from the VERIFY phase. */
VERIFICATION
VERIFICATION,
/** User-to-member or member-to-user follow-up exchange between rounds. */
FOLLOW_UP
}

public enum GroupConversationState {
CREATED, IN_PROGRESS, SYNTHESIZING, COMPLETED, FAILED,
/** Discussion was cancelled before completion — HITL foundation (Phase 9b). */
CANCELLED,
/** Paused for human approval — HITL foundation (Phase 9b). */
AWAITING_APPROVAL
AWAITING_APPROVAL,
/**
* Terminal — member conversations ended, ephemeral agents cleaned up, no
* further follow-ups.
*/
CLOSED
}

public enum HitlPauseType {
Expand Down Expand Up @@ -212,6 +238,14 @@ public void setOriginalQuestion(String originalQuestion) {
this.originalQuestion = originalQuestion;
}

public String getResumeQuestion() {
return resumeQuestion;
}

public void setResumeQuestion(String resumeQuestion) {
this.resumeQuestion = resumeQuestion;
}

public List<TranscriptEntry> getTranscript() {
return transcript;
}
Expand Down Expand Up @@ -264,6 +298,14 @@ public void setDepth(int depth) {
this.depth = depth;
}

public int getRound() {
return round;
}

public void setRound(int round) {
this.round = round;
}

public Instant getCreated() {
return created;
}
Expand Down Expand Up @@ -337,6 +379,44 @@ public void setDynamicAgentConfig(AgentGroupConfiguration.DynamicAgentConfig dyn
this.dynamicAgentConfig = dynamicAgentConfig;
}

public Map<String, String> getMemberDisplayNames() {
Comment thread
github-code-quality[bot] marked this conversation as resolved.
Fixed
return Collections.unmodifiableMap(memberDisplayNames);
}

public void setMemberDisplayNames(Map<String, String> memberDisplayNames) {
this.memberDisplayNames = memberDisplayNames != null
? new LinkedHashMap<>(memberDisplayNames)
: new LinkedHashMap<>();
}

/**
* Register a member's display name (agentId → displayName). Used at discussion
* start to populate the map. This is the supported mutation path —
* {@link #getMemberDisplayNames()} returns an unmodifiable view.
*/
public void addMemberDisplayName(String agentId, String displayName) {
this.memberDisplayNames.put(agentId, displayName);
}

/**
* Computed property — not persisted. Tells clients which operations are
* available based on the current conversation state.
*/
Comment thread
ginccc marked this conversation as resolved.
Resolved
@JsonProperty(value = "availableActions", access = JsonProperty.Access.READ_ONLY)
public List<String> getAvailableActions() {
if (state == null) {
return List.of();
}
return switch (state) {
case COMPLETED -> List.of("followup", "continue", "close");
// FAILED and CANCELLED are terminal but closeable — close ends member
// conversations and reclaims ephemeral agents.
case FAILED, CANCELLED -> List.of("close");
case IN_PROGRESS, SYNTHESIZING, CREATED, AWAITING_APPROVAL -> List.of();
case CLOSED -> List.of();
};
}

@JsonIgnore
public List<Attachment> getAttachments() {
return attachments;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,34 @@ public List<GroupConversation> listByGroupId(String groupId, int index, int limi
return results;
}

@Override
public boolean compareAndSetState(String id, GroupConversation.GroupConversationState expectedState,
GroupConversation.GroupConversationState newState)
throws IResourceStore.ResourceStoreException, IResourceStore.ResourceNotFoundException {
GroupConversation gc = read(id);
if (gc.getState() != expectedState) {
// Fast path: clearly the wrong state — no need to attempt the write.
return false;
}
gc.setState(newState);
gc.setLastModified(java.time.Instant.now());
try {
// Conditional write — the persisted state must STILL be expectedState. The
// read-check above alone was a read-check-update (single-node only): two
// racing callers could both pass it and both write. storeIfFieldEquals makes
// the transition atomic across processes.
updateIfState(gc, expectedState);
return true;
} catch (IResourceStore.ResourceModifiedException e) {
// Another writer transitioned the conversation between our read and our
// write — this CAS lost the race.
return false;
} catch (GroupConversationGoneException e) {
throw new IResourceStore.ResourceNotFoundException(
"Group conversation " + id + " no longer exists");
}
}

@Override
public void updateIfState(GroupConversation gc, GroupConversation.GroupConversationState expectedState)
throws IResourceStore.ResourceStoreException, IResourceStore.ResourceModifiedException {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -82,14 +82,57 @@ GroupConversation readGroupConversation(String groupConversationId)

/**
* Delete a group conversation and cascade-delete member conversations.
*
* @throws GroupDiscussionException
* if another operation (follow-up / continue / close) is currently
* in progress for this conversation — a retryable conflict (REST:
* 409), not a store failure.
*/
void deleteGroupConversation(String groupConversationId) throws IResourceStore.ResourceStoreException;
void deleteGroupConversation(String groupConversationId)
throws GroupDiscussionException, IResourceStore.ResourceStoreException;

/**
* List group conversations for a given group config.
*/
List<GroupConversation> listGroupConversations(String groupId, int index, int limit) throws IResourceStore.ResourceStoreException;

/**
* Send a follow-up question to a specific member agent within a completed group
* conversation. The exchange (user question + agent response) is appended to
* the group transcript. The agent retains full context from its participation
* in prior rounds via its reused private conversation.
*
* <p>
* The {@code targetAgentId} can be either an agent ID or a display name.
* Display names are resolved against
* {@link GroupConversation#getMemberDisplayNames()}.
*
* @return the updated group conversation with the follow-up appended to the
* transcript
*/
GroupConversation followUpWithMember(String groupConversationId, String targetAgentId,
String question)
throws GroupDiscussionException, IResourceStore.ResourceStoreException, IResourceStore.ResourceNotFoundException;

/**
* Continue a completed group conversation with a new question. All phases
* re-execute with the new question; agents retain conversation memory from
* prior rounds via their reused private conversations. The round counter
* increments.
*/
GroupConversation continueDiscussion(String groupConversationId, String question,
GroupDiscussionEventListener listener)
throws GroupDiscussionException, IResourceStore.ResourceStoreException, IResourceStore.ResourceNotFoundException;

/**
* Explicitly close a group conversation. Ends all member conversations,
* triggers ephemeral agent cleanup, and sets state to CLOSED. Irreversible.
*
* @return the closed group conversation
*/
GroupConversation closeGroupConversation(String groupConversationId)
throws GroupDiscussionException, IResourceStore.ResourceStoreException, IResourceStore.ResourceNotFoundException;

/**
* Cancel a running or paused group discussion.
*
Expand Down Expand Up @@ -151,6 +194,8 @@ default void onTaskPlanCreated(GroupConversationEventSink.TaskPlanCreatedEvent e
}
default void onTaskVerified(GroupConversationEventSink.TaskVerifiedEvent event) {
}
default void onRoundStart(GroupConversationEventSink.RoundStartEvent event) {
}
default void onHitlPause(GroupConversationEventSink.HitlPauseEvent event) {
}
default void onHitlResume(GroupConversationEventSink.HitlResumeEvent event) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ public interface IRestGroupConversation {
@Operation(summary = "Delete a group conversation", description = "Deletes a group conversation and its member conversations.")
@APIResponse(responseCode = "200", description = "Group conversation deleted.")
@APIResponse(responseCode = "404", description = "Group conversation not found.")
@APIResponse(responseCode = "409", description = "Another operation (follow-up / continue / close) is in progress — retry.")
Response deleteGroupConversation(@PathParam("groupId") String groupId, @PathParam("groupConversationId") String groupConversationId);

@GET
Expand All @@ -81,6 +82,74 @@ List<GroupConversation> listGroupConversations(@PathParam("groupId") String grou
@QueryParam("limit")
@DefaultValue("20") Integer limit);

@POST
@Path("/{groupId}/conversations/{groupConversationId}/followup")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@Operation(summary = "Follow up with a group member",
description = "Send a follow-up question to a specific member agent in a completed "
+ "group conversation. The agent retains full context from the discussion. "
+ "Both the question and response are recorded on the group transcript. "
+ "The targetAgentId field accepts either an agent ID or a display name. "
+ "Returns the full updated GroupConversation including the new transcript entries.")
@APIResponse(responseCode = "200", description = "Updated group conversation with follow-up on transcript.")
@APIResponse(responseCode = "400", description = "Missing 'question' or 'targetAgentId'.")
@APIResponse(responseCode = "404", description = "Group conversation not found.")
@APIResponse(responseCode = "409", description = "Conversation not in COMPLETED state, or concurrently cancelled/deleted.")
Response followUpWithMember(@PathParam("groupId") String groupId,
Comment thread
github-code-quality[bot] marked this conversation as resolved.
Fixed
@PathParam("groupConversationId") String gcId,
FollowUpRequest request);

@POST
@Path("/{groupId}/conversations/{groupConversationId}/continue")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@Operation(summary = "Continue a group discussion",
description = "Re-run all discussion phases with a new question. All agents retain "
+ "memory of prior rounds. The round counter increments. NOTE: 'attachments' are "
+ "NOT supported on a continuation (they are only shared with member agents when "
+ "the discussion starts) and are rejected with 400 rather than silently ignored.")
@APIResponse(responseCode = "200", description = "Updated group conversation with new round.")
@APIResponse(responseCode = "400", description = "Missing 'question', or 'attachments' supplied (unsupported on continuation).")
@APIResponse(responseCode = "404", description = "Group conversation not found.")
@APIResponse(responseCode = "409", description = "Conversation not in COMPLETED state.")
Response continueDiscussion(@PathParam("groupId") String groupId,
Comment thread
github-code-quality[bot] marked this conversation as resolved.
Fixed
@PathParam("groupConversationId") String gcId,
DiscussRequest request);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

@POST
@Path("/{groupId}/conversations/{groupConversationId}/continue/stream")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.SERVER_SENT_EVENTS)
@Operation(summary = "Continue a group discussion with SSE streaming",
description = "Re-run all discussion phases with SSE event streaming for progress. "
+ "Emits round_start (new round marker) followed by the same events as the "
+ "initial stream (phase_start, speaker_start, speaker_complete, phase_complete, "
+ "synthesis_start, group_complete, group_error), plus the HITL events "
+ "(awaiting_approval, hitl_resume, cancelled, member_pause_skipped). NOTE: "
+ "'attachments' are NOT supported on a continuation and are rejected with a "
+ "terminal group_error event rather than silently ignored.")
@APIResponse(responseCode = "200", description = "SSE event stream of continuation progress.")
@APIResponse(responseCode = "404", description = "Group conversation not found.")
void continueDiscussionStreaming(@PathParam("groupId") String groupId,
Comment thread
github-code-quality[bot] marked this conversation as resolved.
Fixed
@PathParam("groupConversationId") String gcId,
DiscussRequest request,
@Context SseEventSink eventSink, @Context Sse sse);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

@POST
@Path("/{groupId}/conversations/{groupConversationId}/close")
@Produces(MediaType.APPLICATION_JSON)
@Operation(summary = "Close a group conversation",
description = "Permanently close a group conversation. Ends all member conversations "
+ "and cleans up ephemeral agents. No further follow-ups or continuations "
+ "are accepted after closing. "
+ "Lifecycle: discuss → COMPLETED → [followup|continue]* → close → CLOSED (terminal).")
@APIResponse(responseCode = "200", description = "Closed group conversation.")
@APIResponse(responseCode = "404", description = "Group conversation not found.")
@APIResponse(responseCode = "409", description = "Conversation not in COMPLETED, FAILED or CANCELLED state.")
Response closeGroupConversation(@PathParam("groupId") String groupId,
Comment thread
github-code-quality[bot] marked this conversation as resolved.
Fixed
@PathParam("groupConversationId") String gcId);

@POST
@Path("/{groupId}/conversations/{groupConversationId}/cancel")
@Consumes(MediaType.APPLICATION_JSON)
Expand Down Expand Up @@ -149,6 +218,13 @@ public DiscussRequest(String question, String userId) {
}
}

/**
* Request body for following up with a specific group member.
* {@code targetAgentId} accepts either a raw agent ID or a display name.
*/
record FollowUpRequest(String question, String targetAgentId, String userId) {
}

/**
* A single attachment reference on a group discussion request. Provide either
* inline base64 {@code data} (+ {@code mimeType}) or a hosted {@code url}.
Expand Down
Loading
Loading