@hienlh/ppm 0.17.16 → 0.17.18

package/src/services/group-chat/group-chat.service.ts

@@ -7,16 +7,18 @@ import {
   setMemberSession,
   setGroupLeaderSession,
 } from "./group-chat.store.ts";
-import { runGroupTurnLoop } from "./turn-engine.ts";
+import { runReplyBurst } from "./turn-engine.ts";
 import { makeEngineRunAgent } from "./agent-runner.ts";
 import type { ChatBackend } from "./agent-runner.ts";
+import { makeResponderRouter } from "./responder-router.ts";
 import { archiveAndDelete } from "./transcript-archive.ts";
 import type {
   Group,
   GroupMember,
   GroupMessage,
   AgentTurnResult,
-  TurnLoopResult,
+  BurstResult,
+  TurnEngineDeps,
 } from "../../types/group-chat.ts";
 import type { GroupChatServerMessage } from "../../types/group-chat-ws.ts";
 
@@ -24,10 +26,9 @@ type WsClient = { send: (data: string) => void };
 
 interface GroupRuntime {
   abort: AbortController;
-  clients: Set<WsClient>;
-  /** Bounded reconnect buffer of emitted server events. */
+  /** Bounded reconnect buffer of the CURRENT burst's events (replayed on reconnect). */
   buffer: GroupChatServerMessage[];
-  loop: Promise<TurnLoopResult>;
+  loop: Promise<BurstResult>;
 }
 
 const MAX_BUFFER = 2000;
