@pruddiman/hem 0.0.1-beta-5671db0

package/dist/agents/crossref-agent.js

@@ -0,0 +1,560 @@
+/**
+ * LLM-assisted cross-reference agent for Hem.
+ *
+ * Post-processing agent that runs AFTER the organization agent.
+ * Reads all generated documentation files and adds inter-document links
+ * (cross-references) to improve navigation.
+ *
+ * Architecture (v2 — parallel workers with broadcast):
+ *   - Reads all generated docs from disk.
+ *   - Adds cross-reference links between related pages.
+ *   - For large file sets (>8 files), splits work across N parallel workers.
+ *   - Workers communicate via an MCP broadcast tool + prompt injection.
+ *   - The orchestrator intercepts broadcast tool calls via SSE and relays
+ *     messages to all peer workers + their active subagents.
+ *   - For small file sets (≤8 files), falls back to the single-agent path.
+ *   - The pipeline discovers the final file set by scanning disk afterward.
+ */
+import { AuthExpiredError } from "../auth.js";
+import { BaseAgent } from "./base-agent.js";
+import { computeMaxConcurrency } from "../resources.js";
+import { CrossRefArbiterAgent } from "./crossref-arbiter-agent.js";
+import { BROADCAST_TOOL_NAME } from "./organization-agent.js";
+// ── Constants ───────────────────────────────────────────────────────────
+/** File count threshold: use parallel workers above this, single agent below. */
+export const XREF_PARALLEL_THRESHOLD = 8;
+/**
+ * Hard ceiling on parallel cross-ref workers.  The actual worker count is
+ * `min(XREF_MAX_WORKERS, computeMaxConcurrency(), fileCount)`.
+ * The arbiter is excluded from this cap (it is lightweight).
+ */
+export const XREF_MAX_WORKERS = 4;
+// ── Agent ───────────────────────────────────────────────────────────────
+/**
+ * An agent that reads all generated documentation and adds inter-document
+ * cross-reference links for improved navigation.
+ *
+ * Edits files directly via the edit tool. The pipeline discovers the
+ * final file set by scanning disk afterward.
+ */
+export class CrossRefAgent extends BaseAgent {
+    constructor(provider) {
+        super(provider);
+    }
+    /**
+     * Run the cross-reference pass over all generated documentation.
+     * Automatically selects single-agent or parallel mode based on file count.
+     *
+     * @param params  - Cross-reference parameters including file paths.
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    async run(params, verbose) {
+        if (params.allDocFiles.length > XREF_PARALLEL_THRESHOLD) {
+            return this.runParallel(params, verbose);
+        }
+        return this.runSingle(params, verbose);
+    }
+    /**
+     * Single-agent cross-reference pass (original behavior).
+     * Used when file count is ≤ XREF_PARALLEL_THRESHOLD.
+     */
+    async runSingle(params, verbose) {
+        const tag = "xref-agent";
+        // 1. Build prompt
+        const prompt = CrossRefAgent.buildPrompt(params);
+        if (verbose) {
+            verbose(`[${tag}] Prompt: ${prompt.length.toLocaleString()} chars`);
+        }
+        // 2. Create a new session
+        const sessionId = await this.createSession("Hem: cross-references");
+        if (verbose) {
+            verbose(`[${tag}] Session created: ${sessionId}`);
+        }
+        // 3. Send prompt — use hem-xref agent
+        await this.provider.prompt(sessionId, prompt, { agent: "hem-xref" });
+        if (verbose) {
+            verbose(`[${tag}] Agent completed`);
+        }
+    }
+    /**
+     * Parallel cross-reference pass using multiple workers with an arbiter.
+     *
+     * 1. Computes worker count from resource limits (arbiter excluded).
+     * 2. Assigns files to workers via round-robin.
+     * 3. Subscribes to SSE events for broadcast interception.
+     * 4. Creates an arbiter session (long-lived coordinator).
+     * 5. Creates N worker sessions in parallel.
+     * 6. Relays broadcasts with targeted routing:
+     *    - Worker → arbiter only.
+     *    - Arbiter → @tagged worker(s) only (or all if @all-workers / no tag).
+     *    - Completed sessions are excluded from relay.
+     * 7. Kills worker sessions immediately on completion (abort + delete).
+     * 8. Intercepts RECALL: broadcasts to respawn a worker for fixes.
+     * 9. Sends a final prompt to the arbiter so it can wrap up.
+     * 10. Kills the arbiter session.
+     */
+    async runParallel(params, verbose) {
+        const tag = "xref-parallel";
+        const { projectName, destinationPath, allDocFiles } = params;
+        // 1. Compute effective worker count from resource limits (arbiter excluded)
+        const resourceCap = computeMaxConcurrency();
+        const effectiveMaxWorkers = Math.min(XREF_MAX_WORKERS, resourceCap);
+        const assignments = assignXrefFilesToWorkers(allDocFiles, effectiveMaxWorkers);
+        if (verbose) {
+            verbose(`[${tag}] Resource cap: ${resourceCap} sessions (arbiter excluded)`);
+            verbose(`[${tag}] Splitting ${allDocFiles.length} files across ${assignments.length} workers + 1 arbiter`);
+            for (const a of assignments) {
+                verbose(`[${tag}]   ${a.label}: ${a.files.length} files`);
+            }
+        }
+        // 2. Session tracking
+        //    allSessions: sessionId → label (live sessions only — removed on kill)
+        //    workerSessionIds: set of worker session IDs (for routing logic)
+        //    completedSessions: workers that finished (excluded from relay)
+        //    childSessions: childSessionId → parentSessionId (subagent tracking)
+        const allSessions = new Map();
+        const workerSessionIds = new Set();
+        const completedSessions = new Set();
+        const childSessions = new Map();
+        // Store arbiter session ID at this scope so the relay can identify it
+        let arbiterSessionId = "";
+        // Keep a reference to the original assignments for RECALL
+        const assignmentsByLabel = new Map();
+        for (const a of assignments) {
+            assignmentsByLabel.set(a.label, a);
+        }
+        // Pending recall promises collected asynchronously
+        const pendingRecalls = [];
+        // 3. Subscribe to SSE events for broadcast interception
+        //    (NO DecisionQueue — cross-ref workers only add links, no MERGE/DELETE)
+        let sseStream = null;
+        let sseLoopDone = false;
+        const startSseRelay = async () => {
+            try {
+                const subscribeResult = await this.provider.event.subscribe();
+                sseStream = subscribeResult.stream;
+            }
+            catch (err) {
+                if (verbose) {
+                    verbose(`[${tag}] ⚠ Failed to subscribe to SSE events: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return;
+            }
+            if (verbose) {
+                verbose(`[${tag}] SSE relay started`);
+            }
+            try {
+                for await (const rawEvent of sseStream) {
+                    if (sseLoopDone)
+                        break;
+                    const event = rawEvent;
+                    if (!event.type || !event.properties)
+                        continue;
+                    if (event.type === "message.part.updated") {
+                        const part = event.properties.part;
+                        if (!part || part.type !== "tool")
+                            continue;
+                        // ── Detect broadcast tool calls ──────────────────────
+                        if (part.tool === BROADCAST_TOOL_NAME &&
+                            part.state?.status === "running" &&
+                            part.sessionID &&
+                            part.state.input) {
+                            const message = part.state.input.message;
+                            const senderSessionId = part.sessionID;
+                            const senderLabel = allSessions.get(senderSessionId);
+                            if (message && senderLabel) {
+                                if (verbose) {
+                                    verbose(`[${tag}] 📢 Broadcast from ${senderLabel}: ${message}`);
+                                }
+                                // ── RECALL interception ──────────────────────────
+                                // If the arbiter broadcasts "RECALL: @xref-worker-N <instructions>",
+                                // intercept it and spawn a new focused worker session.
+                                const recallMatch = message.match(/^RECALL:\s*@(xref-worker-\d+)\s+([\s\S]+)/i);
+                                if (recallMatch && !workerSessionIds.has(senderSessionId)) {
+                                    const targetLabel = recallMatch[1];
+                                    const instructions = recallMatch[2];
+                                    const originalAssignment = assignmentsByLabel.get(targetLabel);
+                                    if (originalAssignment) {
+                                        if (verbose) {
+                                            verbose(`[${tag}] 🔄 Recalling ${targetLabel} for fixes`);
+                                        }
+                                        const recallPromise = this.runRecalledWorker(projectName, destinationPath, originalAssignment, allDocFiles, assignments.length, instructions, verbose).catch((err) => {
+                                            if (verbose) {
+                                                verbose(`[${tag}] ✗ Recall of ${targetLabel} failed: ${err instanceof Error ? err.message : String(err)}`);
+                                            }
+                                        });
+                                        pendingRecalls.push(recallPromise);
+                                    }
+                                    else if (verbose) {
+                                        verbose(`[${tag}] ⚠ RECALL target ${targetLabel} not found in assignments`);
+                                    }
+                                    // Don't relay RECALL messages — the orchestrator handles them
+                                    continue;
+                                }
+                                // ── Targeted routing ─────────────────────────────
+                                const relayText = `Message from ${senderLabel}: ${message}`;
+                                const relayTargets = [];
+                                const senderIsWorker = workerSessionIds.has(senderSessionId);
+                                if (senderIsWorker) {
+                                    // Worker → always relay to arbiter only
+                                    if (arbiterSessionId && !completedSessions.has(arbiterSessionId)) {
+                                        relayTargets.push({ id: arbiterSessionId, label: "xref-arbiter" });
+                                    }
+                                }
+                                else {
+                                    // Arbiter → check for @tags in message
+                                    const tagPattern = /@(xref-worker-\d+)/g;
+                                    const tags = [...message.matchAll(tagPattern)].map(m => m[1]);
+                                    const isAllWorkers = /@all-workers/i.test(message);
+                                    if (tags.length > 0 && !isAllWorkers) {
+                                        // Route to specifically tagged workers only
+                                        for (const [sessionId, label] of allSessions) {
+                                            if (sessionId === senderSessionId)
+                                                continue;
+                                            if (completedSessions.has(sessionId))
+                                                continue;
+                                            if (tags.some(t => label === t)) {
+                                                relayTargets.push({ id: sessionId, label });
+                                            }
+                                        }
+                                    }
+                                    else {
+                                        // @all-workers or no tags → broadcast to all live workers
+                                        for (const [sessionId, label] of allSessions) {
+                                            if (sessionId === senderSessionId)
+                                                continue;
+                                            if (completedSessions.has(sessionId))
+                                                continue;
+                                            if (workerSessionIds.has(sessionId)) {
+                                                relayTargets.push({ id: sessionId, label });
+                                            }
+                                        }
+                                    }
+                                }
+                                // Also include active subagents of each relay target
+                                const subagentTargets = [];
+                                for (const target of relayTargets) {
+                                    for (const [childId, parentId] of childSessions) {
+                                        if (parentId === target.id && !completedSessions.has(childId)) {
+                                            subagentTargets.push({ id: childId, label: `${target.label}/subagent` });
+                                        }
+                                    }
+                                }
+                                relayTargets.push(...subagentTargets);
+                                // Fire relay prompts concurrently (fire-and-forget)
+                                if (relayTargets.length > 0) {
+                                    const relayPromises = relayTargets.map(async (target) => {
+                                        try {
+                                            await this.provider.session.promptAsync({
+                                                path: { id: target.id },
+                                                body: {
+                                                    parts: [{ type: "text", text: relayText }],
+                                                    agent: "hem-xref",
+                                                },
+                                            });
+                                            if (verbose) {
+                                                verbose(`[${tag}]   → Relayed to ${target.label} (${target.id.slice(0, 8)}…)`);
+                                            }
+                                        }
+                                        catch (err) {
+                                            if (verbose) {
+                                                verbose(`[${tag}]   ✗ Relay to ${target.label} failed: ${err instanceof Error ? err.message : String(err)}`);
+                                            }
+                                        }
+                                    });
+                                    // Don't await — let relays happen async while SSE loop continues
+                                    void Promise.allSettled(relayPromises);
+                                }
+                            }
+                        }
+                    }
+                    // ── Track child sessions via session.created events ────
+                    if (event.type === "session.created") {
+                        const props = event.properties;
+                        if (props.session?.id && props.session.parentID) {
+                            const parentId = props.session.parentID;
+                            // Only track if the parent is one of our sessions (worker or arbiter)
+                            if (allSessions.has(parentId)) {
+                                childSessions.set(props.session.id, parentId);
+                                if (verbose) {
+                                    const parentLabel = allSessions.get(parentId);
+                                    verbose(`[${tag}] · Subagent ${props.session.id.slice(0, 8)}… spawned by ${parentLabel}`);
+                                }
+                            }
+                            // Also check if parent is itself a tracked child (nested subagents)
+                            else if (childSessions.has(parentId)) {
+                                const rootParent = childSessions.get(parentId);
+                                childSessions.set(props.session.id, rootParent);
+                                if (verbose) {
+                                    const rootLabel = allSessions.get(rootParent);
+                                    verbose(`[${tag}] · Nested subagent ${props.session.id.slice(0, 8)}… (root: ${rootLabel})`);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                // SSE stream can error when the server shuts down or on network issues.
+                // This is expected during cleanup — only log if we're still running.
+                if (!sseLoopDone && verbose) {
+                    verbose(`[${tag}] ⚠ SSE stream error: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        };
+        // Start SSE relay in background (don't await — runs concurrently)
+        const sseRelayPromise = startSseRelay();
+        try {
+            // 4. Create arbiter session (long-lived coordinator) via CrossRefArbiterAgent
+            const arbiter = new CrossRefArbiterAgent(this.provider);
+            const { sessionId: aId } = await arbiter.run({
+                projectName,
+                destinationPath,
+                allDocFiles,
+                workerAssignments: assignments,
+            }, verbose);
+            arbiterSessionId = aId;
+            allSessions.set(arbiterSessionId, "xref-arbiter");
+            // 5. Create worker sessions and send prompts concurrently
+            const workerPromises = assignments.map(async (assignment) => {
+                const prompt = CrossRefAgent.buildWorkerPrompt({
+                    projectName,
+                    destinationPath,
+                    assignedFiles: assignment.files,
+                    allDocFiles,
+                    workerLabel: assignment.label,
+                    totalWorkers: assignments.length,
+                });
+                if (verbose) {
+                    verbose(`[${tag}] ${assignment.label}: prompt ${prompt.length.toLocaleString()} chars`);
+                }
+                // Create session
+                const sessionId = await this.createSession(`Hem: ${assignment.label}`);
+                allSessions.set(sessionId, assignment.label);
+                workerSessionIds.add(sessionId);
+                if (verbose) {
+                    verbose(`[${tag}] ${assignment.label}: session ${sessionId}`);
+                }
+                // Send prompt and wait for completion
+                await this.provider.prompt(sessionId, prompt, { agent: "hem-xref" });
+                // ── Kill the worker session immediately ──────────────────
+                // Worker is done — free resources.  Mark as completed first
+                // so the relay loop stops sending messages to it, then abort
+                // and delete the session.
+                completedSessions.add(sessionId);
+                allSessions.delete(sessionId);
+                await this.killSession(sessionId, assignment.label, verbose);
+            });
+            // 6. Wait for all workers to complete
+            const results = await Promise.allSettled(workerPromises);
+            // 7. Check for auth errors first
+            for (const result of results) {
+                if (result.status === "rejected" &&
+                    result.reason instanceof AuthExpiredError) {
+                    throw result.reason;
+                }
+            }
+            // 8. Signal the arbiter that all workers are done
+            await arbiter.wrapUp(arbiterSessionId, verbose);
+            // 9. Wait for any pending recall sessions spawned during arbiter wrap-up
+            if (pendingRecalls.length > 0) {
+                if (verbose) {
+                    verbose(`[${tag}] Waiting for ${pendingRecalls.length} pending recall(s)...`);
+                }
+                await Promise.allSettled(pendingRecalls);
+            }
+            // 10. Kill the arbiter session
+            completedSessions.add(arbiterSessionId);
+            allSessions.delete(arbiterSessionId);
+            await this.killSession(arbiterSessionId, "xref-arbiter", verbose);
+            // 11. Log any worker failures (the pipeline discovers files via disk scan)
+            for (let i = 0; i < results.length; i++) {
+                const result = results[i];
+                const label = assignments[i].label;
+                if (result.status === "rejected") {
+                    const msg = result.reason instanceof Error
+                        ? result.reason.message
+                        : String(result.reason);
+                    if (verbose) {
+                        verbose(`[${tag}] ✗ ${label} failed: ${msg}`);
+                    }
+                }
+                else if (verbose) {
+                    verbose(`[${tag}] ✓ ${label} completed`);
+                }
+            }
+        }
+        finally {
+            // 12. Stop the SSE relay loop
+            sseLoopDone = true;
+            // The SSE stream will naturally close when the server shuts down,
+            // but we set the flag so any in-flight iterations exit cleanly.
+            await Promise.race([
+                sseRelayPromise,
+                new Promise((resolve) => setTimeout(resolve, 1000)),
+            ]);
+        }
+    }
+    /**
+     * Kill a session: abort any running work, then delete the session.
+     * Best-effort — failures are logged but not thrown.
+     */
+    async killSession(sessionId, label, verbose) {
+        try {
+            await this.provider.session.abort({ path: { id: sessionId } });
+        }
+        catch {
+            // Session may already be idle — abort failing is fine
+        }
+        try {
+            await this.provider.session.delete({ path: { id: sessionId } });
+            if (verbose) {
+                verbose(`[xref-parallel] 🗑 Killed session ${label} (${sessionId.slice(0, 8)}…)`);
+            }
+        }
+        catch (err) {
+            if (verbose) {
+                verbose(`[xref-parallel] ⚠ Failed to delete session ${label}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * Spawn a recalled worker session to apply specific fixes.
+     *
+     * Called when the arbiter broadcasts `RECALL: @xref-worker-N <instructions>`.
+     * Creates a new session with the worker's original file assignment and a
+     * focused prompt containing the fix instructions.  The session is killed
+     * immediately after completion.
+     */
+    async runRecalledWorker(projectName, destinationPath, assignment, _allDocFiles, _totalWorkers, instructions, verbose) {
+        const tag = `recall-${assignment.label}`;
+        const prompt = [
+            `Worker **${assignment.label}** (recalled). Previously added cross-reference`,
+            `links for **${projectName}** and the arbiter found link consistency issues.`,
+            "",
+            "## Destination directory",
+            "",
+            `All documentation files are in: \`${destinationPath}\``,
+            "",
+            "## Your assigned files",
+            "",
+            ...assignment.files.map((f) => `- \`${destinationPath}/${f}\``),
+            "",
+            "## Fix instructions from the arbiter",
+            "",
+            instructions,
+            "",
+            "## Rules",
+            "",
+            "- Use the edit tool to make the requested fixes directly.",
+            "- Only modify files in your assigned list unless the arbiter specifically",
+            "  instructed otherwise.",
+            "- When you have completed all fixes, stop.",
+        ].join("\n");
+        if (verbose) {
+            verbose(`[${tag}] Recall prompt: ${prompt.length.toLocaleString()} chars`);
+        }
+        const sessionId = await this.createSession(`Hem: ${tag}`);
+        if (verbose) {
+            verbose(`[${tag}] Session ${sessionId}`);
+        }
+        try {
+            await this.provider.prompt(sessionId, prompt, { agent: "hem-xref" });
+            if (verbose) {
+                verbose(`[${tag}] Recall completed`);
+            }
+        }
+        finally {
+            // Always kill the recall session
+            await this.killSession(sessionId, tag, verbose);
+        }
+    }
+    /**
+     * Builds the single-agent cross-reference prompt (original behavior).
+     */
+    static buildPrompt(params) {
+        const { projectName, destinationPath, allDocFiles } = params;
+        const parts = [];
+        parts.push(`Read all generated documentation files for **${projectName}** and add`, `inter-document links to improve navigation between related pages.`, "", `**Edit files directly using the edit tool.** Do NOT return Markdown content`, `in your response text. When done making changes, stop.`, "");
+        parts.push("## Destination directory", "", `All documentation files are in: \`${destinationPath}\``, "");
+        parts.push("## Documentation files", "");
+        for (const file of allDocFiles) {
+            parts.push(`- \`${destinationPath}/${file}\``);
+        }
+        parts.push("");
+        parts.push("## Your tasks", "", "Read ALL the documentation files listed above, then:", "", "1. **Add \"Related Documentation\" sections**: At the bottom of each page, add", "   or update a \"## Related Documentation\" section with links to related pages.", "   Use descriptive link text and brief descriptions.", "", "2. **Add inline cross-references**: Within the body text, add links to other", "   documentation pages where concepts are mentioned. For example, if a feature", "   page mentions the authentication system, link to the auth documentation.", "", "3. **TSG bidirectional linking**: Ensure documentation pages link to relevant", "   TSG pages and vice versa.", "", "4. **Use relative paths**: All links must use relative paths between files", "   (e.g., `../auth/overview.md` from a TSG page).", "", "5. **Don't add redundant links**: Only add links that provide genuine", "   navigational value. Don't link every mention of every concept.", "");
+        parts.push("## When you are done", "", "After making changes using the edit tool, simply stop.", "Do NOT return a JSON manifest or any other structured output.", "The pipeline will scan the destination directory to discover the final file set.");
+        return parts.join("\n");
+    }
+    /**
+     * Builds the prompt for a parallel cross-ref worker.
+     *
+     * Each worker gets:
+     *   - A scoped identity (e.g. "xref-worker-1 of 3")
+     *   - Its assigned file subset
+     *   - The full file list for cross-reference awareness
+     *   - Instructions for using the broadcast tool
+     *   - Scoped task list (only edit YOUR files)
+     */
+    static buildWorkerPrompt(params) {
+        const { projectName, destinationPath, assignedFiles, allDocFiles, workerLabel, totalWorkers, } = params;
+        const parts = [];
+        // ── Role section ──────────────────────────────────────────────────
+        parts.push(`Worker **${workerLabel}**: read the assigned documentation files for`, `**${projectName}** and add inter-document cross-reference links to improve`, `navigation.`, "", `There are ${totalWorkers} workers running in parallel; each owns a distinct`, `set of files. Coordinate with the arbiter via the broadcast tool.`, "", `**Edit files directly using the edit tool.** Full write access is available`, `— use it. Do NOT delegate file edits to the arbiter or anyone else. Do NOT`, `return Markdown content in your response text. Make changes with the edit`, `tool, then stop when done.`, "", `**IMPORTANT: This session will be terminated when finished.** Complete all`, `edits first, then stop.`, "");
+        // ── Destination directory ─────────────────────────────────────────
+        parts.push("## Destination directory", "", `All documentation files are in: \`${destinationPath}\``, "");
+        // ── Assigned files ────────────────────────────────────────────────
+        parts.push("## Your assigned files", "", "The assigned files for cross-reference linking are:", "");
+        for (const file of assignedFiles) {
+            parts.push(`- \`${destinationPath}/${file}\``);
+        }
+        parts.push("");
+        // ── All files (for cross-reference awareness) ─────────────────────
+        if (allDocFiles.length > assignedFiles.length) {
+            parts.push("## All documentation files (for reference)", "", "Other workers are handling these files. You may read them for context", "but do NOT edit files outside your assigned list.", "");
+            const otherFiles = allDocFiles.filter((f) => !assignedFiles.includes(f));
+            for (const file of otherFiles) {
+                parts.push(`- \`${destinationPath}/${file}\``);
+            }
+            parts.push("");
+        }
+        // ── Tasks (scoped) ────────────────────────────────────────────────
+        parts.push("## Your tasks", "", "Read ALL of your assigned documentation files, then:", "", "1. **Add \"Related Documentation\" sections**: At the bottom of each of YOUR", "   assigned files, add or update a \"## Related Documentation\" section with", "   links to related pages. Use descriptive link text and brief descriptions.", "", "2. **Add inline cross-references**: Within the body text of YOUR files, add", "   links to other documentation pages where concepts are mentioned.", "", "3. **TSG bidirectional linking**: Ensure YOUR documentation pages link to", "   relevant TSG pages and vice versa (only edit YOUR files).", "", "4. **Use relative paths**: All links must use relative paths between files", "   (e.g., `../auth/overview.md` from a TSG page).", "", "5. **Don't add redundant links**: Only add links that provide genuine", "   navigational value. Don't link every mention of every concept.", "", "6. **Cross-worker link consistency**: If you spot a link consistency issue", "   involving another worker's files (e.g., you added a link to a file", "   owned by another worker but the reciprocal link is missing), broadcast", "   a SUGGESTION so the arbiter can coordinate.", "");
+        // ── Coordination section ──────────────────────────────────────────
+        parts.push("## Coordination with the arbiter", "", "You can communicate using the **broadcast** tool. Your broadcasts go", "**ONLY to the arbiter** — other workers will NOT see your messages.", "The arbiter coordinates all cross-worker communication.", "", "### When to broadcast", "", "Broadcast whenever you add a link that could affect cross-worker consistency:", "", '- **Links added**:', '  `broadcast({ message: "LINK-ADDED: auth/overview.md → api/endpoints.md (added reference to API endpoints)" })`', "", '- **Suggestions for cross-worker link issues** (the arbiter will act on these):', '  `broadcast({ message: "SUGGESTION: auth/overview.md links to api/endpoints.md but api/endpoints.md does not link back" })`', "", '- **Acknowledgements** (only when you actually took action on a DECISION):', '  `broadcast({ message: "ACK: Added reciprocal link in auth/overview.md → api/endpoints.md" })`', "", "### When you receive messages", "", "Messages appear as user messages prefixed with the sender's label.", "You will only receive messages from **the arbiter** (DECISION messages).", "Decision types you may receive:", "", "- **ADD-LINK**: `DECISION: @your-label ADD-LINK <file> → <target-file>` —", "  add a reciprocal cross-reference link. After adding, broadcast an ACK.", "", "- **UPDATE-LINK**: `DECISION: @your-label UPDATE-LINK <file>` —", "  update a cross-reference link. After updating, broadcast an ACK.", "", "- **Free-form**: `DECISION: @your-label <instructions>` —", "  execute the instructions directly. After executing, broadcast an ACK.", "", "You **MUST** execute each DECISION yourself. Use the edit tool for all", "link additions and updates. The arbiter decides how to resolve", "cross-worker link consistency issues.", "", "### Rules", "", "- Only edit files in YOUR assigned list. For cross-worker link issues,", "  broadcast a SUGGESTION and let the arbiter decide.", "- Do NOT ACK messages you cannot act on. Only ACK when you actually", "  edited files or updated links.", "- Do NOT broadcast progress updates, questions, or file contents.", "- Keep messages short and actionable.", "- You MUST use the edit tool to make all file changes yourself.", "  Do NOT ask the arbiter to edit files for you.", "");
+        // ── When done ──────────────────────────────────────────────────────
+        parts.push("## When you are done", "", "After making ALL changes (including any changes requested by the arbiter),", "stop. The pipeline will scan the destination directory to discover the", "final file set.", "", "- Make sure all edits are complete before stopping.", "- **Your session will be terminated when you finish.**");
+        return parts.join("\n");
+    }
+}
+// ── File Assignment ─────────────────────────────────────────────────────
+/**
+ * Assigns documentation files to cross-ref workers using round-robin distribution.
+ *
+ * Files are sorted alphabetically first so that files in the same
+ * directory tend to land on adjacent workers, preserving some locality.
+ * Then they are dealt out in order: file 0 → worker 1, file 1 → worker 2,
+ * …, wrapping around. This guarantees perfectly balanced workloads (±1 file).
+ *
+ * @param files      - Relative file paths (e.g. "auth/overview.md").
+ * @param maxWorkers - Maximum number of workers to create.
+ * @returns An array of worker assignments, each with a label and file list.
+ */
+export function assignXrefFilesToWorkers(files, maxWorkers) {
+    if (files.length === 0)
+        return [];
+    const numWorkers = Math.min(maxWorkers, files.length);
+    if (numWorkers <= 1) {
+        return [{ label: "xref-worker-1", files: [...files] }];
+    }
+    const sorted = [...files].sort();
+    const workers = [];
+    for (let i = 0; i < numWorkers; i++) {
+        workers.push({ label: `xref-worker-${i + 1}`, files: [] });
+    }
+    for (let i = 0; i < sorted.length; i++) {
+        workers[i % numWorkers].files.push(sorted[i]);
+    }
+    return workers;
+}

package/dist/agents/crossref-arbiter-agent.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Arbiter agent for Hem's parallel cross-reference pass.
+ *
+ * The cross-ref arbiter is a lightweight coordinator that runs alongside N
+ * parallel cross-ref workers.  It receives all broadcast messages, evaluates
+ * SUGGESTION messages, and issues DECISION directives telling specific
+ * workers what to do for link consistency.  It does NOT edit files itself.
+ *
+ * Lifecycle (two-phase, driven by CrossRefAgent.runParallel):
+ *   1. `run()`    — creates the session, sends the initial prompt via
+ *                    promptAsync (fire-and-forget).  Returns { sessionId }.
+ *   2. `wrapUp()` — called after all workers complete.  Sends a final
+ *                    prompt so the arbiter can issue any remaining
+ *                    DECISION messages.  Non-fatal on failure.
+ */
+import type { Provider } from "../providers/types.js";
+import { BaseAgent } from "./base-agent.js";
+import type { WorkerAssignment } from "./organization-agent.js";
+/** Parameters for the cross-ref arbiter prompt. */
+export interface CrossRefArbiterPromptParams {
+    /** Project name. */
+    projectName: string;
+    /** Absolute path to the destination directory. */
+    destinationPath: string;
+    /** ALL documentation files (for full awareness). */
+    allDocFiles: string[];
+    /** Worker assignments mapping each worker label to its owned files. */
+    workerAssignments: WorkerAssignment[];
+}
+/**
+ * A coordinator agent that monitors cross-ref worker broadcasts and issues
+ * DECISION directives to resolve cross-worker link consistency issues.
+ *
+ * Does NOT edit files — directs workers to make all changes.
+ */
+export declare class CrossRefArbiterAgent extends BaseAgent {
+    constructor(provider: Provider);
+    /**
+     * Create the arbiter session and send the initial prompt.
+     *
+     * The initial prompt is sent via `promptAsync` (fire-and-forget) because
+     * the arbiter sits idle until it receives broadcasts from workers.
+     *
+     * @returns The session ID so the caller can register it in the SSE
+     *          relay map and later call `wrapUp()`.
+     * @throws {AuthExpiredError} If session creation or the initial prompt
+     *         fails due to authentication expiry.
+     */
+    run(params: CrossRefArbiterPromptParams, verbose?: (msg: string) => void): Promise<{
+        sessionId: string;
+    }>;
+    /**
+     * Send the wrap-up prompt after all workers have completed.
+     *
+     * Asks the arbiter to issue any remaining DECISION messages and then
+     * output its final `{ "status": "complete" }` response.
+     *
+     * This is intentionally **non-fatal** — if the arbiter fails, workers
+     * have already made their edits and the pipeline can continue.
+     */
+    wrapUp(sessionId: string, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Builds the cross-ref arbiter prompt.
+     *
+     * The arbiter is a lightweight coordinator that:
+     *   - Receives all broadcasts from cross-ref workers
+     *   - Evaluates SUGGESTION messages and issues DECISION directives
+     *   - Directs specific workers to add/update reciprocal links
+     *   - Does NOT edit files directly
+     */
+    static buildPrompt(params: CrossRefArbiterPromptParams): string;
+}