@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.5

package/src/default-agents.ts

@@ -0,0 +1,126 @@
+/**
+ * default-agents.ts — Embedded default agent configurations.
+ *
+ * These are always available but can be overridden by user .md files with the same name.
+ */
+
+import type { AgentConfig } from "./types.js";
+
+const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+
+export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
+  [
+    "general-purpose",
+    {
+      name: "general-purpose",
+      displayName: "Agent",
+      description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.",
+      // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
+      // inheritContext / runInBackground / isolated omitted — strategy fields, callers decide per-call.
+      // Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
+      extensions: true,
+      skills: true,
+      systemPrompt: "",
+      promptMode: "append",
+      isDefault: true,
+    },
+  ],
+  [
+    "Explore",
+    {
+      name: "Explore",
+      displayName: "Explore",
+      description: "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.",
+      builtinToolNames: READ_ONLY_TOOLS,
+      extensions: true,
+      skills: true,
+      // Fast/cheap portable default for read-only search. A target-local alias
+      // can select its canonical provider; otherwise fuzzy resolution finds a
+      // matching enabled model under any provider.
+      model: "claude-haiku-4-5",
+      systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise`,
+      promptMode: "replace",
+      isDefault: true,
+    },
+  ],
+  [
+    "Plan",
+    {
+      name: "Plan",
+      displayName: "Plan",
+      description: "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",
+      builtinToolNames: READ_ONLY_TOOLS,
+      extensions: true,
+      skills: true,
+      systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a software architect and planning specialist.
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+# Planning Process
+1. Understand requirements
+2. Explore thoroughly (read files, find patterns, understand architecture)
+3. Design solution based on your assigned perspective
+4. Detail the plan with step-by-step implementation strategy
+
+# Requirements
+- Consider trade-offs and architectural decisions
+- Identify dependencies and sequencing
+- Anticipate potential challenges
+- Follow existing patterns where appropriate
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+
+# Output Format
+- Use absolute file paths
+- Do not use emojis
+- End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- /absolute/path/to/file.ts - [Brief reason]`,
+      promptMode: "replace",
+      isDefault: true,
+    },
+  ],
+]);

package/src/detached-results.ts

