DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"use client";
/**
* Live state for one Partner Group session.
*
* The transcript is modelled as *rounds with fixed seats* rather than a flat
* message list. A parallel panel answers one question N times, so the user
* needs the N answers to read as one round, in a stable order — and each
* speaker's block must be the same DOM node from "thinking" to "answered", so
* nothing reorders or jumps when a partner finishes.
*
* Ordering therefore follows the group's member list, never arrival order
* (which is just the backend's asyncio scheduling).
*/
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { wsUrl } from "@/lib/api";
import {
getPartnerGroupHistory,
type PartnerGroup,
type PartnerGroupMessage,
type PartnerInvocation,
} from "@/lib/partner-groups-api";
import { ReconnectingWebSocket } from "@/lib/reconnecting-websocket";
import { shouldAppendEventContent } from "@/lib/stream";
import type { StreamEvent } from "@/features/chat/model/protocol";
export type SeatStatus = "waiting" | "working" | "done" | "error";
export interface Seat {
partnerId: string;
status: SeatStatus;
/** Speaker-private trace: tool calls, narration, thinking. */
events: StreamEvent[];
/** Optimistic body accumulated from stream deltas while working. */
streamed: string;
/** The authoritative persisted message, once the turn settles. */
message?: PartnerGroupMessage;
}
/**
* Only these two kinds make a round a follow-up.
*
* Tested explicitly rather than as "not a plain message": transcripts written
* before ``kind`` existed carry ``null``, and treating those as follow-ups
* turned every historical answer into an aside.
*/
function isFollowupKind(kind: string | null | undefined): boolean {
return kind === "invocation_question" || kind === "invocation_reply";
}
export interface Round {
turnId: string;
/** The human message that opened this round (absent for follow-up rounds). */
user?: PartnerGroupMessage;
seats: Seat[];
/** True for an approved partner-to-partner exchange, rendered as an aside. */
followup: boolean;
/** Set while this round is the one currently running. */
live: boolean;
/** The user stopped this round before every speaker finished. */
stopped?: boolean;
}
interface LiveTurn {
turnId: string;
/** The session that started this turn; a thread switch retires it. */
sessionKey: string;
targets: string[];
seats: Map<string, Seat>;
followup: boolean;
}
type GroupFrame =
| { type: "user_message"; message: PartnerGroupMessage }
| { type: "partner_started"; partner_id: string; invocation_id?: string }
| {
type: "partner_trace";
turn_id: string;
partner_id: string;
invocation_id?: string;
event: StreamEvent;
}
| { type: "partner_message"; message: PartnerGroupMessage }
| { type: "invocation_updated"; invocation: PartnerInvocation }
| { type: "done"; result?: Record<string, unknown> }
| { type: "cancelled"; content?: string }
| { type: "error"; content: string };
/** Grow the public body without withdrawing already published content. */
function growBody(seat: Seat, event: StreamEvent): string {
return shouldAppendEventContent(event)
? seat.streamed + (event.content || "")
: seat.streamed;
}
function emptySeat(partnerId: string): Seat {
return { partnerId, status: "waiting", events: [], streamed: "" };
}
export function useGroupSession(group: PartnerGroup, sessionKey: string) {
const [messages, setMessages] = useState<PartnerGroupMessage[]>([]);
const [rawLive, setLive] = useState<LiveTurn | null>(null);
// Switching threads retires a turn started by the previous one, declaratively
// rather than by resetting state inside an effect.
const live = rawLive && rawLive.sessionKey === sessionKey ? rawLive : null;
const [stoppedTurns, setStoppedTurns] = useState<Set<string>>(new Set());
const [connected, setConnected] = useState(false);
/** Which session's history has landed. Deriving ``loading`` from it means
* switching sessions is loading again without an imperative reset. */
const [loadedKey, setLoadedKey] = useState<string | null>(null);
const [error, setError] = useState("");
/** Invocation ids with an approve/reject request in flight. */
const [pendingActions, setPendingActions] = useState<Set<string>>(new Set());
const socketRef = useRef<ReconnectingWebSocket | null>(null);
/** A user-initiated invocation runs immediately: they *are* the approval. */
const autoRunRef = useRef<{ requester: string; target: string } | null>(null);
const historyReadyRef = useRef(false);
const attach = useCallback(
(socket: ReconnectingWebSocket | null) => {
socket?.send(
JSON.stringify({ action: "attach", session_key: sessionKey }),
);
},
[sessionKey],
);
useEffect(() => {
let cancelled = false;
historyReadyRef.current = false;
void getPartnerGroupHistory(group.group_id, sessionKey)
.then((history) => {
if (cancelled) return;
setMessages(history);
})
.catch(() => {
if (!cancelled) setMessages([]);
})
.finally(() => {
if (cancelled) return;
setLoadedKey(sessionKey);
historyReadyRef.current = true;
// Re-attaching after history lands lets an in-flight turn started
// before this mount (or before a refresh) replay into the new socket.
attach(socketRef.current);
});
return () => {
cancelled = true;
};
}, [attach, group.group_id, sessionKey]);
const handleFrame = useCallback(
(frame: GroupFrame) => {
switch (frame.type) {
case "user_message": {
const message = frame.message;
setMessages((current) =>
current.some((item) => item.event_id === message.event_id)
? current
: [...current, message],
);
// ``mentions`` is the backend's resolved target list, so the seats
// for this round are known before any partner starts working.
const targets = message.mentions.length
? message.mentions
: group.member_ids;
setLive({
sessionKey,
turnId: message.turn_id,
targets,
seats: new Map(targets.map((id) => [id, emptySeat(id)])),
followup: false,
});
setError("");
return;
}
case "partner_started": {
setLive((current) => {
// A follow-up round has no user message to open it, so the first
// signal that it exists is the invoked partner starting.
const base: LiveTurn = current ?? {
turnId: "",
sessionKey,
targets: [frame.partner_id],
seats: new Map(),
followup: Boolean(frame.invocation_id),
};
const seats = new Map(base.seats);
const seat =
seats.get(frame.partner_id) ?? emptySeat(frame.partner_id);
seats.set(frame.partner_id, { ...seat, status: "working" });
const targets = base.targets.includes(frame.partner_id)
? base.targets
: [...base.targets, frame.partner_id];
return { ...base, targets, seats };
});
return;
}
case "partner_trace": {
setLive((current) => {
if (!current) return current;
const seats = new Map(current.seats);
const seat =
seats.get(frame.partner_id) ?? emptySeat(frame.partner_id);
seats.set(frame.partner_id, {
...seat,
status: "working",
streamed: growBody(seat, frame.event),
events: [...seat.events, frame.event],
});
return {
...current,
turnId: current.turnId || frame.turn_id,
seats,
};
});
return;
}
case "partner_message": {
const message = frame.message;
setMessages((current) =>
current.some((item) => item.event_id === message.event_id)
? current
: [...current, message],
);
setLive((current) => {
if (!current) return current;
const seats = new Map(current.seats);
seats.delete(message.author_id);
return { ...current, seats };
});
return;
}
case "invocation_updated": {
const invocation = frame.invocation;
// The user asked for this one, so skip the approval step they would
// otherwise have to click on their own request.
const wanted = autoRunRef.current;
if (
wanted &&
invocation.status === "pending" &&
invocation.requester_partner_id === wanted.requester &&
invocation.target_partner_id === wanted.target
) {
autoRunRef.current = null;
socketRef.current?.send(
JSON.stringify({
action: "approve_invocation",
invocation_id: invocation.invocation_id,
session_key: sessionKey,
}),
);
}
setMessages((current) =>
current.map((message) =>
message.invocation_id === invocation.invocation_id
? { ...message, invocation }
: message,
),
);
setPendingActions((current) => {
if (!current.has(invocation.invocation_id)) return current;
const next = new Set(current);
next.delete(invocation.invocation_id);
return next;
});
return;
}
case "cancelled": {
setLive(null);
setPendingActions(new Set());
return;
}
case "done": {
setLive(null);
setPendingActions(new Set());
return;
}
case "error": {
setLive(null);
setPendingActions(new Set());
setError(frame.content);
return;
}
}
},
// ``sessionKey`` only stamps new turns; the handler is reached through a
// ref below, so widening this does not touch the socket's lifetime.
[group.member_ids, sessionKey],
);
// The socket outlives roster edits, so the handler is reached through a ref
// instead of being a dependency — otherwise changing a member would drop and
// re-open the connection mid-discussion.
const handleFrameRef = useRef(handleFrame);
useEffect(() => {
handleFrameRef.current = handleFrame;
}, [handleFrame]);
useEffect(() => {
const socket = new ReconnectingWebSocket(
wsUrl(`/ws/partner-groups/${encodeURIComponent(group.group_id)}`),
{
onOpen: () => {
setConnected(true);
if (historyReadyRef.current) attach(socket);
},
onDisconnect: () => setConnected(false),
onError: () => setConnected(false),
onMessage: (event) => {
try {
handleFrameRef.current(
JSON.parse(String(event.data)) as GroupFrame,
);
} catch {
// A malformed frame must not tear down the session.
}
},
},
);
socketRef.current = socket;
socket.start();
return () => {
socket.stop();
socketRef.current = null;
};
}, [attach, group.group_id]);
/** Rounds derived from persisted messages, merged with the live turn. */
const rounds = useMemo<Round[]>(() => {
const order = group.member_ids;
const byTurn = new Map<string, Round>();
for (const message of messages) {
let round = byTurn.get(message.turn_id);
if (!round) {
round = {
turnId: message.turn_id,
seats: [],
followup: isFollowupKind(message.kind),
live: false,
stopped: stoppedTurns.has(message.turn_id),
};
byTurn.set(message.turn_id, round);
}
if (message.role === "user") {
round.user = message;
continue;
}
if (message.kind === "round_stopped") {
// Server-side record of a user cancellation: round metadata, not a
// speaker, and what makes the marker survive a refresh.
round.stopped = true;
continue;
}
if (isFollowupKind(message.kind)) round.followup = true;
round.seats.push({
partnerId: message.author_id,
status: message.error ? "error" : "done",
events: message.events ?? [],
streamed: "",
message,
});
}
if (live) {
const round =
byTurn.get(live.turnId) ??
(() => {
const created: Round = {
turnId: live.turnId || "live",
seats: [],
followup: live.followup,
live: true,
};
byTurn.set(created.turnId, created);
return created;
})();
round.live = true;
round.seats = [...round.seats, ...live.seats.values()];
}
const seatRank = (seat: Seat) => {
const index = order.indexOf(seat.partnerId);
return index === -1 ? order.length : index;
};
/**
* Which pass of the round a seat belongs to.
*
* Debate puts the same speaker on the panel twice, so ordering by member
* alone would interleave the passes (A-opening, A-rebuttal, B-opening…)
* and destroy the actual chronology. A live seat carries no message yet,
* so its pass is inferred from how many times that speaker has already
* landed one in this round — which is exactly what makes a parallel
* round's live seats keep their fixed position instead of jumping.
*/
const passRank = (seat: Seat, siblings: Seat[]) => {
const kind = seat.message?.kind;
if (kind === "round_summary") return 2;
if (kind === "debate_rebuttal") return 1;
if (seat.message) return 0;
const spoken = siblings.filter(
(item) => item.message && item.partnerId === seat.partnerId,
).length;
return Math.min(spoken, 2);
};
return [...byTurn.values()].map((round) => ({
...round,
// Follow-up rounds are a Q&A pair whose chronological order carries the
// meaning (question then answer), so only panel rounds get seat order.
seats: round.followup
? round.seats
: [...round.seats].sort(
(a, b) =>
passRank(a, round.seats) - passRank(b, round.seats) ||
seatRank(a) - seatRank(b),
),
}));
}, [group.member_ids, live, messages, stoppedTurns]);
const reportConsultationActivity = useCallback((hasDraft: boolean, active: boolean) => {
socketRef.current?.send(JSON.stringify({
action: "consultation_activity", session_key: sessionKey, has_draft: hasDraft, active,
}));
}, [sessionKey]);
const send = useCallback(
(content: string, mentions: string[] | null) => {
const socket = socketRef.current;
if (!socket?.connected) return false;
return socket.send(
JSON.stringify({ content, session_key: sessionKey, mentions }),
);
},
[sessionKey],
);
const actOnInvocation = useCallback(
(invocationId: string, action: "approve" | "reject") => {
const socket = socketRef.current;
if (!socket?.connected || pendingActions.has(invocationId)) return false;
setPendingActions((current) => new Set(current).add(invocationId));
const ok = socket.send(
JSON.stringify({
action:
action === "approve" ? "approve_invocation" : "reject_invocation",
invocation_id: invocationId,
session_key: sessionKey,
}),
);
if (!ok) {
setPendingActions((current) => {
const next = new Set(current);
next.delete(invocationId);
return next;
});
}
return ok;
},
[pendingActions, sessionKey],
);
/** Ask one Partner to respond to another, on the user's initiative. */
const askPeer = useCallback(
(requesterId: string, targetId: string, question: string) => {
const socket = socketRef.current;
if (!socket?.connected) return false;
autoRunRef.current = { requester: requesterId, target: targetId };
const ok = socket.send(
JSON.stringify({
action: "create_invocation",
session_key: sessionKey,
requester_partner_id: requesterId,
target_partner_id: targetId,
question,
}),
);
if (!ok) autoRunRef.current = null;
return ok;
},
[sessionKey],
);
/** Ask one member to close a round with consensus / disagreement / advice. */
const summarizeRound = useCallback(
(turnId: string, partnerId: string) => {
const socket = socketRef.current;
if (!socket?.connected) return false;
return socket.send(
JSON.stringify({
action: "summarize_round",
session_key: sessionKey,
turn_id: turnId,
partner_id: partnerId,
}),
);
},
[sessionKey],
);
const cancel = useCallback(() => {
const socket = socketRef.current;
if (!socket?.connected) return false;
const ok = socket.send(
JSON.stringify({ action: "cancel", session_key: sessionKey }),
);
// Remember the round so the transcript can say it was stopped: otherwise
// the user is left with their question and no trace of what happened.
if (ok && live) {
const turnId = live.turnId;
setStoppedTurns((current) => new Set(current).add(turnId));
}
return ok;
}, [live, sessionKey]);
/**
* How many addressed partners have already answered this round.
*
* A debate runs two passes over the same speakers, so the counter would
* appear to fall back to zero halfway through. ``clash`` says which pass is
* running — everyone having already landed a message means this is the
* second one — so the label can say so instead of looking like a regression.
*/
const progress = useMemo(() => {
if (!live) return null;
const total = live.targets.length;
const answered = messages.filter(
(message) =>
message.turn_id === live.turnId && message.role === "partner",
).length;
return {
done: total - live.seats.size,
total,
clash: total > 0 && answered >= total,
};
}, [live, messages]);
return {
messages,
rounds,
reportConsultationActivity,
running: Boolean(live),
progress,
connected,
loading: loadedKey !== sessionKey,
error,
setError,
pendingActions,
send,
actOnInvocation,
askPeer,
summarizeRound,
cancel,
};
}