@pruddiman/hem 0.0.1-beta-5671db0

package/dist/agents/index-agent.js

@@ -0,0 +1,360 @@
+/**
+ * LLM-assisted index page generation agent for Hem.
+ *
+ * Post-processing agent that runs AFTER the architecture agent.
+ * Uses an OpenCode session to generate a rich `index.md` with a
+ * narrative introduction, project overview, and reading guide.
+ *
+ * The agent writes `index.md` with a `<!-- TOC -->` placeholder
+ * that the pipeline replaces with the procedurally generated
+ * table of contents link list.
+ *
+ * Architecture:
+ *   - Reuses the `hem-arch` agent permissions (no new agent entry).
+ *   - The pipeline reads back `index.md`, replaces the placeholder,
+ *     then writes the final version.
+ *   - Falls back to procedural TOC if the agent fails.
+ */
+import pLimit from "p-limit";
+import { extractJSON } from "../helpers/parsing.js";
+import { BaseAgent } from "./base-agent.js";
+import { computeMaxConcurrency } from "../resources.js";
+import { AuthExpiredError } from "../auth.js";
+// ── Types ───────────────────────────────────────────────────────────────
+/** Character-count threshold above which the index agent chunks its input. */
+export const INDEX_CHUNK_THRESHOLD = 80_000;
+// ── Agent ───────────────────────────────────────────────────────────────
+/**
+ * An agent that uses an LLM to generate a rich index page (`index.md`)
+ * for a project's documentation.
+ *
+ * Writes `index.md` with a `<!-- TOC -->` placeholder that the pipeline
+ * replaces with the procedural table of contents link list.
+ */
+export class IndexAgent extends BaseAgent {
+    constructor(provider) {
+        super(provider);
+    }
+    /**
+     * Run the index page generation pipeline.
+     *
+     * @param params  - All inputs needed for the index prompt.
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    async run(params, verbose) {
+        const tag = "index-agent";
+        // 1. Build the full prompt to measure size
+        const fullPrompt = IndexAgent.buildPrompt(params);
+        if (verbose) {
+            verbose(`[${tag}] Full prompt: ${fullPrompt.length.toLocaleString()} chars`);
+        }
+        // 2. If the prompt fits in a single context window, use the simple path
+        if (fullPrompt.length <= INDEX_CHUNK_THRESHOLD) {
+            const sessionId = await this.createSession("Hem: index overview");
+            if (verbose) {
+                verbose(`[${tag}] Session created: ${sessionId}`);
+            }
+            await this.provider.prompt(sessionId, fullPrompt, { agent: "hem-index" });
+            if (verbose) {
+                verbose(`[${tag}] Agent completed`);
+            }
+            return;
+        }
+        // 3. Chunked path — split inputs across multiple sessions
+        const chunks = IndexAgent.chunkInputs(params);
+        if (verbose) {
+            verbose(`[${tag}] Chunking: ${chunks.length} chunks for ${params.allFindings.length} findings + ${params.allGroupSummaries.length} groups`);
+        }
+        // Run chunk sessions in parallel (bounded by resource concurrency)
+        const concurrency = computeMaxConcurrency();
+        const limit = pLimit(concurrency);
+        const settled = await Promise.allSettled(chunks.map((chunk, i) => limit(async () => {
+            const chunkPrompt = IndexAgent.buildChunkPrompt(params, chunk.findings, chunk.summaries, i + 1, chunks.length);
+            if (verbose) {
+                verbose(`[${tag}] Chunk ${i + 1}/${chunks.length}: ${chunkPrompt.length.toLocaleString()} chars`);
+            }
+            const sessionId = await this.createSession(`Hem: index chunk ${i + 1}/${chunks.length}`);
+            if (verbose) {
+                verbose(`[${tag}] Chunk session created: ${sessionId}`);
+            }
+            const responseText = await this.provider.prompt(sessionId, chunkPrompt, { agent: "hem-index" }) ?? "";
+            try {
+                const jsonStr = extractJSON(responseText);
+                const parsed = JSON.parse(jsonStr);
+                return {
+                    narrative: parsed.narrative ?? "",
+                    keyConcepts: Array.isArray(parsed.keyConcepts) ? parsed.keyConcepts : [],
+                    readingGuideEntries: Array.isArray(parsed.readingGuideEntries) ? parsed.readingGuideEntries : [],
+                };
+            }
+            catch {
+                if (verbose) {
+                    verbose(`[${tag}] Chunk ${i + 1} response was not valid JSON, using fallback`);
+                }
+                return {
+                    narrative: responseText.slice(0, 500),
+                    keyConcepts: [],
+                    readingGuideEntries: [],
+                };
+            }
+        })));
+        // Collect results; use empty fallback for failed chunks so synthesis still runs.
+        // Re-throw AuthExpiredError immediately.
+        const chunkSummaries = [];
+        for (let i = 0; i < settled.length; i++) {
+            const result = settled[i];
+            if (result.status === "fulfilled") {
+                chunkSummaries.push(result.value);
+            }
+            else {
+                if (result.reason instanceof AuthExpiredError) {
+                    throw result.reason;
+                }
+                if (verbose) {
+                    const msg = result.reason instanceof Error ? result.reason.message : String(result.reason);
+                    verbose(`[${tag}] chunk ${i + 1}/${chunks.length} failed: ${msg}`);
+                }
+                chunkSummaries.push({ narrative: "", keyConcepts: [], readingGuideEntries: [] });
+            }
+        }
+        // 4. Synthesis session — combine chunk summaries into the final index.md
+        const synthesisPrompt = IndexAgent.buildSynthesisPrompt(params, chunkSummaries);
+        if (verbose) {
+            verbose(`[${tag}] Synthesis prompt: ${synthesisPrompt.length.toLocaleString()} chars`);
+        }
+        const synthesisSessionId = await this.createSession("Hem: index synthesis");
+        if (verbose) {
+            verbose(`[${tag}] Synthesis session created: ${synthesisSessionId}`);
+        }
+        await this.provider.prompt(synthesisSessionId, synthesisPrompt, { agent: "hem-index" });
+        if (verbose) {
+            verbose(`[${tag}] Agent completed (chunked: ${chunks.length} chunks + synthesis)`);
+        }
+    }
+    // ── Static helpers (pure functions, easy to unit test) ───────────────
+    /**
+     * Builds the index page prompt from exploration findings, group
+     * summaries, and the list of generated documentation files.
+     */
+    static buildPrompt(params) {
+        const { projectName, destinationPath, allFindings, allGroupSummaries, allDocFiles, } = params;
+        const parts = [];
+        // 1. System-level instructions
+        parts.push(`Generate a rich, narrative \`index.md\` that serves as the landing page`, `for the project's documentation. It should orient readers with a project`, `description, explain what the documentation covers, and provide a reading`, `guide.`, "", `**Write files directly using the edit tool.** Do NOT return Markdown content`, `in your response text. Instead, use the edit tool to create \`index.md\``, `in the destination directory. When you are done, stop.`, "");
+        // 2. Where to write
+        parts.push("## Destination", "", `Write the index page to: \`${destinationPath}/index.md\``, "");
+        // 3. TOC placeholder instruction
+        parts.push("## Table of contents placeholder", "", `The \`index.md\` MUST include the exact placeholder \`<!-- TOC -->\` on its`, `own line. The pipeline will replace this placeholder with an auto-generated,`, `navigable table of contents linking to every documentation page. Do NOT`, `generate your own links to individual doc pages — the placeholder handles that.`, "", "Example:", "", "```markdown", `# ${projectName} Documentation`, "", "Brief project description...", "", "## Reading guide", "", "How to navigate this documentation...", "", "<!-- TOC -->", "```", "");
+        // 4. Content guidelines
+        parts.push("## What to include", "", `1. **Project title as H1**: \`# ${projectName} Documentation\``, "", `2. **Project description**: 1-3 paragraphs explaining what ${projectName} is,`, `   what problem it solves, and who its audience is. Derive this from the`, `   exploration findings and generated documentation.`, "", `3. **Key concepts / terminology**: If the project uses domain-specific terms,`, `   briefly define the most important ones.`, "", `4. **Reading guide**: Help readers navigate the documentation. For example:`, `   - "New to the project? Start with [Architecture Overview](./architecture.md)."`, `   - Group documentation into logical themes and explain what each covers.`, "", `5. **The \`<!-- TOC -->\` placeholder**: Place this where you want the`, `   auto-generated table of contents to appear. Typically after your narrative`, `   content and before any closing remarks.`, "");
+        // 5. Quality standards
+        parts.push("## Quality standards", "", `- **Google Markdown style guide**: ATX headings, single H1, informative links.`, `- **No verbatim source code**: This is a documentation index, not a code reference.`, `- **Concise but informative**: Aim for a landing page that can be read in under 2 minutes.`, `- **Link to architecture.md**: If it exists, reference it in your reading guide.`, "");
+        // 6. Generated doc files for context
+        if (allDocFiles.length > 0) {
+            parts.push("## Generated documentation files", "");
+            parts.push("These documentation files have already been generated. Read them using tools", "to understand what the project is about and what content exists. Use this to", "write an informed project description and reading guide.", "");
+            for (const docFile of allDocFiles) {
+                parts.push(`- \`${destinationPath}/${docFile}\``);
+            }
+            parts.push("");
+        }
+        // 7. Exploration findings
+        parts.push("## Exploration findings", "");
+        if (allFindings.length > 0) {
+            parts.push("The exploration phase discovered these findings across all file groups.", "Use them to understand what the project does:", "");
+            for (const findings of allFindings) {
+                parts.push(`### Group: ${findings.groupId}`);
+                parts.push("");
+                parts.push(findings.text);
+                parts.push("");
+            }
+        }
+        else {
+            parts.push("No exploration findings available. Use tools to read the generated", "documentation files for context.", "");
+        }
+        // 8. File groups
+        parts.push("## File groups in this project", "");
+        if (allGroupSummaries.length > 0) {
+            for (const group of allGroupSummaries) {
+                parts.push(`- **${group.label}** (${group.id})`);
+            }
+        }
+        else {
+            parts.push("No file groups defined.");
+        }
+        parts.push("");
+        // 9. How to work
+        parts.push("## How to work", "");
+        parts.push(`1. **Read generated docs**: Use tools to read the generated documentation files`, `   to understand what the project is about.`, `2. **Read architecture.md**: If it exists, read it for the system overview.`, `3. **Write index.md**: Use the edit tool to write the index page.`, `4. **Include the TOC placeholder**: Remember to include \`<!-- TOC -->\` exactly once.`, "");
+        // 10. Done
+        parts.push("## When you are done", "");
+        parts.push(`After writing \`index.md\` using the edit tool, simply stop.`, `Do NOT return a JSON manifest or any other structured output.`, `The pipeline will read back \`index.md\` and replace the \`<!-- TOC -->\``, `placeholder with the auto-generated table of contents.`);
+        return parts.join("\n");
+    }
+    /**
+     * Splits exploration findings and group summaries into chunks that
+     * each produce a prompt under {@link INDEX_CHUNK_THRESHOLD} characters.
+     *
+     * The doc file list is NOT chunked — it is always included in the
+     * synthesis prompt (it is just a list of paths and stays small).
+     */
+    static chunkInputs(params) {
+        const { allFindings, allGroupSummaries } = params;
+        // Estimate the character cost of each finding and summary
+        const findingSizes = allFindings.map((f) => JSON.stringify(f).length);
+        const summarySizes = allGroupSummaries.map((s) => JSON.stringify(s).length);
+        const totalVariableSize = findingSizes.reduce((a, b) => a + b, 0) +
+            summarySizes.reduce((a, b) => a + b, 0);
+        // Base prompt overhead (system instructions, destination, TOC, etc.)
+        const baseOverhead = 3_000;
+        const budgetPerChunk = INDEX_CHUNK_THRESHOLD - baseOverhead;
+        // Calculate how many chunks we need
+        const numChunks = Math.max(1, Math.ceil(totalVariableSize / budgetPerChunk));
+        // Build a paired list sorted by size descending for balanced distribution
+        const items = [
+            ...findingSizes.map((size, index) => ({
+                type: "finding",
+                index,
+                size,
+            })),
+            ...summarySizes.map((size, index) => ({
+                type: "summary",
+                index,
+                size,
+            })),
+        ];
+        items.sort((a, b) => b.size - a.size);
+        // Greedy bin-packing: assign each item to the lightest chunk
+        const chunkBins = Array.from({ length: numChunks }, () => ({
+            findings: [],
+            summaries: [],
+            size: 0,
+        }));
+        for (const item of items) {
+            // Find the chunk with the smallest current size
+            let minIdx = 0;
+            for (let j = 1; j < chunkBins.length; j++) {
+                if (chunkBins[j].size < chunkBins[minIdx].size) {
+                    minIdx = j;
+                }
+            }
+            const target = chunkBins[minIdx];
+            if (item.type === "finding") {
+                target.findings.push(allFindings[item.index]);
+            }
+            else {
+                target.summaries.push(allGroupSummaries[item.index]);
+            }
+            target.size += item.size;
+        }
+        // Filter out empty chunks (can happen if numChunks > items.length)
+        return chunkBins
+            .filter((c) => c.findings.length > 0 || c.summaries.length > 0)
+            .map(({ findings, summaries }) => ({ findings, summaries }));
+    }
+    /**
+     * Builds a prompt for a single chunk session.
+     *
+     * The chunk agent reads a subset of findings and group summaries and
+     * returns a JSON summary — it does NOT write `index.md`.
+     */
+    static buildChunkPrompt(params, chunkFindings, chunkSummaries, chunkIndex, totalChunks) {
+        const { projectName, destinationPath, allDocFiles } = params;
+        const parts = [];
+        parts.push(`Process chunk ${chunkIndex} of ${totalChunks} for the project **${projectName}**.`, `Analyze the exploration findings and file group summaries below, then return`, `a JSON summary.`, "", `**Do NOT write any files.** Do NOT use the edit tool. Return ONLY a JSON object`, `in your response.`, "");
+        // Context: doc files exist (for awareness, not for reading)
+        if (allDocFiles.length > 0) {
+            parts.push("## Documentation files (for context)", "");
+            parts.push(`These ${allDocFiles.length} documentation files have been generated.`, `You do not need to read them — just be aware they exist:`, "");
+            // Only list first 20 to keep the chunk prompt lean
+            const listed = allDocFiles.slice(0, 20);
+            for (const f of listed) {
+                parts.push(`- \`${destinationPath}/${f}\``);
+            }
+            if (allDocFiles.length > 20) {
+                parts.push(`- ... and ${allDocFiles.length - 20} more files`);
+            }
+            parts.push("");
+        }
+        // Findings for this chunk
+        parts.push("## Exploration findings (this chunk)", "");
+        if (chunkFindings.length > 0) {
+            for (const findings of chunkFindings) {
+                parts.push(`### Group: ${findings.groupId}`);
+                parts.push("");
+                parts.push(findings.text);
+                parts.push("");
+            }
+        }
+        else {
+            parts.push("No exploration findings in this chunk.", "");
+        }
+        // Group summaries for this chunk
+        parts.push("## File groups (this chunk)", "");
+        if (chunkSummaries.length > 0) {
+            for (const group of chunkSummaries) {
+                parts.push(`- **${group.label}** (${group.id})`);
+            }
+        }
+        else {
+            parts.push("No file groups in this chunk.");
+        }
+        parts.push("");
+        // Response format
+        parts.push("## Response format", "", "Return a JSON object with this structure:", "", "```json", "{", '  "narrative": "1-2 paragraphs describing what this chunk of the project does",', '  "keyConcepts": ["concept1", "concept2"],', '  "readingGuideEntries": ["Start with X to understand Y", "See Z for details on W"]', "}", "```", "", "Focus on extracting the most important themes and concepts from the", "findings and groups assigned to this chunk.");
+        return parts.join("\n");
+    }
+    /**
+     * Builds the synthesis prompt that combines chunk summaries into the
+     * final `index.md`. This prompt instructs the agent to write the file.
+     */
+    static buildSynthesisPrompt(params, chunkSummaries) {
+        const { projectName, destinationPath, allDocFiles } = params;
+        const parts = [];
+        // 1. System instructions (same as original buildPrompt)
+        parts.push(`Generate a rich, narrative \`index.md\` that serves as the landing page`, `for the project's documentation. It should orient readers with a project`, `description, explain what the documentation covers, and provide a reading`, `guide.`, "", `**Write files directly using the edit tool.** Do NOT return Markdown content`, `in your response text. Instead, use the edit tool to create \`index.md\``, `in the destination directory. When you are done, stop.`, "");
+        // 2. Where to write
+        parts.push("## Destination", "", `Write the index page to: \`${destinationPath}/index.md\``, "");
+        // 3. TOC placeholder (same as original)
+        parts.push("## Table of contents placeholder", "", `The \`index.md\` MUST include the exact placeholder \`<!-- TOC -->\` on its`, `own line. The pipeline will replace this placeholder with an auto-generated,`, `navigable table of contents linking to every documentation page. Do NOT`, `generate your own links to individual doc pages — the placeholder handles that.`, "", "Example:", "", "```markdown", `# ${projectName} Documentation`, "", "Brief project description...", "", "## Reading guide", "", "How to navigate this documentation...", "", "<!-- TOC -->", "```", "");
+        // 4. Content guidelines (same as original)
+        parts.push("## What to include", "", `1. **Project title as H1**: \`# ${projectName} Documentation\``, "", `2. **Project description**: 1-3 paragraphs explaining what ${projectName} is,`, `   what problem it solves, and who its audience is. Synthesize from the`, `   chunk summaries below.`, "", `3. **Key concepts / terminology**: Combine the key concepts from all chunks.`, "", `4. **Reading guide**: Combine the reading guide entries from all chunks into`, `   a coherent navigation guide.`, "", `5. **The \`<!-- TOC -->\` placeholder**: Place this where you want the`, `   auto-generated table of contents to appear.`, "");
+        // 5. Quality standards (same as original)
+        parts.push("## Quality standards", "", `- **Google Markdown style guide**: ATX headings, single H1, informative links.`, `- **No verbatim source code**: This is a documentation index, not a code reference.`, `- **Concise but informative**: Aim for a landing page that can be read in under 2 minutes.`, `- **Link to architecture.md**: If it exists, reference it in your reading guide.`, "");
+        // 6. Chunk summaries (the main input for synthesis)
+        parts.push("## Analysis summaries from exploration", "");
+        parts.push(`The project was analyzed in ${chunkSummaries.length} chunks. Here are the`, `summaries from each chunk. Synthesize these into a coherent project description`, `and reading guide:`, "");
+        for (let i = 0; i < chunkSummaries.length; i++) {
+            const cs = chunkSummaries[i];
+            parts.push(`### Chunk ${i + 1}`, "");
+            parts.push(`**Narrative**: ${cs.narrative}`, "");
+            if (cs.keyConcepts.length > 0) {
+                parts.push(`**Key concepts**: ${cs.keyConcepts.join(", ")}`, "");
+            }
+            if (cs.readingGuideEntries.length > 0) {
+                parts.push("**Reading guide entries**:");
+                for (const entry of cs.readingGuideEntries) {
+                    parts.push(`- ${entry}`);
+                }
+                parts.push("");
+            }
+        }
+        // 7. Generated doc files (full list for context)
+        if (allDocFiles.length > 0) {
+            parts.push("## Generated documentation files", "");
+            parts.push("These documentation files have been generated. You may read them using", "tools for additional context:", "");
+            for (const docFile of allDocFiles) {
+                parts.push(`- \`${destinationPath}/${docFile}\``);
+            }
+            parts.push("");
+        }
+        // 8. How to work
+        parts.push("## How to work", "");
+        parts.push(`1. **Review the chunk summaries above**: They contain the synthesized analysis.`, `2. **Optionally read generated docs**: For additional context.`, `3. **Write index.md**: Use the edit tool to write the index page.`, `4. **Include the TOC placeholder**: Remember to include \`<!-- TOC -->\` exactly once.`, "");
+        // 9. Done
+        parts.push("## When you are done", "");
+        parts.push(`After writing \`index.md\` using the edit tool, simply stop.`, `Do NOT return a JSON manifest or any other structured output.`, `The pipeline will read back \`index.md\` and replace the \`<!-- TOC -->\``, `placeholder with the auto-generated table of contents.`);
+        return parts.join("\n");
+    }
+}