@@ -0,0 +1,134 @@
+/**
+ * detached-results.ts -- hand completed background agents back to a session
+ * after the extension instance that spawned them is gone.
+ *
+ * `/new`, `/resume`, `/fork` and `/reload` shut the extension down but keep the
+ * process alive. Background agents are allowed to finish in the orphaned
+ * manager, which can no longer talk to pi (its `pi` handle is stale), so each
+ * result is spooled to disk keyed by the PARENT session file. The extension
+ * instance bound to that session drains the spool on `session_start`, and while
+ * it is active a process-wide sink wakes it for results that land later.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentRecord } from "./types.js";
+import type { AgentActivity } from "./ui/agent-widget.js";
+
+/** One finished agent, in the shape `session_start` needs to re-announce it. */
+export interface DetachedResult {
+  id: string;
+  /** Pre-rendered `<task-notification>` text for the LLM. */
+  content: string;
+  /** `subagent-notification` renderer details. */
+  details: unknown;
+  /** History entry for a result that finished detached; absent if already appended. */
+  record?: Record<string, unknown>;
+}
+
+const SINK_KEY = Symbol.for("pi-subagents:detached-sink");
+
+/** Per-session wake-ups, shared across every extension instance in the process. */
+function sinks(): Map<string, () => void> {
+  const g = globalThis as Record<symbol, unknown>;
+  let map = g[SINK_KEY] as Map<string, () => void> | undefined;
+  if (!map) {
+    map = new Map();
+    g[SINK_KEY] = map;
+  }
+  return map;
+}
+
+/** Spool directory for one parent session (created on demand, owner-only). */
+export function detachedDir(sessionFile: string): string {
+  const key = createHash("sha256").update(sessionFile).digest("hex").slice(0, 16);
+  const dir = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`, "detached", key);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+/** Persist a result for `sessionFile` and wake its live extension instance, if any. */
+export function spoolDetached(sessionFile: string, result: DetachedResult): void {
+  const dir = detachedDir(sessionFile);
+  const name = `${Date.now()}-${result.id.replace(/[^\w.-]/g, "_")}.json`;
+  // Rename into place so a concurrent drain never reads a half-written file.
+  const tmp = join(dir, `.${name}.tmp`);
+  writeFileSync(tmp, JSON.stringify(result), { mode: 0o600 });
+  renameSync(tmp, join(dir, name));
+  try {
+    sinks().get(sessionFile)?.();
+  } catch {
+    // The woken instance is already shutting down; the file stays for the next drain.
+  }
+}
+
+/** Read and delete every spooled result for `sessionFile`, oldest first. Unreadable files are dropped. */
+export function drainDetached(sessionFile: string): DetachedResult[] {
+  const dir = detachedDir(sessionFile);
+  const out: DetachedResult[] = [];
+  for (const name of readdirSync(dir).filter(n => n.endsWith(".json") && !n.startsWith(".")).sort()) {
+    const path = join(dir, name);
+    try {
+      out.push(JSON.parse(readFileSync(path, "utf8")) as DetachedResult);
+    } catch {
+      // Corrupt spool entry: nothing recoverable, and retrying it forever helps nobody.
+    }
+    rmSync(path, { force: true });
+  }
+  return out;
+}
+
+/** Call `onSpooled` whenever a result lands for `sessionFile`. Returns the unsubscribe. */
+export function watchDetached(sessionFile: string, onSpooled: () => void): () => void {
+  const map = sinks();
+  map.set(sessionFile, onSpooled);
+  return () => {
+    if (map.get(sessionFile) === onSpooled) map.delete(sessionFile);
+  };
+}
+
+/**
+ * A background agent still running in an orphaned manager. The record and
+ * activity are the orphan's live objects, so a reloaded session can show and
+ * open them; `abort` and `steer` are bound to the orphan's manager.
+ */
+export interface RunningDetached {
+  record: AgentRecord;
+  activity?: AgentActivity;
+  abort(): boolean;
+  steer(message: string): boolean;
+}
+
+const RUNNING_KEY = Symbol.for("pi-subagents:detached-running");
+
+/** Running orphans by parent session file then agent id, shared across every extension instance. */
+function running(): Map<string, Map<string, RunningDetached>> {
+  const g = globalThis as Record<symbol, unknown>;
+  let map = g[RUNNING_KEY] as Map<string, Map<string, RunningDetached>> | undefined;
+  if (!map) {
+    map = new Map();
+    g[RUNNING_KEY] = map;
+  }
+  return map;
+}
+
+/** Publish an orphaned, still-running agent so the session's next extension instance can list it. */
+export function registerRunningDetached(sessionFile: string, agent: RunningDetached): void {
+  const byId = running().get(sessionFile) ?? new Map<string, RunningDetached>();
+  byId.set(agent.record.id, agent);
+  running().set(sessionFile, byId);
+}
+
+/** Drop an orphan once it settles (its result is spooled from there on). */
+export function unregisterRunningDetached(sessionFile: string, id: string): void {
+  const byId = running().get(sessionFile);
+  byId?.delete(id);
+  if (byId?.size === 0) running().delete(sessionFile);
+}
+
+/** Orphans still running for `sessionFile`, in registration order. */
+export function listRunningDetached(sessionFile: string | undefined): RunningDetached[] {
+  if (sessionFile === undefined) return [];
+  return [...(running().get(sessionFile)?.values() ?? [])];
+}

package/src/enabled-models.ts

@@ -0,0 +1,180 @@
+/**
+ * Reads `enabledModels` from pi's settings (global `<agentDir>/settings.json`
+ * + project-local `<cwd>/.pi/settings.json`, project wins) and resolves
+ * entries to concrete `provider/modelId` keys for scope validation.
+ *
+ * **Project overrides global**, mirroring pi's own `SettingsManager`
+ * deep-merge behavior and matching the precedence we use for our own
+ * `subagents.json` settings (see `src/settings.ts:loadSettings`). If
+ * project file has `enabledModels` set, it wholly replaces global's
+ * (array fields are replaced, not concatenated).
+ *
+ * **Limited subset of upstream's resolveModelScope.** We support exact
+ * `provider/modelId` matching only. Upstream (pi-coding-agent's
+ * `core/model-resolver.ts`) additionally supports glob patterns
+ * (`*sonnet*`, `anthropic/*`), bare model IDs without provider, and
+ * thinking-level suffixes (`provider/*:high`). Those forms are silently
+ * ignored here.
+ *
+ * In practice, pi's `/scoped-models` picker writes exact `provider/modelId`
+ * entries, so the limitation is invisible for users who configure scope
+ * through pi's UI. Hand-edited settings using globs or bare IDs will
+ * produce an empty allowed set (scope check becomes a no-op).
+ *
+ * Example:
+ *   enabledModels = ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"]
+ *   → resolves to { "anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6" }
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ModelEntry } from "./model-resolver.js";
+
+/** Minimal registry shape — only the methods resolveEnabledModels actually calls. */
+export interface ModelRegistryRef {
+  getAll(): unknown[];
+  getAvailable?(): unknown[];
+}
+
+/** Paths to pi's settings.json files: [project, global] (project takes precedence). */
+function settingsPaths(cwd: string): [project: string, global: string] {
+  return [
+    join(cwd, ".pi", "settings.json"),
+    join(getAgentDir(), "settings.json"),
+  ];
+}
+
+/** Read `enabledModels` from a single settings.json file. Undefined when missing or absent. */
+function readField(path: string): string[] | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8"));
+    if (Array.isArray(raw?.enabledModels)) return raw.enabledModels as string[];
+  } catch {
+    /* corrupt file — silent */
+  }
+  return undefined;
+}
+
+/**
+ * Read enabledModels from pi's settings — project-local overrides global.
+ * Mirrors pi's SettingsManager deep-merge for the `enabledModels` field
+ * (and matches our own loadSettings precedence in src/settings.ts).
+ * Returns undefined when neither file has the field.
+ */
+export function readEnabledModels(cwd: string): string[] | undefined {
+  const [project, global] = settingsPaths(cwd);
+  return readField(project) ?? readField(global);
+}
+
+/**
+ * Resolve enabledModels patterns → Set<"provider/modelId"> (lowercase keys).
+ *
+ * Only exact `provider/modelId` patterns are matched (case-insensitive).
+ * Patterns without a slash, with glob characters, or with a `:thinking`
+ * suffix are silently dropped. See module-level docstring for rationale.
+ *
+ * Cache: keyed on JSON.stringify(patterns) + mtime/size of *both*
+ * project and global settings.json files. Re-resolves when either file
+ * changes or the patterns argument differs.
+ *
+ * Returns undefined when no patterns are provided or no patterns match
+ * (scope check becomes a no-op at the call site).
+ */
+
+// Module-level cache — invalidated when either settings.json changes or patterns differ.
+let cachedAllowed: Set<string> | undefined;
+let cachedHash = "";
+let cachedPatternsKey = "";
+
+/** mtime+size hash of one file, or "missing" if absent. */
+function hashOf(path: string): string {
+  try {
+    const s = statSync(path);
+    return `${s.mtimeMs}-${s.size}`;
+  } catch {
+    return "missing";
+  }
+}
+
+export function resolveEnabledModels(
+  patterns: string[] | undefined,
+  registry: ModelRegistryRef,
+  cwd: string = process.cwd(),
+): Set<string> | undefined {
+  // Fast path: check cache (stat both project and global settings.json files)
+  const patternsKey = JSON.stringify(patterns);
+  const [project, global] = settingsPaths(cwd);
+  const fileHash = `${hashOf(project)};${hashOf(global)}`;
+
+  if (fileHash === cachedHash && patternsKey === cachedPatternsKey) {
+    return cachedAllowed;
+  }
+
+  // Cache miss — resolve
+  if (!patterns || patterns.length === 0) {
+    cachedHash = fileHash;
+    cachedPatternsKey = patternsKey;
+    cachedAllowed = undefined;
+    return undefined;
+  }
+
+  const available = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
+  const allowed = new Set<string>();
+
+  for (const pattern of patterns) {
+    const trimmed = pattern.trim();
+    if (!trimmed) continue;  // skip empty/whitespace
+    resolveExact(trimmed, available, allowed);
+  }
+
+  const result = allowed.size > 0 ? allowed : undefined;
+  cachedHash = fileHash;
+  cachedPatternsKey = patternsKey;
+  cachedAllowed = result;
+  return result;
+}
+
+
+
+/**
+ * True when `model` is in the allowed set. Centralizes the key format
+ * (`provider/id` lowercase) so callers don't have to reproduce it —
+ * both set-building (resolveExact) and lookup go through `modelKey`.
+ */
+export function isModelInScope(
+  model: { provider: string; id: string },
+  allowed: Set<string>,
+): boolean {
+  return allowed.has(modelKey(model));
+}
+
+/** Canonical lowercase `provider/id` key for the allowed set. */
+function modelKey(model: { provider: string; id: string }): string {
+  return `${model.provider}/${model.id}`.toLowerCase();
+}
+
+/**
+ * Resolve exact model pattern. Example: "google/gemma-4-31b-it".
+ */
+function resolveExact(
+  pattern: string,
+  available: ModelEntry[],
+  allowed: Set<string>,
+): void {
+  // "provider/modelId" — exact (colon is part of id, not split)
+  const slashIdx = pattern.indexOf("/");
+  if (slashIdx === -1) return; // bare modelId not supported
+
+  const provider = pattern.slice(0, slashIdx).toLowerCase();
+  const modelId = pattern.slice(slashIdx + 1).toLowerCase();
+  const exact = available.find(
+    m => m.provider.toLowerCase() === provider && m.id.toLowerCase() === modelId,
+  );
+  if (exact) {
+    allowed.add(modelKey(exact));
+  }
+}
+
+

