@pruddiman/hem 0.0.1-beta-5671db0

package/dist/agents/crossref-arbiter-agent.js

@@ -0,0 +1,147 @@
+/**
+ * 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 { isAuthExpired, AuthExpiredError } from "../auth.js";
+import { BaseAgent } from "./base-agent.js";
+// ── Agent ───────────────────────────────────────────────────────────────
+/**
+ * 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 class CrossRefArbiterAgent extends BaseAgent {
+    constructor(provider) {
+        super(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.
+     */
+    async run(params, verbose) {
+        const tag = "xref-arbiter";
+        // 1. Build prompt
+        const prompt = CrossRefArbiterAgent.buildPrompt(params);
+        if (verbose) {
+            verbose(`[${tag}] prompt ${prompt.length.toLocaleString()} chars`);
+        }
+        // 2. Create session
+        const sessionId = await this.createSession("Hem: xref-arbiter");
+        if (verbose) {
+            verbose(`[${tag}] session ${sessionId}`);
+        }
+        // 3. Fire the initial prompt (fire-and-forget — arbiter waits for broadcasts)
+        try {
+            await this.provider.session.promptAsync({
+                path: { id: sessionId },
+                body: {
+                    parts: [{ type: "text", text: prompt }],
+                    agent: "hem-xref",
+                },
+            });
+        }
+        catch (err) {
+            if (isAuthExpired(err)) {
+                throw new AuthExpiredError("the configured provider", err);
+            }
+            throw err;
+        }
+        if (verbose) {
+            verbose(`[${tag}] initial prompt sent (listening for broadcasts)`);
+        }
+        return { sessionId };
+    }
+    /**
+     * 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.
+     */
+    async wrapUp(sessionId, verbose) {
+        const tag = "xref-arbiter";
+        if (verbose) {
+            verbose(`[${tag}] all workers done, sending wrap-up prompt`);
+        }
+        try {
+            const wrapUpResponse = await this.provider.prompt(sessionId, "All workers have completed their tasks. If you have any remaining " +
+                "DECISION messages to issue, broadcast them now. Otherwise, output your " +
+                'final `{ "status": "complete" }` response.', { agent: "hem-xref" });
+            if (verbose) {
+                verbose(`[${tag}] wrap-up response (${(wrapUpResponse ?? "").length} chars)`);
+            }
+        }
+        catch (err) {
+            // Arbiter failure is not fatal — workers already made their edits
+            if (verbose) {
+                verbose(`[${tag}] ⚠ wrap-up failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * 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) {
+        const { projectName, destinationPath, allDocFiles, workerAssignments, } = params;
+        const totalWorkers = workerAssignments.length;
+        const workerLabels = workerAssignments.map((a) => a.label);
+        const parts = [];
+        // ── Role ──────────────────────────────────────────────────────────
+        parts.push(`Coordinate a parallel cross-reference pass on`, `**${projectName}** as the **arbiter**. There are ${totalWorkers} workers running in parallel,`, `each responsible for adding cross-reference links to a subset of`, `documentation files. Coordinate them for link consistency.`, "", `Coordinate only — do NOT edit files. Workers have the edit tool`, `and make all file changes themselves. Issue DECISION messages to tell`, `workers what to do.`, "", `**IMPORTANT: Workers are terminated immediately after they finish.**`, `If a worker has already completed and you need further changes`, `to their files, use the RECALL mechanism (see below).`, "");
+        // ── Workers ───────────────────────────────────────────────────────
+        parts.push("## Workers", "", `There are ${totalWorkers} workers: ${workerLabels.join(", ")}`, "");
+        // ── Destination directory ─────────────────────────────────────────
+        parts.push("## Destination directory", "", `All documentation files are in: \`${destinationPath}\``, "");
+        // ── Worker file assignments ─────────────────────────────────────
+        parts.push("## Worker file assignments", "", "Each worker owns a specific subset of files. When issuing DECISION", "directives, always target the worker that owns the affected file(s).", "");
+        for (const { label, files } of workerAssignments) {
+            parts.push(`### ${label}`, "");
+            for (const file of files) {
+                parts.push(`- \`${destinationPath}/${file}\``);
+            }
+            parts.push("");
+        }
+        // ── All files (flat list for cross-reference) ─────────────────────
+        parts.push("## All documentation files", "");
+        for (const file of allDocFiles) {
+            parts.push(`- \`${destinationPath}/${file}\``);
+        }
+        parts.push("");
+        // ── How it works ──────────────────────────────────────────────────
+        parts.push("## How this works", "", "Workers broadcast messages as they work. You will receive these messages", "as user messages prefixed with \"Message from xref-worker-N:\". Message types:", "", "- **LINK-ADDED**: A worker added a cross-reference link to one of their files.", "- **SUGGESTION**: A worker identified a cross-worker link consistency issue", "  they cannot resolve themselves (e.g., a reciprocal link is needed in", "  another worker's file).", "- **ACK**: A worker completed an action (added/updated links as requested).", "");
+        // ── Your job ──────────────────────────────────────────────────────
+        parts.push("## Your job", "", "1. **Monitor all broadcasts.** You will passively receive LINK-ADDED", "   and ACK messages — you do not need to respond to these unless", "   you see a link consistency issue.", "", "2. **Act on SUGGESTION messages.** When a worker broadcasts a SUGGESTION", "   (e.g., \"file X links to file Y but file Y does not link back\"),", "   evaluate it and issue a DECISION telling the appropriate worker(s)", "   what to do.", "", "3. **Issue DECISION messages.** Use the broadcast tool with one of these", "   structured formats, always addressed to a specific worker:", "", "   **ADD-LINK** — tell a worker to add a reciprocal cross-reference link:", "", '   `broadcast({ message: "DECISION: @xref-worker-2 ADD-LINK auth/overview.md → api/endpoints.md\\nAdd a link to api/endpoints.md in the Related Documentation section." })`', "", "   **UPDATE-LINK** — tell a worker to update a cross-reference link:", "", '   `broadcast({ message: "DECISION: @xref-worker-2 UPDATE-LINK auth/overview.md\\nUpdate the link text for api/endpoints.md to be more descriptive." })`', "", "   **Free-form** — for anything that doesn't fit the above patterns:", "", '   `broadcast({ message: "DECISION: @xref-worker-1 Review the Related Documentation section in auth/overview.md for completeness." })`', "", "   **Rules for DECISION messages:**", "   - **ALWAYS** address decisions to a specific worker using `@xref-worker-N`.", "   - Messages without an `@` tag are broadcast to ALL workers, which wastes", "     resources. Only use `@all-workers` when every worker needs to act.", "   - If multiple workers need to act, issue multiple decisions each tagged", "     to the specific worker.", "", "4. **Resolve conflicts.** If two workers propose contradictory link structures", "   or make conflicting changes, issue a DECISION picking one approach.", "", "5. **Never edit files.** This is a coordination task, not editing. Workers have", "   the edit tool and make all file changes themselves.", "");
+        // ── RECALL mechanism ──────────────────────────────────────────────
+        parts.push("## RECALL mechanism", "", "Workers are terminated immediately after they finish. If", "you discover during wrap-up that a worker's files need further changes", "(e.g., you spot link consistency issues after all workers have completed),", "you can recall a worker by broadcasting a message with this exact prefix:", "", '  `broadcast({ message: "RECALL: @xref-worker-2 Add a reciprocal link in auth/overview.md pointing back to api/endpoints.md" })`', "", "The orchestrator will intercept this message and spawn a **new** session", "with that worker's original file assignment plus your fix instructions.", "The recalled worker will make the edits directly.", "", "Rules for RECALL:", "- Use `RECALL:` prefix followed by `@xref-worker-N` and clear instructions.", "- Only recall workers whose files actually need changes.", "- Be specific about what needs to be fixed — the recalled worker gets", "  your instructions verbatim.", "");
+        // ── Output format ─────────────────────────────────────────────────
+        parts.push("## Output format", "", "Wait for worker broadcasts. Process them as described above. When you are", "finished coordinating (no pending suggestions to resolve), respond with", "ONLY:", "", "```json", '{ "status": "complete" }', "```");
+        return parts.join("\n");
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * LLM-assisted documentation generation agent for Hem.
+ *
+ * Uses an OpenCode session to generate documentation for a single file
+ * group. The agent writes documentation files directly via the edit tool.
+ * The pipeline discovers what was written by scanning disk afterward.
+ *
+ * Architecture (v2):
+ *   - The agent has full autonomy over file naming, structure, and how
+ *     many files to create per group.
+ *   - The agent writes files directly — Hem does NOT write files.
+ *   - If existing docs are provided, the agent merges inline.
+ */
+import type { Provider } from "../providers/types.js";
+import type { FileGroup, GenerationContext, ExplorationFindings } from "../types.js";
+import { BaseAgent } from "./base-agent.js";
+/**
+ * An agent that uses an LLM to generate documentation for a single
+ * file group. The agent writes files directly via the edit tool.
+ */
+export declare class DocumentationAgent extends BaseAgent {
+    constructor(provider: Provider);
+    /**
+     * Run the documentation generation pipeline for a single group.
+     *
+     * @param group   - The file group to document.
+     * @param context - Shared generation context (includes exploration findings,
+     *                  existing docs for merge, destination path).
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    run(group: FileGroup, context: GenerationContext, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Returns the exploration findings text for inclusion in the prompt.
+     */
+    static formatFindings(findings: ExplorationFindings): string;
+    /**
+     * Summarizes all findings for cross-group context (excludes the current group).
+     */
+    static summarizeCrossGroupFindings(allFindings: ExplorationFindings[], currentGroupId: string): string;
+    /**
+     * Builds the documentation generation prompt.
+     *
+     * The agent writes files directly using the edit tool and returns
+     * a JSON manifest of files written. The prompt includes:
+     *   - File group details
+     *   - Quality standards
+     *   - Exploration findings
+     *   - Existing docs for merge context
+     *   - Tool-usage instructions
+     *   - Cross-group context
+     *   - Output manifest format
+     */
+    static buildPrompt(group: FileGroup, context: GenerationContext): string;
+}

package/dist/agents/documentation-agent.js

@@ -0,0 +1,159 @@
+/**
+ * LLM-assisted documentation generation agent for Hem.
+ *
+ * Uses an OpenCode session to generate documentation for a single file
+ * group. The agent writes documentation files directly via the edit tool.
+ * The pipeline discovers what was written by scanning disk afterward.
+ *
+ * Architecture (v2):
+ *   - The agent has full autonomy over file naming, structure, and how
+ *     many files to create per group.
+ *   - The agent writes files directly — Hem does NOT write files.
+ *   - If existing docs are provided, the agent merges inline.
+ */
+import { BaseAgent } from "./base-agent.js";
+// ── Agent ───────────────────────────────────────────────────────────────
+/**
+ * An agent that uses an LLM to generate documentation for a single
+ * file group. The agent writes files directly via the edit tool.
+ */
+export class DocumentationAgent extends BaseAgent {
+    constructor(provider) {
+        super(provider);
+    }
+    /**
+     * Run the documentation generation pipeline for a single group.
+     *
+     * @param group   - The file group to document.
+     * @param context - Shared generation context (includes exploration findings,
+     *                  existing docs for merge, destination path).
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    async run(group, context, verbose) {
+        const tag = `doc-agent:${group.id}`;
+        // 1. Build prompt (file contents are NOT embedded — agent reads via tools)
+        const prompt = DocumentationAgent.buildPrompt(group, context);
+        if (verbose) {
+            verbose(`[${tag}] Prompt: ${prompt.length.toLocaleString()} chars`);
+        }
+        // 2. Create a new session
+        const sessionId = await this.createSession(`Hem: doc — ${group.label}`);
+        if (verbose) {
+            verbose(`[${tag}] Session created: ${sessionId}`);
+        }
+        // 3. Send prompt and wait for response — use hem-doc agent
+        await this.provider.prompt(sessionId, prompt, { agent: "hem-doc" });
+        if (verbose) {
+            verbose(`[${tag}] Agent completed`);
+        }
+    }
+    // ── Static helpers (pure functions, easy to unit test) ───────────────
+    /**
+     * Returns the exploration findings text for inclusion in the prompt.
+     */
+    static formatFindings(findings) {
+        return findings.text;
+    }
+    /**
+     * Summarizes all findings for cross-group context (excludes the current group).
+     */
+    static summarizeCrossGroupFindings(allFindings, currentGroupId) {
+        const others = allFindings.filter((f) => f.groupId !== currentGroupId);
+        if (others.length === 0)
+            return "No other groups explored.";
+        return others.map((f) => `### ${f.groupId}\n${f.text}`).join("\n\n");
+    }
+    /**
+     * Builds the documentation generation prompt.
+     *
+     * The agent writes files directly using the edit tool and returns
+     * a JSON manifest of files written. The prompt includes:
+     *   - File group details
+     *   - Quality standards
+     *   - Exploration findings
+     *   - Existing docs for merge context
+     *   - Tool-usage instructions
+     *   - Cross-group context
+     *   - Output manifest format
+     */
+    static buildPrompt(group, context) {
+        const parts = [];
+        const groupFindings = context.groupFindings;
+        const allFindings = context.explorationFindings;
+        // 1. System-level instructions
+        parts.push(`Generate documentation files that answer the questions the code asks — not`, `merely describe what the code does.`, "", `**You write files directly using the edit tool.** Do NOT return Markdown content`, `in your response text. Instead, use the edit tool to create and write files in`, `the destination directory. When you are done writing all files, stop.`, "");
+        // 2. Where to write files
+        parts.push("## Destination directory", "", `Write all documentation files under: \`${context.destinationPath}\``, "", `You have full autonomy over:`, `- **File naming**: Choose descriptive kebab-case filenames (e.g., \`user-authentication.md\`)`, `- **Directory structure**: Create subdirectories that make sense for this codebase`, `- **Number of files**: Create as many files as needed to properly document the group`, `- **File structure**: Design each document's heading hierarchy and sections`, "", `Guidelines for file organization:`, `- Choose a directory layout that reflects how the codebase is actually organized`, `- You may use flat files, subdirectories, or nested structures — whatever fits best`, `- Use \`.md\` extension for all files`, "");
+        // 3. Quality standards
+        parts.push("## Quality Standard: Answer Every Question", "", "Your primary quality standard is: **every question from the exploration findings", "MUST be answered in the generated documentation.** Do NOT leave any question", "unanswered. If you cannot find a definitive answer, state what is known and what", "requires further investigation — but NEVER silently skip a question.", "", "For each integration discovered in the exploration findings:", "", "1. **Use `webfetch` to research answers**: When an integration has an", "   `officialDocsUrl`, fetch that URL to find authoritative answers.", "2. **Address HOW, not just WHAT**: Explain HOW to access, query, monitor,", "   and troubleshoot each integration.", "3. **Answer operational questions**: Every `operationalQuestions` entry for each", "   integration MUST be answered in the documentation.", "");
+        parts.push("## Documentation quality standards", "");
+        parts.push("You MUST follow these principles:", "");
+        parts.push(`1. **Answer the questions the code asks**: For every service, integration, or`, `   dependency, address the operational and conceptual questions a reader would`, `   naturally ask.`, "", `2. **WHAT/WHY/HOW structure**:`, `   - Overview pages: convey WHAT the application is and WHY it exists`, `   - Module/component pages: convey WHAT it does, WHY it exists, and HOW it works`, "", `3. **No verbatim source code (FR-006 / FR-007)**: Reference source files by`, `   path link only.`, "", `4. **Google Markdown style guide**: ATX-style headings, single H1 per page,`, `   informative link titles, 4-space indent for nested lists, Markdown over HTML.`, "", `5. **Mermaid diagrams**: Include only when complexity warrants them (check`, `   exploration findings for \`ComplexitySignal\` entries).`, "", `6. **Readable structure**: Heading hierarchy, section ordering, and navigation`, `   flow are first-class concerns.`, "", `7. **Cross-references**: Link to related documentation pages using relative paths.`, "");
+        // 4. Task description
+        parts.push("## Your task", "");
+        parts.push("Generate documentation for the following file group.", "");
+        parts.push(`**Group**: ${group.label} (ID: ${group.id})`, `**Group type**: ${group.type} (${group.type === "vertical" ? "feature slice" : "architectural layer"})`, `**Files to document**:`);
+        for (const file of group.files) {
+            parts.push(`- \`${file.path}\``);
+        }
+        parts.push("");
+        parts.push(`**Source root**: ${context.sourceRoot}`, `**Project name**: ${context.projectName}`, "");
+        // 5. Exploration findings for this group
+        parts.push("## Exploration findings for this group", "");
+        if (groupFindings) {
+            parts.push("The exploration phase discovered these findings for your group:", "");
+            parts.push(DocumentationAgent.formatFindings(groupFindings));
+        }
+        else {
+            parts.push("No exploration findings available for this group. Use tools to read and analyze the source files directly.", "");
+        }
+        // 6. Cross-group context
+        parts.push("## Cross-group context", "");
+        parts.push("Other groups discovered these integrations and dependencies that may relate to", "your group:", "");
+        parts.push(DocumentationAgent.summarizeCrossGroupFindings(allFindings, group.id));
+        parts.push("");
+        // 7. Existing docs — search-before-write with skip/update/create decisions
+        if (context.existingDocs.length > 0 || (context.mentionedDocPaths && context.mentionedDocPaths.length > 0)) {
+            parts.push("## Existing documentation in destination", "");
+            parts.push("The destination directory already contains documentation files.", "**Before writing ANY file, you MUST search for related existing docs.**", "", "### Decision criteria for each topic you plan to document:", "", "1. **SKIP** — if an existing doc already covers the topic accurately and", "   completely. Do NOT rewrite content that is already correct.", "2. **UPDATE** — if an existing doc covers the topic but is stale, incomplete,", "   or missing sections. Update it **in place** using the edit tool. Preserve", "   accurate content; fix or expand what is stale or missing.", "3. **CREATE** — if no existing doc covers the topic. Write a new file.", "", "**Content-only changes**: Do NOT rename, move, or delete existing files.", "Only modify file content.", "");
+            // Full content for the most relevant docs
+            if (context.existingDocs.length > 0) {
+                parts.push(`### Most relevant existing docs (${context.existingDocs.length} file${context.existingDocs.length === 1 ? "" : "s"}, full content)`, "");
+                for (const doc of context.existingDocs) {
+                    parts.push(`#### \`${doc.path}\``);
+                    parts.push("```markdown");
+                    parts.push(doc.content);
+                    parts.push("```");
+                    parts.push("");
+                }
+            }
+            // Path-only mentions for the rest
+            if (context.mentionedDocPaths && context.mentionedDocPaths.length > 0) {
+                parts.push(`### Other existing docs (${context.mentionedDocPaths.length} file${context.mentionedDocPaths.length === 1 ? "" : "s"}, paths only)`, "", "These files also exist in the destination directory. Use `cat` or `grep`", "to read them if they might overlap with your topic:", "");
+                for (const p of context.mentionedDocPaths) {
+                    parts.push(`- \`${p}\``);
+                }
+                parts.push("");
+            }
+            parts.push("### How to search before writing", "", "Before creating or updating documentation for a topic, search the", "destination directory for existing coverage:", "", `1. Run \`find ${context.destinationPath} -name '*.md' | xargs grep -li '<keyword>'\``, "   where `<keyword>` is a key term from the topic you're about to write.", "2. Read any matching files with `cat` to assess their current content.", "3. Apply the SKIP / UPDATE / CREATE decision above.", "", "You may delegate this search to a subagent if you prefer — spawn a", "subagent to search and summarize existing coverage, then use its report", "to decide what to write or update.", "");
+        }
+        // 8. How to work
+        parts.push("## How to work", "");
+        parts.push(`0. **Search before writing**: Before creating or updating any documentation`, `   file, search the destination directory for existing docs that cover the`, `   same topic. Apply the SKIP / UPDATE / CREATE decision criteria above.`, `1. **Read files using tools**: Use the file read tool, grep, or bash commands to`, `   read the source files. Do NOT ask me to provide file contents.`, `2. **Answer EVERY question**: Go through the exploration findings systematically.`, `   Use \`webfetch\` to fetch official documentation URLs.`, `3. **Write files directly**: Use the edit tool to create documentation files in`, `   the destination directory. Do NOT return Markdown in your response text.`, `4. **Generate diagrams**: If exploration findings include complexity signals,`, `   generate Mermaid diagrams.`, `5. **Link to related pages**: Use relative paths to link to other documentation`, `   pages listed in the group summaries below.`, "");
+        // 9. Other documentation groups
+        if (context.allGroups.length > 1) {
+            parts.push("## Other documentation groups being generated", "");
+            for (const g of context.allGroups) {
+                if (g.id !== group.id) {
+                    parts.push(`- **${g.label}** (${g.id}): ${g.files.join(", ")}`);
+                }
+            }
+            parts.push("");
+        }
+        // 10. Done
+        parts.push("## When you are done", "");
+        parts.push(`After writing all documentation files 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 what you wrote.`);
+        return parts.join("\n");
+    }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * LLM-assisted code exploration agent for Hem.
+ *
+ * Uses an OpenCode session to discover what questions the code asks.
+ * Explores a file group using tools (read, glob, grep, bash) and
+ * webfetch, and outputs a structured natural-language report that
+ * informs the DocumentationAgent.
+ *
+ * The agent:
+ *   1. Builds a structured prompt with file paths (NOT contents).
+ *   2. Sends the prompt to an OpenCode session with `agent: "hem-explore"`.
+ *   3. Returns the response text directly — no JSON parsing needed.
+ *
+ * This agent implements FR-002 (answer the questions code asks),
+ * FR-013 (tool-based exploration), and FR-014 (read-only plan mode).
+ */
+import type { Provider } from "../providers/types.js";
+import type { FileGroup, ExplorationFindings } from "../types.js";
+import { BaseAgent } from "./base-agent.js";
+/**
+ * An agent that uses an LLM to explore a file group and produce a
+ * natural-language exploration report covering questions, integrations,
+ * complexity signals, style guides, and cross-group dependencies.
+ */
+export declare class ExplorationAgent extends BaseAgent {
+    constructor(provider: Provider);
+    /**
+     * Run the exploration pipeline: prompt → send → return text.
+     *
+     * @param group       - The file group to explore.
+     * @param sourceRoot  - Absolute path to the source root directory.
+     * @param allGroups   - Summaries of all groups for cross-group awareness.
+     * @param verbose     - Optional logging callback (writes to stderr).
+     * @returns `ExplorationFindings` containing the natural-language report.
+     * @throws If session creation or prompting fails.
+     */
+    run(group: FileGroup, sourceRoot: string, allGroups: Array<{
+        id: string;
+        label: string;
+        files: string[];
+    }>, verbose?: (msg: string) => void): Promise<ExplorationFindings>;
+    /**
+     * Builds the exploration prompt for a file group.
+     *
+     * Contains file paths (NOT file contents), instructions for tool-based
+     * exploration, and the expected natural-language report format.
+     *
+     * @param group      - The file group to explore.
+     * @param sourceRoot - Absolute path to the source root directory.
+     * @param allGroups  - Summaries of all groups for cross-group awareness.
+     * @returns The prompt string.
+     */
+    static buildPrompt(group: FileGroup, sourceRoot: string, allGroups: Array<{
+        id: string;
+        label: string;
+        files: string[];
+    }>): string;
+}

package/dist/agents/exploration-agent.js

@@ -0,0 +1,102 @@
+/**
+ * LLM-assisted code exploration agent for Hem.
+ *
+ * Uses an OpenCode session to discover what questions the code asks.
+ * Explores a file group using tools (read, glob, grep, bash) and
+ * webfetch, and outputs a structured natural-language report that
+ * informs the DocumentationAgent.
+ *
+ * The agent:
+ *   1. Builds a structured prompt with file paths (NOT contents).
+ *   2. Sends the prompt to an OpenCode session with `agent: "hem-explore"`.
+ *   3. Returns the response text directly — no JSON parsing needed.
+ *
+ * This agent implements FR-002 (answer the questions code asks),
+ * FR-013 (tool-based exploration), and FR-014 (read-only plan mode).
+ */
+import { BaseAgent } from "./base-agent.js";
+// ── Agent ───────────────────────────────────────────────────────────────
+/**
+ * An agent that uses an LLM to explore a file group and produce a
+ * natural-language exploration report covering questions, integrations,
+ * complexity signals, style guides, and cross-group dependencies.
+ */
+export class ExplorationAgent extends BaseAgent {
+    constructor(provider) {
+        super(provider);
+    }
+    /**
+     * Run the exploration pipeline: prompt → send → return text.
+     *
+     * @param group       - The file group to explore.
+     * @param sourceRoot  - Absolute path to the source root directory.
+     * @param allGroups   - Summaries of all groups for cross-group awareness.
+     * @param verbose     - Optional logging callback (writes to stderr).
+     * @returns `ExplorationFindings` containing the natural-language report.
+     * @throws If session creation or prompting fails.
+     */
+    async run(group, sourceRoot, allGroups, verbose) {
+        const tag = `explore-agent:${group.id}`;
+        // 1. Build prompt
+        const prompt = ExplorationAgent.buildPrompt(group, sourceRoot, allGroups);
+        if (verbose) {
+            verbose(`[${tag}] Prompt: ${prompt.length.toLocaleString()} chars`);
+        }
+        // 2. Create a new session
+        const sessionId = await this.createSession(`Hem: explore — ${group.label}`);
+        if (verbose) {
+            verbose(`[${tag}] Session created: ${sessionId}`);
+        }
+        // 3. Send prompt and wait for response
+        const response = await this.provider.prompt(sessionId, prompt, { agent: "hem-explore" }) ?? "";
+        if (verbose) {
+            verbose(`[${tag}] Response: ${response.length.toLocaleString()} chars`);
+        }
+        return { groupId: group.id, text: response };
+    }
+    // ── Static helpers (pure functions, easy to unit test) ───────────────
+    /**
+     * Builds the exploration prompt for a file group.
+     *
+     * Contains file paths (NOT file contents), instructions for tool-based
+     * exploration, and the expected natural-language report format.
+     *
+     * @param group      - The file group to explore.
+     * @param sourceRoot - Absolute path to the source root directory.
+     * @param allGroups  - Summaries of all groups for cross-group awareness.
+     * @returns The prompt string.
+     */
+    static buildPrompt(group, sourceRoot, allGroups) {
+        const parts = [];
+        // System-level instructions
+        parts.push(`Discover what questions the code asks — the operational, conceptual, and`, `architectural questions that a reader would naturally have after reading`, `this code.`, "", "## Quality Standard: Answer the Questions Code Asks", "", "Your primary quality standard is: **documentation must go beyond surface-level", "descriptions to answer the operational, conceptual, and architectural", "questions that integrations, services, and dependencies naturally", "raise.** Simply noting that an integration exists (e.g., \"Application Insights is", "configured\") is NOT sufficient. You must discover the NEXT questions a reader", "would ask:", "", "- **Operational**: How do I access, query, monitor, rotate credentials for, or", "  troubleshoot this integration? Where is data stored? What dashboard do I use?", "- **Conceptual**: Why was this technology chosen? What problem does it solve?", "  What are its limitations?", "- **Architectural**: How does this integration fit into the larger system? What", "  depends on it? What happens if it fails?", "", "For every integration you discover, you MUST:", "1. Identify at least 2 operational questions (e.g., \"Where is telemetry data", "   stored?\", \"How do I access the dashboard?\", \"How do I rotate secrets?\")", "2. Categorize each question as operational, conceptual, or architectural", "3. Suggest sources where answers might be found (e.g., \"Azure Application", "   Insights docs\", \"AWS Secrets Manager console\", \"Redis CLI documentation\")", "");
+        // FR-006: No verbatim source code in findings
+        parts.push("## No verbatim source code (FR-006)", "", "Your exploration report MUST NOT contain verbatim project source code.", "Follow these rules strictly:", "", "1. Reference code by file path and line number, NOT by embedding code snippets.", "   - CORRECT: \"Call to AddApplicationInsights() in startup.ts:42\"", "   - WRONG: \"const client = new Redis({ host: 'localhost' })\"", "", "2. If you need to describe what code does, use prose. For example, instead", "   of copying a function body, write: \"The retry logic in `src/client.ts:85`", "   uses exponential backoff with a maximum of 3 attempts.\"", "", "3. You MAY mention function names, class names, and identifiers by name (e.g.,", "   \"the `connectToDatabase()` function in `src/db.ts:22`\"), but you MUST NOT", "   reproduce their implementation code.", "");
+        // Task description
+        parts.push("## Your task", "", "Explore the following file group and produce a structured exploration report.", "", `**Group**: ${group.label} (ID: ${group.id})`, "**Files to explore**:");
+        for (const file of group.files) {
+            parts.push(`- ${file.path}`);
+        }
+        parts.push("");
+        parts.push(`**Source root**: ${sourceRoot}`);
+        parts.push("");
+        // How to explore
+        parts.push("## How to explore", "", "Use your tools to read and analyze the source files. Do NOT ask me to provide", "file contents — read them yourself using the file read tool, grep, or bash", "commands.", "", "For each file in the group:", "", "1. **Read the file** using the file read tool", "2. **Identify integrations**: Look for imports, API calls, database connections,", "   cloud service SDKs, message queue producers/consumers, HTTP clients, and any", "   external dependency", "3. **Ask \"what questions does this raise?\"**: For each integration or complex", "   pattern, think about what a reader would need to know:", "   - Where is data stored? How do I access it?", "   - How do I query/monitor/troubleshoot this?", "   - What happens when this fails?", "   - How do I rotate credentials for this?", "   - What are the performance characteristics?", "4. **Generate operational questions for every integration**: At least 2 per", "   integration. Examples:", "   - Database: \"How do I access the database?\", \"How do backups work?\"", "   - Monitoring: \"How do I access the dashboard?\", \"What is the data retention?\"", "   - Secrets: \"How do I rotate secrets?\", \"What happens if a secret expires?\"", "5. **Detect complexity signals**: Look for patterns that warrant diagrams:", "   - 3+ services interacting in a flow", "   - 5+ database tables with relationships", "   - Complex state machines or workflows", "   - Cloud infrastructure configuration", "6. **Find style guides**: Systematically search for style guides, brand", "   guidelines, and design system artifacts (`.editorconfig`, ESLint/Prettier", "   configs, brand asset directories, design token files).", "7. **Note cross-group dependencies**: If this code depends on or shares entities", "   with files in other groups, note which groups", "");
+        // Webfetch policy
+        parts.push("## Webfetch policy", "", "You MAY use webfetch to look up official documentation for integrations you", "discover. Rules:", "- Only fetch from official/authoritative sources (e.g., official docs sites,", "  GitHub repos of the integration)", "- You may first discover what the official docs URL is, then fetch it", "- Do NOT fetch random blog posts, Stack Overflow, or unofficial sources", "- If you cannot determine the official source, note the integration without a URL", "");
+        // Other groups
+        const otherGroups = allGroups.filter((g) => g.id !== group.id);
+        if (otherGroups.length > 0) {
+            parts.push("## Other groups in this project (for cross-reference awareness)", "");
+            for (const g of otherGroups) {
+                parts.push(`- **${g.label}** (${g.id}): ${g.files.join(", ")}`);
+            }
+            parts.push("");
+        }
+        // Style Guide Reference (Google Markdown Style Guide — FR-010)
+        parts.push("## Style Guide Reference", "", "All text you produce MUST follow these formatting rules:", "", "1. **ATX-style headings only** — use `#` syntax, never Setext style.", "2. **Informative link titles** — use descriptive text, never `[click here](…)`.", "3. **4-space indent for nested lists**.", "4. **Prefer Markdown over HTML**.", "");
+        // Output format
+        parts.push("## Output format", "", "Write a structured natural-language exploration report with these sections:", "", "### Summary", "One paragraph explaining what this group does and why it exists.", "", "### Questions to Answer", "Key questions a reader of this code would have. For each question:", "- State the question", "- Classify it: **operational**, **conceptual**, or **architectural**", "- Note what in the source raised it (file:line reference)", "- Suggest where the answer might be found", "", "### Integrations Discovered", "External services, libraries, databases, APIs, or cloud services found.", "For each integration:", "- Name and type (e.g., database, cloud-service, messaging, auth, monitoring)", "- Source file(s) where configured or used (file:line references)", "- Official docs URL if known", "- At least 2 operational questions about how to access/monitor/troubleshoot it", "", "### Complexity Signals", "Patterns that warrant a diagram or deeper architectural explanation.", "For each signal:", "- What makes it complex", "- Which files are involved", "- What diagram type would help (flowchart, sequence, er, c4, or state)", "", "### Style Guides Found", "Any linting, formatting, brand, or design system artifacts found.", "If none found, write: \"None found.\"", "", "### Cross-Group Dependencies", "Other group IDs this group depends on or shares entities with.", "Use the group IDs from the list above (e.g., `agent-system`, `orchestrator`).", "If none, write: \"None.\"", "", "Write clear, concise prose. Do not use JSON. Do not include verbatim source code.");
+        return parts.join("\n");
+    }
+}