package/dist/agents/organization-agent.d.ts

@@ -0,0 +1,144 @@
+/**
+ * LLM-assisted organization agent for Hem.
+ *
+ * Post-processing agent that runs AFTER all doc agents complete.
+ * Reviews all written documentation files, restructures/renames/deduplicates
+ * for consistency.
+ *
+ * Architecture (v3 — parallel workers with broadcast):
+ *   - Absorbs the old DeduplicationAgent's responsibility.
+ *   - 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 type { Provider } from "../providers/types.js";
+import { BaseAgent } from "./base-agent.js";
+/** File count threshold: use parallel workers above this, single agent below. */
+export declare const PARALLEL_THRESHOLD = 8;
+/**
+ * Hard ceiling on parallel org workers.  The actual worker count is
+ * `min(MAX_WORKERS, computeOrgWorkers(fileCount), computeMaxConcurrency())`.
+ * The arbiter is excluded from this cap (it is lightweight).
+ */
+export declare const MAX_WORKERS = 7;
+/**
+ * MCP tool name as it appears in SSE events.
+ * Format: "{mcp-server-name}_{tool-name}"
+ */
+export declare const BROADCAST_TOOL_NAME = "hem-broadcast_broadcast";
+/** Parameters for the single-agent organization prompt. */
+export interface OrgPromptParams {
+    /** Project name. */
+    projectName: string;
+    /** Absolute path to the destination directory. */
+    destinationPath: string;
+    /** Relative paths of all generated documentation files. */
+    allDocFiles: string[];
+}
+/** Parameters for a parallel org worker prompt. */
+export interface OrgWorkerPromptParams {
+    /** Project name. */
+    projectName: string;
+    /** Absolute path to the destination directory. */
+    destinationPath: string;
+    /** Files assigned to THIS worker (relative paths). */
+    assignedFiles: string[];
+    /** ALL documentation files across all workers (for cross-reference awareness). */
+    allDocFiles: string[];
+    /** Label for this worker, e.g. "org-worker-1". */
+    workerLabel: string;
+    /** Total number of parallel workers. */
+    totalWorkers: number;
+}
+/** A single worker assignment: label → file list. */
+export interface WorkerAssignment {
+    label: string;
+    files: string[];
+}
+/**
+ * An agent that reviews all generated documentation and restructures
+ * for consistency — deduplicating, renaming, and reorganizing files.
+ *
+ * Writes/edits files directly via the edit tool. The pipeline discovers
+ * the final file set by scanning disk afterward.
+ */
+export declare class OrganizationAgent extends BaseAgent {
+    constructor(provider: Provider);
+    /**
+     * Run the organization pass over all generated documentation.
+     * Automatically selects single-agent or parallel mode based on file count.
+     *
+     * @param params  - Organization parameters including file paths.
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    run(params: OrgPromptParams, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Single-agent organization pass (original behavior).
+     * Used when file count is ≤ PARALLEL_THRESHOLD.
+     */
+    runSingle(params: OrgPromptParams, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Parallel organization 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.
+     */
+    runParallel(params: OrgPromptParams, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Kill a session: abort any running work, then delete the session.
+     * Best-effort — failures are logged but not thrown.
+     */
+    private killSession;
+    /**
+     * Spawn a recalled worker session to apply specific fixes.
+     *
+     * Called when the arbiter broadcasts `RECALL: @org-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.
+     */
+    private runRecalledWorker;
+    /**
+     * Builds the single-agent organization prompt (original behavior).
+     */
+    static buildPrompt(params: OrgPromptParams): string;
+    /**
+     * Builds the prompt for a parallel org worker.
+     *
+     * Each worker gets:
+     *   - A scoped identity (e.g. "org-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: OrgWorkerPromptParams): string;
+}
+/**
+ * Assigns documentation files to 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 declare function assignFilesToWorkers(files: string[], maxWorkers: number): WorkerAssignment[];