package/src/enterprise-local.ts

@@ -0,0 +1,66 @@
+/**
+ * Optional machine-local enterprise overlay.
+ *
+ * This extension deliberately knows no enterprise provider, endpoint, model, or
+ * credential. A user-provisioned manifest lives beside Pi's other private state
+ * at `<agentDir>/enterprise.local.json`; it is never read from a project.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const MANIFEST_VERSION = 1;
+const MANIFEST_NAME = "enterprise.local.json";
+
+export interface EnterpriseLocalManifest {
+  version: number;
+  settings?: Record<string, unknown>;
+  models?: { providers?: Record<string, unknown> };
+  subagents?: Record<string, unknown>;
+}
+
+/** Return the target-local manifest path without reading it. */
+export function enterpriseLocalPath(): string {
+  return join(getAgentDir(), MANIFEST_NAME);
+}
+
+/**
+ * Read and minimally validate the machine-local manifest. It never exposes its
+ * contents in diagnostics: providers can include command-backed credentials.
+ */
+export function readEnterpriseLocalManifest(): EnterpriseLocalManifest | undefined {
+  const path = enterpriseLocalPath();
+  if (!existsSync(path)) return undefined;
+
+  try {
+    const mode = statSync(path).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+      console.warn(`[pi-subagents] Ignoring ${path}: permissions must not grant group or other access.`);
+      return undefined;
+    }
+    const raw: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new Error("expected a JSON object");
+    }
+    const manifest = raw as Record<string, unknown>;
+    if (manifest.version !== MANIFEST_VERSION) {
+      throw new Error(`unsupported manifest version (expected ${MANIFEST_VERSION})`);
+    }
+    for (const section of ["settings", "models", "subagents"] as const) {
+      const value = manifest[section];
+      if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
+        throw new Error(`section "${section}" must be an object`);
+      }
+    }
+    const models = manifest.models as Record<string, unknown> | undefined;
+    if (models?.providers !== undefined && (!models.providers || typeof models.providers !== "object" || Array.isArray(models.providers))) {
+      throw new Error('section "models.providers" must be an object');
+    }
+    return manifest as unknown as EnterpriseLocalManifest;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    console.warn(`[pi-subagents] Ignoring invalid ${path}: ${reason}`);
+    return undefined;
+  }
+}