@@ -37,31 +38,54 @@ const MAX_BUFFER = 2000;
  *  model — FE disconnect does NOT abort the loop. */
 class GroupChatService {
   private runtimes = new Map<string, GroupRuntime>();
-  /** WS clients connected before a runtime exists — migrated into the runtime on start/resume. */
-  private pendingClients = new Map<string, Set<WsClient>>();
+  /** Connected WS clients per group — PERSISTENT across bursts. Must NOT be tied to a
+   *  runtime's lifetime: with re-seed-per-message the runtime is created/destroyed for
+   *  every message, and a client stored on the runtime would be orphaned when the burst
+   *  ends (missing its own next message until it reconnects). */
+  private clients = new Map<string, Set<WsClient>>();
+  /** Latest user message received while a burst was running — drained into the next
+   *  burst when the current one finishes (single-slot: newer supersedes older). */
+  private pendingMessage = new Map<string, GroupMessage>();
+  /** Member session ids known created + live THIS server run. Keep-alive: a member's
+   *  session is reused (resumed → native memory) across bursts while its id is here.
+   *  Cleared on server restart → sessions are recreated fresh (memory reset, accepted). */
+  private aliveSessions = new Set<string>();
 
   // --- test seams (production uses the real provider-backed runner) --------
   private stubbedRunAgent: (() => (m: GroupMember, prompt: string) => Promise<AgentTurnResult>) | null = null;
+  private stubbedResponderRouter: (() => NonNullable<TurnEngineDeps["routeNextSpeakers"]>) | null = null;
   private spawnStub = false;
 
   _setRunAgentFactory(f: () => (m: GroupMember, prompt: string) => Promise<AgentTurnResult>): void {
     this.stubbedRunAgent = f;
   }
+  _setResponderRouterFactory(f: (() => NonNullable<TurnEngineDeps["routeNextSpeakers"]>) | null): void {
+    this.stubbedResponderRouter = f;
+  }
   _setSpawnStub(v: boolean): void { this.spawnStub = v; }
+  /** Inject a fake ChatBackend (session/create/send) for lifecycle tests. */
+  _setBackend(b: ChatBackend | null): void { this.backendCache = b; this.aliveSessions.clear(); }
   isRunning(groupId: string): boolean { return this.runtimes.has(groupId); }
 
   // --- lifecycle -----------------------------------------------------------
 
-  /** Start (or ignore if already running) the turn loop for a group. Detached.
-   *  Persists the user's task as the first bus message, then runs the loop. */
+  /** Handle a user message: persist it as a chat message, then run a bounded reply
+   *  burst. If a burst is already running, queue the message (newer supersedes older)
+   *  and run it once the current burst finishes. */
   async start(groupId: string, userMessage: string, providerId = "claude"): Promise<void> {
-    if (this.runtimes.has(groupId)) return;
     const { group, members } = this.loadGroup(groupId);
-
-    const taskMsg = appendMessage({
-      groupId, fromMember: "user", kind: "task", summary: userMessage, turnIndex: -1,
+    const msg = appendMessage({
+      groupId, fromMember: "user", kind: "chat", summary: userMessage,
+      turnIndex: this.nextTurnIndex(groupId),
     });
-    await this.runLoop(group, members, userMessage, providerId, taskMsg);
+
+    if (this.runtimes.has(groupId)) {
+      // A burst is in flight — queue this message and surface it in the feed now.
+      this.pendingMessage.set(groupId, msg);
+      this.emit(groupId, { type: "group_message", message: msg });
+      return;
+    }
+    await this.runBurst(group, members, providerId, msg);
   }
 
   /** Stop a running group: abort the in-flight turn + mark paused. Cooperative
@@ -72,16 +96,17 @@ class GroupChatService {
     setGroupStatus(groupId, "paused");
   }
 
-  /** Resume: re-spawn fresh member sessions and re-enter the loop, seeding
-   *  context from the durable bus (windowed + rolling summary). The bus is the
-   *  source of truth — works even after transcripts were archived/deleted.
-   *  Resuming a converged group starts a new round appended to the same bus. */
+  /** Resume after a Stop: re-run a reply burst ONLY when the latest message is an
+   *  unanswered user message (i.e. a burst was stopped/errored before replying). If the
+   *  last message is an assistant reply, the conversation is already answered → no-op,
+   *  so Resume never double-replies to a question that was already handled. */
   async resume(groupId: string, providerId = "claude"): Promise<void> {
     if (this.runtimes.has(groupId)) return;
     const { group, members } = this.loadGroup(groupId);
-    // The original task is the durable anchor for every resumed round.
-    const task = this.originalTask(groupId) ?? group.name;
-    await this.runLoop(group, members, task, providerId);
+    const msgs = readMessages(groupId);
+    const last = msgs[msgs.length - 1];
+    if (!last || last.fromMember !== "user") { setGroupStatus(groupId, "idle"); return; }
+    await this.runBurst(group, members, providerId);
   }
 
   // --- shared loop core ----------------------------------------------------
@@ -94,71 +119,104 @@ class GroupChatService {
     return { group, members };
   }
 
-  /** Original user task from the durable bus (turn_index = -1). */
-  private originalTask(groupId: string): string | null {
-    const first = readMessages(groupId).find((m) => m.kind === "task" && m.fromMember === "user");
-    return first?.summary ?? null;
+  /** Next sequential turn index for the group's durable bus. */
+  private nextTurnIndex(groupId: string): number {
+    const prior = readMessages(groupId);
+    return (prior[prior.length - 1]?.turnIndex ?? -1) + 1;
   }
 
-  /** Spawn fresh sessions (unless stubbed), run the detached turn loop, and
-   *  register the runtime. Shared by both start() and resume(). */
-  private async runLoop(
-    group: Group, members: GroupMember[], task: string, providerId: string,
+  /** Register the runtime, then (async) spawn sessions + run one detached reply burst,
+   *  draining any user message queued while the burst ran. Re-seed per message.
+   *  The runtime is registered SYNCHRONOUSLY (before the first await) so a message that
+   *  arrives during session spawn is queued via start()'s runtimes.has() check — never
+   *  run as a second concurrent burst. */
+  private async runBurst(
+    group: Group, members: GroupMember[], providerId: string,
     initialMessage?: GroupMessage,
   ): Promise<void> {
-    const backend = this.spawnStub ? null : await this.getBackend();
-    if (backend) await this.spawnSessions(group, members, backend);
-
-    setGroupStatus(group.id, "active");
     const abort = new AbortController();
+    // Synchronous registration — no await may precede this (so a message arriving during
+    // session spawn is queued, not run as a second concurrent burst).
+    const runtime: GroupRuntime = {
+      abort, buffer: [],
+      loop: Promise.resolve({ reason: "stopped", turns: 0, costUsd: 0 } as BurstResult),
+    };
+    this.runtimes.set(group.id, runtime);
+    setGroupStatus(group.id, "active");
+    // Emit the user's message now that the runtime exists (so it lands in the reconnect
+    // buffer); persistent clients receive it live regardless of runtime lifetime.
+    if (initialMessage) {
+      this.emit(group.id, { type: "group_message", message: initialMessage });
+    }
 
-    const runAgent = this.stubbedRunAgent
-      ? this.stubbedRunAgent()
-      : makeEngineRunAgent(backend!, providerId, abort.signal);
+    // Dedicated ephemeral router session (cheap-model next-speaker classification) —
+    // kept separate from member sessions so router prompts never pollute member history.
+    let routerSessionId: string | null = null;
 
-    const deps = {
-      runAgent,
-      appendMessage,
-      readMessages,
-      onMessage: (message: GroupMessage) => this.emit(group.id, { type: "group_message", message }),
-      shouldStop: () => abort.signal.aborted,
-    };
+    const loop = (async () => {
+      const backend = this.spawnStub ? null : await this.getBackend();
+      if (backend) await this.ensureSessions(group, members, backend);
+      const runAgent = this.stubbedRunAgent
+        ? this.stubbedRunAgent()
+        : makeEngineRunAgent(backend!, providerId, abort.signal);
 
-    const loop = runGroupTurnLoop(group, members, deps, task)
+      // Smart responder routing: prefer a stubbed router in tests; otherwise build one over
+      // a fresh ephemeral session. Absent → engine falls back to mention-following.
+      let routeNextSpeakers: TurnEngineDeps["routeNextSpeakers"];
+      if (this.stubbedResponderRouter) {
+        routeNextSpeakers = this.stubbedResponderRouter();
+      } else if (backend) {
+        const rs = await backend.createSession({
+          projectPath: group.projectPath, projectName: group.projectName,
+          title: `[group:${group.name}] router`,
+        });
+        routerSessionId = rs.id;
+        routeNextSpeakers = makeResponderRouter(backend, providerId, rs.id);
+      }
+
+      const deps = {
+        runAgent,
+        appendMessage,
+        readMessages,
+        onMessage: (message: GroupMessage) => this.emit(group.id, { type: "group_message", message }),
+        onTyping: (member: string) => this.emit(group.id, { type: "typing", member }),
+        routeNextSpeakers,
+        shouldStop: () => abort.signal.aborted,
+      };
+      return runReplyBurst(group, members, deps, { cap: group.maxTurns });
+    })()
       .then((res) => {
         this.emit(group.id, { type: "group_done", reason: res.reason, turns: res.turns, costUsd: res.costUsd });
         // A user-requested stop keeps the group paused for a later resume;
-        // any natural termination returns the group to idle.
+        // a natural burst end returns the group to idle to wait for the next message.
         setGroupStatus(group.id, res.reason === "stopped" ? "paused" : "idle");
         return res;
       })
       .catch((e) => {
         this.emit(group.id, { type: "error", message: (e as Error).message });
         setGroupStatus(group.id, "idle");
-        return { reason: "stopped", turns: 0, costUsd: 0 } as TurnLoopResult;
+        return { reason: "stopped", turns: 0, costUsd: 0 } as BurstResult;
       })
       .finally(() => {
-        if (!this.spawnStub) void this.archiveMembers(group, members);
+        // Keep-alive: member sessions are NOT archived per burst — they persist so the
+        // next burst resumes them (native memory). Archival happens on group/member delete.
+        if (routerSessionId) void this.deleteRouterSession(providerId, routerSessionId);
         this.runtimes.delete(group.id);
+        // Drain a message queued mid-burst → run the next burst for it.
+        const queued = this.pendingMessage.get(group.id);
+        if (queued) {
+          this.pendingMessage.delete(group.id);
+          void this.runBurst(group, members, providerId);
+        }
       });
-
-    // Migrate any WS clients that connected before this runtime was created.
-    const inherited = this.pendingClients.get(group.id) ?? new Set<WsClient>();
-    this.pendingClients.delete(group.id);
-    this.runtimes.set(group.id, { abort, clients: inherited, buffer: [], loop });
-    // Emit the task message now that the runtime + client set exists, so WS
-    // clients that connected before start() was called receive it immediately.
-    if (initialMessage) {
-      this.emit(group.id, { type: "group_message", message: initialMessage });
-    }
-    // Surface spawn/immediate errors to the caller; loop errors are emitted.
+    runtime.loop = loop;
+    // Surface spawn/immediate errors to the caller; burst errors are emitted.
     await Promise.resolve();
   }
 
   // --- WS wiring -----------------------------------------------------------
 
   addClient(groupId: string, ws: WsClient): void {
-    const rt = this.runtimes.get(groupId);
     const group = getGroup(groupId);
     if (group) {
       const members = listMembers(groupId).map((m) => ({
@@ -166,39 +224,50 @@ class GroupChatService {
       }));
       ws.send(JSON.stringify({ type: "group_state", groupId, status: group.status, members } satisfies GroupChatServerMessage));
     }
-    if (rt) {
-      rt.clients.add(ws);
-      for (const ev of rt.buffer) ws.send(JSON.stringify(ev));
-    } else {
-      // No runtime yet — park the client so it is migrated into the runtime when the
-      // engine starts. Without this the WS receives group_state but misses all
-      // group_message broadcasts because emit() only iterates rt.clients.
-      let pending = this.pendingClients.get(groupId);
-      if (!pending) { pending = new Set(); this.pendingClients.set(groupId, pending); }
-      pending.add(ws);
-    }
+    // Register in the persistent per-group client set (survives burst churn).
+    let set = this.clients.get(groupId);
+    if (!set) { set = new Set(); this.clients.set(groupId, set); }
+    set.add(ws);
+    // Replay the current burst's buffer so a mid-burst reconnect catches up.
+    const rt = this.runtimes.get(groupId);
+    if (rt) for (const ev of rt.buffer) ws.send(JSON.stringify(ev));
   }
 
   removeClient(groupId: string, ws: WsClient): void {
-    this.runtimes.get(groupId)?.clients.delete(ws);
-    this.pendingClients.get(groupId)?.delete(ws);
+    const set = this.clients.get(groupId);
+    set?.delete(ws);
+    if (set && set.size === 0) this.clients.delete(groupId);
   }
 
   private emit(groupId: string, ev: GroupChatServerMessage): void {
+    // Buffer into the current burst (for reconnect replay) when one is running.
     const rt = this.runtimes.get(groupId);
-    if (!rt) return;
-    rt.buffer.push(ev);
-    if (rt.buffer.length > MAX_BUFFER) rt.buffer.shift();
+    if (rt) {
+      rt.buffer.push(ev);
+      if (rt.buffer.length > MAX_BUFFER) rt.buffer.shift();
+    }
+    // Broadcast to all persistent clients — independent of runtime lifetime.
+    const set = this.clients.get(groupId);
+    if (!set) return;
     const payload = JSON.stringify(ev);
-    for (const c of rt.clients) {
+    for (const c of set) {
       try { c.send(payload); } catch { /* dropped client */ }
     }
   }
 
   // --- provider-backed session lifecycle -----------------------------------
 
-  private async spawnSessions(group: Group, members: GroupMember[], backend: ChatBackend): Promise<void> {
+  /** Keep-alive: reuse a member's session while it's live this run (resume → native
+   *  memory); otherwise create a fresh one (archiving any stale prior file first). */
+  private async ensureSessions(group: Group, members: GroupMember[], backend: ChatBackend): Promise<void> {
     for (const m of members) {
+      if (m.sessionId && this.aliveSessions.has(m.sessionId)) {
+        if (m.role === "leader") setGroupLeaderSession(group.id, m.sessionId);
+        continue; // reuse — the provider resumes it (in-process message count > 0)
+      }
+      // Not alive this run (new member / post-restart): archive any orphaned old file,
+      // then create a fresh session so we never create-with-an-existing-id.
+      if (m.sessionId) await archiveAndDelete(m.sessionId, group.name).catch(() => {});
       const session = await backend.createSession({
         projectPath: group.projectPath,
         projectName: group.projectName,
@@ -206,16 +275,46 @@ class GroupChatService {
       });
       setMemberSession(m.id, session.id);
       m.sessionId = session.id;
+      this.aliveSessions.add(session.id);
       if (m.role === "leader") setGroupLeaderSession(group.id, session.id);
     }
   }
 
+  /** Archive + delete every member's live session and forget it (on group/member delete). */
   private async archiveMembers(group: Group, members: GroupMember[]): Promise<void> {
     for (const m of members) {
-      if (m.sessionId) await archiveAndDelete(m.sessionId, group.name).catch(() => {});
+      if (m.sessionId) {
+        await archiveAndDelete(m.sessionId, group.name).catch(() => {});
+        this.aliveSessions.delete(m.sessionId);
+      }
     }
   }
 
+  /** Teardown for group delete: stop any burst, archive all member sessions, drop state. */
+  async archiveAndForget(groupId: string): Promise<void> {
+    const group = getGroup(groupId);
+    if (!group) return;
+    this.stop(groupId);
+    if (!this.spawnStub) await this.archiveMembers(group, listMembers(groupId));
+    this.clients.delete(groupId);
+    this.pendingMessage.delete(groupId);
+  }
+
+  /** Archive + forget a single member's session (on member removal). */
+  async archiveMemberSession(groupName: string, sessionId: string | null): Promise<void> {
+    if (!sessionId || this.spawnStub) return;
+    await archiveAndDelete(sessionId, groupName).catch(() => {});
+    this.aliveSessions.delete(sessionId);
+  }
+
+  /** Delete the ephemeral router session (no archive — its transcript is throwaway). */
+  private async deleteRouterSession(providerId: string, sessionId: string): Promise<void> {
+    try {
+      const { chatService } = await import("../chat.service.ts");
+      await chatService.deleteSession(providerId, sessionId);
+    } catch { /* best-effort cleanup */ }
+  }
+
   private backendCache: ChatBackend | null = null;
 
   private async getBackend(): Promise<ChatBackend> {
@@ -228,7 +327,7 @@ class GroupChatService {
       // consumer-side signal guard halts the turn, so only permissionMode is
       // forwarded here.
       sendMessage: (pid, sid, prompt, opts) =>
-        chatService.sendMessage(pid, sid, prompt, { permissionMode: opts?.permissionMode }),
+        chatService.sendMessage(pid, sid, prompt, { permissionMode: opts?.permissionMode, model: opts?.model, oneMContext: opts?.oneMContext }),
     };
     return this.backendCache;
   }

package/src/services/group-chat/group-chat.store.ts

@@ -10,6 +10,7 @@ import {
   type MemberStatus,
   type CreateGroupInput,
   type AddMemberInput,
+  type UpdateMemberInput,
   type AppendMessageInput,
   type ReadMessagesOptions,
 } from "../../types/group-chat.ts";
@@ -142,6 +143,11 @@ export function setGroupLeaderSession(id: string, sessionId: string): void {
   getDb().query("UPDATE chat_groups SET leader_session_id = ? WHERE id = ?").run(sessionId, id);
 }
 
+/** Update the per-group reply-burst cap (max AI turns per user message). */
+export function setGroupMaxTurns(id: string, maxTurns: number): void {
+  getDb().query("UPDATE chat_groups SET max_turns = ? WHERE id = ?").run(maxTurns, id);
+}
+
 // ---------------------------------------------------------------------------
 // Members
 // ---------------------------------------------------------------------------
@@ -159,6 +165,30 @@ export function addMember(input: AddMemberInput): GroupMember {
   return toMember(row);
 }
 
+export function getMember(memberId: string): GroupMember | null {
+  const row = getDb().query("SELECT * FROM chat_group_members WHERE id = ?").get(memberId) as MemberRow | null;
+  return row ? toMember(row) : null;
+}
+
+/** Update the provided fields of a member; unspecified fields are left unchanged. */
+export function updateMember(memberId: string, patch: UpdateMemberInput): GroupMember | null {
+  const cols: Array<[string, string | null]> = [];
+  if (patch.role !== undefined) cols.push(["role", patch.role]);
+  if (patch.name !== undefined) cols.push(["name", patch.name]);
+  if (patch.persona !== undefined) cols.push(["persona", patch.persona]);
+  if (patch.agentType !== undefined) cols.push(["agent_type", patch.agentType]);
+  if (patch.model !== undefined) cols.push(["model", patch.model]);
+  if (patch.color !== undefined) cols.push(["color", patch.color]);
+  if (cols.length === 0) return getMember(memberId);
+  const set = cols.map(([c]) => `${c} = ?`).join(", ");
+  getDb().query(`UPDATE chat_group_members SET ${set} WHERE id = ?`).run(...cols.map(([, v]) => v), memberId);
+  return getMember(memberId);
+}
+
+export function removeMember(memberId: string): void {
+  getDb().query("DELETE FROM chat_group_members WHERE id = ?").run(memberId);
+}
+
 export function listMembers(groupId: string): GroupMember[] {
   const rows = getDb().query(
     "SELECT * FROM chat_group_members WHERE group_id = ? ORDER BY joined_at, id",

package/src/services/group-chat/responder-router.ts

@@ -0,0 +1,110 @@
+import type { GroupMember, GroupMessage } from "../../types/group-chat.ts";
+import { buildContextWindow, renderWindow, DEFAULT_WINDOW } from "./context-window.ts";
+
+/** Cheapest/fastest model for the lightweight next-speaker classification. */
+export const ROUTER_MODEL = "claude-haiku-4-5";
+const NONE = "NONE";
+
+/** Minimal backend the router needs (structural subset of agent-runner's ChatBackend). */
+export interface RouterBackend {
+  sendMessage(
+    providerId: string,
+    sessionId: string,
+    prompt: string,
+    opts?: { model?: string; permissionMode?: string; oneMContext?: boolean },
+  ): AsyncIterable<{ type: string; content?: string; message?: string }>;
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Parse the router's reply into known member names (0-N), in order of appearance.
+ *  Never invents a name — only exact member-name matches (case-insensitive, word-bounded).
+ *  Longest names first + claimed spans so a short name can't match inside a longer one.
+ *  NONE / unknown / garbage → []. */
+export function parseResponders(text: string, members: GroupMember[]): string[] {
+  const t = (text ?? "").trim();
+  if (!t) return [];
+  const byLen = [...members].sort((a, b) => b.name.length - a.name.length);
+  const claimed: Array<[number, number]> = [];
+  const found: Array<{ name: string; at: number }> = [];
+  for (const m of byLen) {
+    if (!m.name) continue;
+    const re = new RegExp(`(^|[^\\p{L}\\p{N}_])(${escapeRe(m.name)})([^\\p{L}\\p{N}_]|$)`, "giu");
+    let match: RegExpExecArray | null;
+    while ((match = re.exec(t)) !== null) {
+      const start = match.index + match[1]!.length;
+      if (claimed.some(([s, e]) => start >= s && start < e)) continue; // inside a longer name
+      found.push({ name: m.name, at: start });
+      claimed.push([start, start + m.name.length]);
+      break; // one occurrence per member is enough
+    }
+  }
+  found.sort((a, b) => a.at - b.at);
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const f of found) if (!seen.has(f.name)) { out.push(f.name); seen.add(f.name); }
+  return out;
+}
+
+/** Build the classification prompt. Priority: recent history > member name > persona;
+ *  leader only as fallback / to curb off-topic drift; user turns must pick someone. */
+export function buildRouterPrompt(
+  history: GroupMessage[], members: GroupMember[], isUserTurn: boolean,
+): string {
+  const { window, rollingSummary } = buildContextWindow(history, DEFAULT_WINDOW);
+  const leader = members.find((m) => m.role === "leader");
+  const roster = members
+    .map((m) => `- ${m.name}${m.role === "leader" ? " (leader)" : ""}${m.persona ? `: ${m.persona}` : ""}`)
+    .join("\n");
+  const names = members.map((m) => m.name).join(", ");
+  // The AI the user is currently conversing with (spoke most recently).
+  const lastSpeaker = [...history].reverse().find((m) => m.fromMember !== "user")?.fromMember;
+
+  const parts = [
+    `You route a group chat: decide WHO should speak next. Output member names (or ${NONE}).`,
+    `Members:\n${roster}`,
+    rollingSummary ? `\nEARLIER (summary):\n${rollingSummary}` : "",
+    `\nRECENT MESSAGES:\n${renderWindow(window)}`,
+    `\nRules (priority order):`,
+    lastSpeaker
+      ? `1. CONTINUITY: the user is currently talking with "${lastSpeaker}" (spoke most recently). If this new user message is a reply or instruction directed at them (incl. "assign X", "tell the others", "you do it"), pick "${lastSpeaker}" — even if that's the leader. Only pick someone else if the message clearly targets a different member.`
+      : `1. Prefer whoever the RECENT conversation makes most relevant — continue an ongoing thread.`,
+    `2. Otherwise, the member NAME being addressed.`,
+    `3. Use PERSONA/expertise only for generic questions with no clear thread.`,
+    `4. Pick the leader (${leader?.name ?? "leader"}) ONLY if no member clearly fits, or to steer the team back when the discussion drifts off-topic.`,
+    `5. PARALLELISM: if several members should respond and can do so INDEPENDENTLY (their replies don't depend on each other), list them ALL — they run in parallel. If a reply must build on another's, list only the ONE who goes next.`,
+    `6. WRAP-UP: after the leader (${leader?.name ?? "leader"}) delegated a task and the assigned members have reported back, pick the leader ONCE to summarize the results for the user — then, on the following turn, output ${NONE} to end.`,
+    isUserTurn
+      ? `This is a reply to the USER — you MUST pick at least one member (never ${NONE}).`
+      : `If no one has anything useful to add, output ${NONE} to end the exchange.`,
+    `\nAnswer with member name(s) from [${names}]${isUserTurn ? "" : ` or ${NONE}`}, separated by spaces — no other words.`,
+  ];
+  return parts.filter(Boolean).join("\n");
+}
+
+/** Bind a `routeNextSpeaker` fn to a backend + a dedicated router session. Best-effort:
+ *  any error / empty / unknown reply → null (the engine forces the leader on user turns
+ *  and ends the burst on AI turns). Uses the cheapest model via a per-call override. */
+export function makeResponderRouter(
+  backend: RouterBackend, providerId: string, sessionId: string,
+  opts: { model?: string } = {},
+): (ctx: { history: GroupMessage[]; members: GroupMember[]; isUserTurn: boolean }) => Promise<string[]> {
+  const model = opts.model ?? ROUTER_MODEL;
+  return async ({ history, members, isUserTurn }) => {
+    try {
+      const prompt = buildRouterPrompt(history, members, isUserTurn);
+      let text = "";
+      // oneMContext:false — the cheap router model needs no 1M window and may not support it.
+      for await (const ev of backend.sendMessage(providerId, sessionId, prompt, { model, permissionMode: "bypassPermissions", oneMContext: false })) {
+        if (ev.type === "text") text += ev.content ?? "";
+        else if (ev.type === "error") return [];
+        else if (ev.type === "done") break;
+      }
+      return parseResponders(text, members);
+    } catch {
+      return [];
+    }
+  };
+}

package/src/services/group-chat/transcript-archive.ts

@@ -74,3 +74,21 @@ export function readArchivedTranscript(sessionId: string, groupName: string): st
   if (!existsSync(dest)) return null;
   try { return readFileSync(dest, "utf8"); } catch { return null; }
 }
+
+/** Absolute path of an archived transcript JSONL if it exists (else null). */
+export function archivedTranscriptPath(sessionId: string, groupName: string): string | null {
+  const dest = join(archiveDir(groupName), `${sessionId}.jsonl`);
+  return existsSync(dest) ? dest : null;
+}
+
+/** Absolute path of a LIVE (not-yet-archived) session JSONL under the Claude projects
+ *  root, else null. Keep-alive sessions stay here until the group is deleted. */
+export async function liveTranscriptPath(sessionId: string): Promise<string | null> {
+  return findJsonl(sessionId);
+}
+
+/** Resolve a member transcript: prefer the LIVE session file (keep-alive), fall back to
+ *  the archived copy (post group/member delete). */
+export async function resolveTranscriptPath(sessionId: string, groupName: string): Promise<string | null> {
+  return (await liveTranscriptPath(sessionId)) ?? archivedTranscriptPath(sessionId, groupName);
+}