@pruddiman/hem 0.0.1-beta-5671db0

package/dist/agents/grouping-agent.js

@@ -0,0 +1,557 @@
+/**
+ * LLM-assisted file grouping agent for Hem.
+ *
+ * Uses an OpenCode session to analyze source files and produce semantically
+ * meaningful documentation groups. Falls back gracefully — returns `null`
+ * on any failure so the caller can use heuristic grouping instead.
+ *
+ * The agent:
+ *   1. Reads file contents and extracts import dependencies (programmatic).
+ *   2. Builds a structured prompt with file summaries + dependency graph.
+ *   3. Sends the prompt to an OpenCode session.
+ *   4. Parses the strongly-typed JSON response.
+ *   5. Maps results to `FileGroup[]` with hallucination guards.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { extractJSON } from "../helpers/parsing.js";
+import { commonDirectory } from "../grouping.js";
+import { toKebabCase } from "../helpers/strings.js";
+import { AuthExpiredError } from "../auth.js";
+import { BaseAgent } from "./base-agent.js";
+import pLimit from "p-limit";
+import { computeMaxConcurrency } from "../resources.js";
+/** File name for the on-disk grouping result cache. */
+export const GROUPING_CACHE_FILE = "grouping-cache.json";
+/**
+ * File count threshold: when there are more files than this, use chunked
+ * grouping (split into batches → parallel LLM sessions → merge results).
+ * Below this threshold, the original single-prompt approach is used.
+ */
+export const GROUPING_CHUNK_THRESHOLD = 200;
+/**
+ * Target number of files per batch when chunking. Batches are sized to
+ * stay well within LLM context limits (~100 files × 40 lines each ≈ 4000
+ * lines of context, comfortably under typical 128K-200K token windows).
+ */
+export const FILES_PER_CHUNK = 100;
+// ── Agent ───────────────────────────────────────────────────────────────
+/**
+ * An agent that uses an LLM to group source files into cohesive
+ * documentation topics.
+ */
+export class GroupingAgent extends BaseAgent {
+    projectName;
+    constructor(provider, projectName) {
+        super(provider);
+        this.projectName = projectName;
+    }
+    /**
+     * Run the full grouping pipeline: read → analyze → prompt → parse → map.
+     *
+     * @param files    - Discovered source files to group.
+     * @param verbose  - Optional logging callback (writes to stderr).
+     * @param cacheDir - Optional directory for the grouping result cache
+     *                   (typically the `.hem` directory in the project root).
+     *                   When provided, a cache hit skips the LLM call entirely.
+     * @returns `FileGroup[]` on success, `null` on any failure.
+     */
+    async run(files, verbose, cacheDir) {
+        try {
+            // ── Cache check (fast path) ────────────────────────────────────
+            const filesHash = GroupingAgent.computeFilesHash(files);
+            if (cacheDir) {
+                const cached = await GroupingAgent.loadGroupingCache(cacheDir, filesHash);
+                if (cached) {
+                    if (verbose) {
+                        verbose(`[grouping-agent] Cache hit (${filesHash.slice(0, 8)}…): skipping LLM call`);
+                    }
+                    const filesByPath = new Map(files.map((f) => [f.path, f]));
+                    const groups = GroupingAgent.mapToFileGroups(cached, filesByPath);
+                    if (groups.length > 0)
+                        return groups;
+                    if (verbose) {
+                        verbose(`[grouping-agent] Cached results produced no valid groups; re-running LLM`);
+                    }
+                }
+            }
+            // 1. Read file contents
+            const fileContents = await GroupingAgent.readFiles(files);
+            if (verbose) {
+                const totalBytes = fileContents.reduce((sum, f) => sum + f.content.length, 0);
+                verbose(`[grouping-agent] Read ${fileContents.length} files (${totalBytes.toLocaleString()} bytes)`);
+            }
+            // 2. Analyze imports
+            const imports = GroupingAgent.analyzeImports(fileContents);
+            if (verbose) {
+                const totalImports = [...imports.values()].reduce((sum, deps) => sum + deps.length, 0);
+                verbose(`[grouping-agent] Found ${totalImports} import relationships`);
+            }
+            // 3. Run LLM — chunked path for large projects, single-prompt otherwise
+            let rawResults;
+            if (fileContents.length > GROUPING_CHUNK_THRESHOLD) {
+                if (verbose) {
+                    verbose(`[grouping-agent] File count (${fileContents.length}) exceeds threshold (${GROUPING_CHUNK_THRESHOLD}), using chunked grouping`);
+                }
+                const chunkedResults = await this.runChunkedRaw(fileContents, imports, verbose);
+                if (!chunkedResults)
+                    return null;
+                rawResults = chunkedResults;
+            }
+            else {
+                // Single-prompt path
+                const prompt = GroupingAgent.buildPrompt(this.projectName, fileContents, imports);
+                if (verbose) {
+                    verbose(`[grouping-agent] Prompt: ${prompt.length.toLocaleString()} chars`);
+                }
+                const sessionId = await this.createSession(`Hem: grouping — ${this.projectName}`);
+                if (verbose) {
+                    verbose(`[grouping-agent] Session created: ${sessionId}`);
+                }
+                const response = await this.provider.prompt(sessionId, prompt, { agent: "hem-group" }) ?? "";
+                if (verbose) {
+                    verbose(`[grouping-agent] Response: ${response.length.toLocaleString()} chars`);
+                }
+                const parsed = GroupingAgent.parseResponse(response);
+                if (!parsed) {
+                    if (verbose) {
+                        verbose(`[grouping-agent] Failed to parse JSON from response. First 500 chars: ${response.slice(0, 500)}`);
+                    }
+                    return null;
+                }
+                if (verbose) {
+                    verbose(`[grouping-agent] Parsed ${parsed.length} groups from LLM`);
+                }
+                rawResults = parsed;
+            }
+            // 4. Save to cache (best-effort — never fail the pipeline on write errors)
+            if (cacheDir) {
+                GroupingAgent.saveGroupingCache(cacheDir, filesHash, rawResults).catch(() => { });
+            }
+            // 5. Map to FileGroup[]
+            const filesByPath = new Map(files.map((f) => [f.path, f]));
+            const groups = GroupingAgent.mapToFileGroups(rawResults, filesByPath);
+            if (groups.length === 0) {
+                if (verbose) {
+                    verbose(`[grouping-agent] No valid groups after mapping (all file paths unrecognized?)`);
+                }
+                return null;
+            }
+            if (verbose) {
+                for (const g of groups) {
+                    verbose(`[grouping-agent] Group "${g.label}" (${g.type}): ${g.files.map((f) => f.path).join(", ")}`);
+                }
+            }
+            return groups;
+        }
+        catch (err) {
+            // Re-throw auth errors — those should not be swallowed.
+            if (err instanceof AuthExpiredError) {
+                throw err;
+            }
+            if (verbose) {
+                const msg = err instanceof Error ? err.message : String(err);
+                verbose(`[grouping-agent] Error: ${msg}`);
+            }
+            return null;
+        }
+    }
+    /**
+     * Chunked grouping for large file sets.
+     *
+     * Splits files into batches that fit within context limits, runs
+     * multiple grouping sessions in parallel, and merges the results.
+     * Returns raw {@link GroupingResult}[] (before `mapToFileGroups`).
+     */
+    async runChunkedRaw(fileContents, imports, verbose) {
+        // 1. Split files into chunks
+        const chunks = GroupingAgent.splitIntoChunks(fileContents, FILES_PER_CHUNK);
+        if (verbose) {
+            verbose(`[grouping-agent] Split ${fileContents.length} files into ${chunks.length} chunks`);
+        }
+        // 2. Run grouping sessions in parallel, respecting resource limits
+        const concurrency = Math.max(1, computeMaxConcurrency());
+        const limit = pLimit(concurrency);
+        if (verbose) {
+            verbose(`[grouping-agent] Running ${chunks.length} chunk sessions (concurrency: ${concurrency})`);
+        }
+        const chunkResults = await Promise.allSettled(chunks.map((chunk, idx) => limit(async () => {
+            const chunkLabel = `chunk-${idx + 1}/${chunks.length}`;
+            if (verbose) {
+                verbose(`[grouping-agent] Starting ${chunkLabel} (${chunk.length} files)`);
+            }
+            // Build a per-chunk import map (only imports relevant to this chunk's files)
+            const chunkPaths = new Set(chunk.map((f) => f.path));
+            const chunkImports = new Map();
+            for (const [file, deps] of imports) {
+                if (chunkPaths.has(file)) {
+                    chunkImports.set(file, deps);
+                }
+            }
+            const prompt = GroupingAgent.buildPrompt(this.projectName, chunk, chunkImports);
+            if (verbose) {
+                verbose(`[grouping-agent] ${chunkLabel} prompt: ${prompt.length.toLocaleString()} chars`);
+            }
+            const sessionId = await this.createSession(`Hem: grouping ${chunkLabel} — ${this.projectName}`);
+            const response = await this.provider.prompt(sessionId, prompt, { agent: "hem-group" }) ?? "";
+            const results = GroupingAgent.parseResponse(response);
+            if (!results) {
+                if (verbose) {
+                    verbose(`[grouping-agent] ${chunkLabel} failed to parse JSON. First 500 chars: ${response.slice(0, 500)}`);
+                }
+                return [];
+            }
+            if (verbose) {
+                verbose(`[grouping-agent] ${chunkLabel} produced ${results.length} groups`);
+            }
+            return results;
+        })));
+        // 3. Collect successful results, log failures
+        const allResults = [];
+        for (let i = 0; i < chunkResults.length; i++) {
+            const result = chunkResults[i];
+            if (result.status === "fulfilled") {
+                allResults.push(...result.value);
+            }
+            else {
+                // Re-throw auth errors
+                if (result.reason instanceof AuthExpiredError) {
+                    throw result.reason;
+                }
+                if (verbose) {
+                    const msg = result.reason instanceof Error
+                        ? result.reason.message
+                        : String(result.reason);
+                    verbose(`[grouping-agent] chunk-${i + 1}/${chunks.length} failed: ${msg}`);
+                }
+            }
+        }
+        if (allResults.length === 0) {
+            if (verbose) {
+                verbose(`[grouping-agent] All chunks failed or produced no groups`);
+            }
+            return null;
+        }
+        // 4. Merge overlapping groups from different chunks
+        const merged = GroupingAgent.mergeGroupingResults(allResults);
+        if (verbose) {
+            verbose(`[grouping-agent] Merged ${allResults.length} groups into ${merged.length} groups`);
+        }
+        return merged;
+    }
+    // ── Static helpers (pure functions, easy to unit test) ───────────────
+    /**
+     * Read file contents for all files. Files that fail to read get an
+     * error placeholder.
+     */
+    static async readFiles(files) {
+        const results = [];
+        for (const file of files) {
+            try {
+                const content = await readFile(file.absolutePath, "utf-8");
+                results.push({ path: file.path, content, size: file.size });
+            }
+            catch {
+                results.push({
+                    path: file.path,
+                    content: "[Error: unable to read file]",
+                    size: file.size,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Extract import dependencies from file contents via regex.
+     *
+     * Handles:
+     *   - `import ... from "./foo.js"`
+     *   - `import ... from "../bar/baz.js"`
+     *   - `import("./dynamic.js")`
+     *   - `require("./cjs.js")`
+     *
+     * Only tracks local (relative) imports — ignores node_modules.
+     *
+     * @returns Map from file path → array of imported file paths.
+     */
+    static analyzeImports(fileContents) {
+        const imports = new Map();
+        // Build a set of known file basenames (without extension) for resolution
+        const knownFiles = new Set(fileContents.map((f) => f.path));
+        for (const file of fileContents) {
+            const deps = [];
+            // Match: import ... from "./path" or import ... from "../path"
+            const staticImportPattern = /(?:import|export)\s+.*?\s+from\s+["'](\.[^"']+)["']/g;
+            // Match: import("./path") or require("./path")
+            const dynamicImportPattern = /(?:import|require)\s*\(\s*["'](\.[^"']+)["']\s*\)/g;
+            for (const pattern of [staticImportPattern, dynamicImportPattern]) {
+                let match;
+                while ((match = pattern.exec(file.content)) !== null) {
+                    const specifier = match[1];
+                    // Resolve relative to the file's directory
+                    const resolved = resolveImportPath(file.path, specifier, knownFiles);
+                    if (resolved) {
+                        deps.push(resolved);
+                    }
+                }
+            }
+            if (deps.length > 0) {
+                imports.set(file.path, [...new Set(deps)]);
+            }
+        }
+        return imports;
+    }
+    /**
+     * Build the grouping prompt from file summaries and import graph.
+     *
+     * Includes the first 40 lines of each file plus the dependency graph
+     * so the LLM can make informed grouping decisions.
+     */
+    static buildPrompt(projectName, fileContents, imports) {
+        const parts = [];
+        // System instructions
+        parts.push(`Analyze source files for the "${projectName}" project and group them for documentation.`, "");
+        // File summaries (first 40 lines each)
+        parts.push("## File Summaries", "");
+        for (const file of fileContents) {
+            const lines = file.content.split("\n");
+            const summary = lines.slice(0, 40).join("\n");
+            const truncated = lines.length > 40 ? ` (showing 40/${lines.length} lines)` : "";
+            parts.push(`### \`${file.path}\` (${file.size.toLocaleString()} bytes${truncated})`, "", "```", summary, "```", "");
+        }
+        // Import dependencies
+        if (imports.size > 0) {
+            parts.push("## Import Dependencies", "");
+            for (const [file, deps] of imports) {
+                parts.push(`- ${file} → ${deps.join(", ")}`);
+            }
+            parts.push("");
+        }
+        // Task
+        parts.push("## Task", "", "Group these files into cohesive documentation topics. Each group becomes one documentation page.", "");
+        // Rules
+        parts.push("## Rules", "", "- 2-6 files per group", "- Files MAY appear in multiple groups when they are central to multiple features", "- Prefer feature-based (\"vertical\") groups that bundle related functionality across layers", "- Use \"horizontal\" type only for cross-cutting concerns (e.g., shared utilities, type definitions)", "- Every file must appear in at least one group", "");
+        // Output format
+        parts.push("## Output", "", "Respond with ONLY a JSON array inside a ```json code fence. No other text before or after the fence.", "", "Each element must match this exact schema:", "```json", JSON.stringify({
+            id: "kebab-case-identifier",
+            label: "Human Readable Name",
+            type: "vertical | horizontal",
+            files: ["relative/path.ts"],
+            rationale: "1-sentence explanation",
+        }, null, 2), "```");
+        return parts.join("\n");
+    }
+    /**
+     * Extract and validate JSON from the LLM response.
+     *
+     * Tries to find a fenced ```json block first, then falls back to
+     * parsing the entire response as JSON.
+     *
+     * @returns Validated array of `GroupingResult`, or `null` if invalid.
+     */
+    static parseResponse(response) {
+        try {
+            // Extract JSON from LLM response (handles fenced blocks, preamble text)
+            const raw = extractJSON(response);
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                return null;
+            // Validate each element
+            for (const item of parsed) {
+                if (typeof item !== "object" ||
+                    item === null ||
+                    typeof item.id !== "string" ||
+                    typeof item.label !== "string" ||
+                    typeof item.type !== "string" ||
+                    !Array.isArray(item.files) ||
+                    typeof item.rationale !== "string") {
+                    return null;
+                }
+                if (!["vertical", "horizontal"].includes(item.type))
+                    return null;
+                if (item.files.length === 0)
+                    return null;
+                if (!item.files.every((f) => typeof f === "string")) {
+                    return null;
+                }
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Map validated LLM results to `FileGroup[]`.
+     *
+     * Resolves file paths against the known file set, skipping any
+     * paths the LLM hallucinated. Computes `directory` via
+     * `commonDirectory()` from `grouping.ts`.
+     */
+    static mapToFileGroups(results, filesByPath) {
+        const groups = [];
+        for (const result of results) {
+            // Resolve file paths — skip any the LLM hallucinated
+            const resolvedFiles = [];
+            for (const filePath of result.files) {
+                const info = filesByPath.get(filePath);
+                if (info) {
+                    resolvedFiles.push(info);
+                }
+            }
+            // Skip groups with fewer than 2 resolved files
+            if (resolvedFiles.length < 2)
+                continue;
+            groups.push({
+                id: toKebabCase(result.id),
+                label: result.label,
+                type: result.type,
+                files: resolvedFiles.sort((a, b) => a.path.localeCompare(b.path)),
+                directory: commonDirectory(resolvedFiles),
+            });
+        }
+        return groups;
+    }
+    /**
+     * Split file contents into batches of approximately `chunkSize` files.
+     *
+     * Files are split sequentially — no shuffling — so files that are
+     * close in the directory listing stay together, improving the LLM's
+     * ability to detect intra-chunk relationships.
+     */
+    static splitIntoChunks(fileContents, chunkSize) {
+        const chunks = [];
+        for (let i = 0; i < fileContents.length; i += chunkSize) {
+            chunks.push(fileContents.slice(i, i + chunkSize));
+        }
+        return chunks;
+    }
+    /**
+     * Merge grouping results from multiple chunks.
+     *
+     * Groups from different chunks may overlap — e.g., two chunks may each
+     * produce an "Authentication" group containing different files. This
+     * method merges groups with the same `id` (after kebab-case normalization)
+     * by combining their file lists and deduplicating.
+     *
+     * When groups share the same normalized ID:
+     *   - File lists are unioned (deduplicated).
+     *   - The label and type from the first occurrence are kept.
+     *   - Rationales are concatenated.
+     *
+     * @param results - All `GroupingResult[]` from every chunk (flattened).
+     * @returns Merged array of `GroupingResult`.
+     */
+    static mergeGroupingResults(results) {
+        const merged = new Map();
+        for (const result of results) {
+            const normalizedId = toKebabCase(result.id);
+            const existing = merged.get(normalizedId);
+            if (existing) {
+                // Merge file lists (deduplicate)
+                const fileSet = new Set([...existing.files, ...result.files]);
+                existing.files = [...fileSet];
+                // Append rationale if different
+                if (!existing.rationale.includes(result.rationale)) {
+                    existing.rationale = `${existing.rationale}; ${result.rationale}`;
+                }
+            }
+            else {
+                // First occurrence — clone to avoid mutating input
+                merged.set(normalizedId, {
+                    id: result.id,
+                    label: result.label,
+                    type: result.type,
+                    files: [...result.files],
+                    rationale: result.rationale,
+                });
+            }
+        }
+        return [...merged.values()];
+    }
+    // ── Grouping cache helpers ────────────────────────────────────────────
+    /**
+     * Compute a stable hash of the file list for cache invalidation.
+     * Uses path + size so renames and size changes invalidate the cache.
+     */
+    static computeFilesHash(files) {
+        const key = files
+            .map((f) => `${f.path}:${f.size}`)
+            .sort()
+            .join("\n");
+        return createHash("sha256").update(key).digest("hex");
+    }
+    /**
+     * Attempt to load a valid cache entry from `cacheDir`.
+     * Returns `null` on miss, parse error, or hash mismatch.
+     */
+    static async loadGroupingCache(cacheDir, filesHash) {
+        try {
+            const cacheFile = join(cacheDir, GROUPING_CACHE_FILE);
+            const raw = await readFile(cacheFile, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                parsed.version !== 1 ||
+                parsed.filesHash !== filesHash ||
+                !Array.isArray(parsed.results)) {
+                return null;
+            }
+            return parsed.results;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Write grouping results to the cache file (best-effort, never throws).
+     */
+    static async saveGroupingCache(cacheDir, filesHash, results) {
+        const cache = { version: 1, filesHash, results };
+        await mkdir(cacheDir, { recursive: true });
+        await writeFile(join(cacheDir, GROUPING_CACHE_FILE), JSON.stringify(cache, null, 2), "utf-8");
+    }
+}
+// ── Internal helpers ────────────────────────────────────────────────────
+/**
+ * Resolve a relative import specifier to a known file path.
+ *
+ * Handles `.js` extension stripping (TypeScript sources import `.js`
+ * but the actual files are `.ts`/`.tsx`).
+ */
+function resolveImportPath(fromFile, specifier, knownFiles) {
+    // Get directory of the importing file
+    const parts = fromFile.split("/");
+    parts.pop(); // remove filename
+    const dir = parts.join("/");
+    // Resolve the specifier relative to the importing file
+    const segments = (dir ? dir + "/" + specifier : specifier).split("/");
+    const resolved = [];
+    for (const seg of segments) {
+        if (seg === "." || seg === "")
+            continue;
+        if (seg === "..") {
+            resolved.pop();
+        }
+        else {
+            resolved.push(seg);
+        }
+    }
+    const resolvedPath = resolved.join("/");
+    // Try direct match
+    if (knownFiles.has(resolvedPath))
+        return resolvedPath;
+    // Try stripping .js and adding .ts / .tsx
+    const withoutJs = resolvedPath.replace(/\.js$/, "");
+    if (knownFiles.has(withoutJs + ".ts"))
+        return withoutJs + ".ts";
+    if (knownFiles.has(withoutJs + ".tsx"))
+        return withoutJs + ".tsx";
+    // Try the path as-is with .ts / .tsx
+    if (knownFiles.has(resolvedPath + ".ts"))
+        return resolvedPath + ".ts";
+    if (knownFiles.has(resolvedPath + ".tsx"))
+        return resolvedPath + ".tsx";
+    return null;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * 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 type { Provider } from "../providers/types.js";
+import type { ExplorationFindings } from "../types.js";
+import { BaseAgent } from "./base-agent.js";
+import type { ArchGroupSummary } from "./architecture-agent.js";
+/** Character-count threshold above which the index agent chunks its input. */
+export declare const INDEX_CHUNK_THRESHOLD = 80000;
+/** Summary produced by a single chunk session for later synthesis. */
+export interface IndexChunkSummary {
+    /** Short narrative describing what was found in this chunk. */
+    narrative: string;
+    /** Key concepts or terminology discovered. */
+    keyConcepts: string[];
+    /** Suggested reading guide entries. */
+    readingGuideEntries: string[];
+}
+/** Parameters for the index overview prompt. */
+export interface IndexPromptParams {
+    projectName: string;
+    destinationPath: string;
+    allDocFiles: string[];
+    allFindings: ExplorationFindings[];
+    allGroupSummaries: ArchGroupSummary[];
+}
+/**
+ * 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 declare class IndexAgent extends BaseAgent {
+    constructor(provider: 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.
+     */
+    run(params: IndexPromptParams, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Builds the index page prompt from exploration findings, group
+     * summaries, and the list of generated documentation files.
+     */
+    static buildPrompt(params: IndexPromptParams): string;
+    /**
+     * 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: IndexPromptParams): Array<{
+        findings: ExplorationFindings[];
+        summaries: ArchGroupSummary[];
+    }>;
+    /**
+     * 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: IndexPromptParams, chunkFindings: ExplorationFindings[], chunkSummaries: ArchGroupSummary[], chunkIndex: number, totalChunks: number): string;
+    /**
+     * 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: IndexPromptParams, chunkSummaries: IndexChunkSummary[]): string;
+}