package/src/env.ts

@@ -0,0 +1,33 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { EnvInfo } from "./types.js";
+
+export async function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo> {
+  let isGitRepo = false;
+  let branch = "";
+
+  try {
+    const result = await pi.exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
+    isGitRepo = result.code === 0 && result.stdout.trim() === "true";
+  } catch {
+    // Not a git repo or git not installed
+  }
+
+  if (isGitRepo) {
+    try {
+      const result = await pi.exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
+      branch = result.code === 0 ? result.stdout.trim() : "unknown";
+    } catch {
+      branch = "unknown";
+    }
+  }
+
+  return {
+    isGitRepo,
+    branch,
+    platform: process.platform,
+  };
+}

package/src/group-join.ts

@@ -0,0 +1,148 @@
+/**
+ * group-join.ts — Manages grouped background agent completion notifications.
+ *
+ * Instead of each agent individually nudging the main agent on completion,
+ * agents in a group are held until all complete (or a timeout fires),
+ * then a single consolidated notification is sent.
+ */
+
+import type { AgentRecord } from "./types.js";
+
+export type DeliveryCallback = (records: AgentRecord[], partial: boolean) => void;
+
+interface AgentGroup {
+  groupId: string;
+  agentIds: Set<string>;
+  completedRecords: Map<string, AgentRecord>;
+  timeoutHandle?: ReturnType<typeof setTimeout>;
+  delivered: boolean;
+  /** Shorter timeout for stragglers after a partial delivery. */
+  isStraggler: boolean;
+}
+
+/** Default timeout: 30s after first completion in a group. */
+const DEFAULT_TIMEOUT = 30_000;
+/** Straggler re-batch timeout: 15s. */
+const STRAGGLER_TIMEOUT = 15_000;
+
+export class GroupJoinManager {
+  private groups = new Map<string, AgentGroup>();
+  private agentToGroup = new Map<string, string>();
+
+  constructor(
+    private deliverCb: DeliveryCallback,
+    private groupTimeout = DEFAULT_TIMEOUT,
+  ) {}
+
+  /** Register a group of agent IDs that should be joined. */
+  registerGroup(groupId: string, agentIds: string[]): void {
+    const group: AgentGroup = {
+      groupId,
+      agentIds: new Set(agentIds),
+      completedRecords: new Map(),
+      delivered: false,
+      isStraggler: false,
+    };
+    this.groups.set(groupId, group);
+    for (const id of agentIds) {
+      this.agentToGroup.set(id, groupId);
+    }
+  }
+
+  /**
+   * Called when an agent completes.
+   * Returns:
+   * - 'pass'      — agent is not grouped, caller should send individual nudge
+   * - 'held'      — result held, waiting for group completion
+   * - 'delivered'  — this completion triggered the group notification
+   */
+  onAgentComplete(record: AgentRecord): 'delivered' | 'held' | 'pass' {
+    const groupId = this.agentToGroup.get(record.id);
+    if (!groupId) return 'pass';
+
+    const group = this.groups.get(groupId);
+    if (!group || group.delivered) return 'pass';
+
+    group.completedRecords.set(record.id, record);
+
+    // All done — deliver immediately
+    if (group.completedRecords.size >= group.agentIds.size) {
+      this.deliver(group, false);
+      return 'delivered';
+    }
+
+    // First completion in this batch — start timeout
+    if (!group.timeoutHandle) {
+      const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
+      group.timeoutHandle = setTimeout(() => {
+        this.onTimeout(group);
+      }, timeout);
+    }
+
+    return 'held';
+  }
+
+  private onTimeout(group: AgentGroup): void {
+    if (group.delivered) return;
+    group.timeoutHandle = undefined;
+
+    // Partial delivery — some agents still running
+    const remaining = new Set<string>();
+    for (const id of group.agentIds) {
+      if (!group.completedRecords.has(id)) remaining.add(id);
+    }
+
+    // Clean up agentToGroup for delivered agents (they won't complete again)
+    for (const id of group.completedRecords.keys()) {
+      this.agentToGroup.delete(id);
+    }
+
+    // Deliver what we have
+    this.deliverCb([...group.completedRecords.values()], true);
+
+    // Set up straggler group for remaining agents
+    group.completedRecords.clear();
+    group.agentIds = remaining;
+    group.isStraggler = true;
+    // Timeout will be started when the next straggler completes
+  }
+
+  private deliver(group: AgentGroup, partial: boolean): void {
+    if (group.timeoutHandle) {
+      clearTimeout(group.timeoutHandle);
+      group.timeoutHandle = undefined;
+    }
+    group.delivered = true;
+    this.deliverCb([...group.completedRecords.values()], partial);
+    this.cleanupGroup(group.groupId);
+  }
+
+  private cleanupGroup(groupId: string): void {
+    const group = this.groups.get(groupId);
+    if (!group) return;
+    for (const id of group.agentIds) {
+      this.agentToGroup.delete(id);
+    }
+    this.groups.delete(groupId);
+  }
+
+  /** Check if an agent is in a group. */
+  isGrouped(agentId: string): boolean {
+    return this.agentToGroup.has(agentId);
+  }
+
+  /** Release held completions to the outbox before a session transfer. */
+  flushPending(): void {
+    for (const group of [...this.groups.values()]) {
+      this.deliver(group, true);
+    }
+  }
+
+  dispose(): void {
+    for (const group of this.groups.values()) {
+      if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
+    }
+    this.groups.clear();
+    this.agentToGroup.clear();
+  }
+}