@pruddiman/hem 0.0.1-beta-5671db0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Ruddiman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

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

package/dist/agents/arbiter-agent.js

@@ -0,0 +1,149 @@
+/**
+ * Arbiter agent for Hem's parallel organization pass.
+ *
+ * The arbiter is a lightweight coordinator that runs alongside N parallel
+ * org workers.  It receives all broadcast messages, evaluates SUGGESTION
+ * messages, and issues DECISION directives telling specific workers what
+ * to do.  It does NOT edit files itself.
+ *
+ * Lifecycle (two-phase, driven by OrganizationAgent.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 worker broadcasts and issues
+ * DECISION directives to resolve cross-subset issues.
+ *
+ * Does NOT edit files — directs workers to make all changes.
+ */
+export class ArbiterAgent 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 = "arbiter";
+        // 1. Build prompt
+        const prompt = ArbiterAgent.buildPrompt(params);
+        if (verbose) {
+            verbose(`[${tag}] prompt ${prompt.length.toLocaleString()} chars`);
+        }
+        // 2. Create session
+        const sessionId = await this.createSession("Hem: 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-org",
+                },
+            });
+        }
+        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 produced their manifests and the pipeline can continue.
+     */
+    async wrapUp(sessionId, verbose) {
+        const tag = "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-org" });
+            if (verbose) {
+                verbose(`[${tag}] wrap-up response (${(wrapUpResponse ?? "").length} chars)`);
+            }
+        }
+        catch (err) {
+            // Arbiter failure is not fatal — workers already produced manifests
+            if (verbose) {
+                verbose(`[${tag}] ⚠ wrap-up failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * Builds the arbiter prompt.
+     *
+     * The arbiter is a lightweight coordinator that:
+     *   - Receives all broadcasts from workers
+     *   - Evaluates SUGGESTION messages and issues DECISION directives
+     *   - Directs specific workers to take action on cross-subset issues
+     *   - 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 documentation organization pass on`, `**${projectName}** as the **arbiter**. There are ${totalWorkers} workers running in parallel,`, `each responsible for a subset of files.`, "", `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 org-worker-N:\". Message types:", "", "- **RENAMED**: A worker renamed/moved a file in their subset.", "- **DELETED**: A worker deleted a file (merged into another).", "- **CONVENTION**: A worker established a naming/structure convention.", "- **SUGGESTION**: A worker identified a cross-subset issue they cannot", "  resolve themselves (e.g., duplicate files across different workers).", "- **ACK**: A worker completed an action (edited files, updated links).", "");
+        // ── Your job ──────────────────────────────────────────────────────
+        parts.push("## Your job", "", "1. **Monitor all broadcasts.** You will passively receive RENAMED, DELETED,", "   CONVENTION, and ACK messages — you do not need to respond to these unless", "   you see a conflict or problem.", "", "2. **Act on SUGGESTION messages.** When a worker broadcasts a SUGGESTION", "   (e.g., \"these two files across different workers look like duplicates\"),", "   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. The orchestrator parses these to sequence operations", "   correctly (e.g., ensuring MERGE completes before DELETE on the same file).", "", "   **MERGE** — tell a worker to merge content from a source file into a target:", "", '   `broadcast({ message: "DECISION: @org-worker-2 MERGE auth/api-keys.md INTO auth/authentication-overview.md\\nMerge all API key setup instructions into the authentication overview." })`', "", "   **DELETE** — tell a worker to delete a file:", "", '   `broadcast({ message: "DECISION: @org-worker-2 DELETE auth/api-keys.md\\nThis file has been merged into auth/authentication-overview.md." })`', "", "   **UPDATE-LINKS** — tell a worker to update internal links in a file:", "", '   `broadcast({ message: "DECISION: @org-worker-3 UPDATE-LINKS guides/setup.md\\nUpdate the link to auth/api-keys.md → auth/authentication-overview.md" })`', "", "   **Free-form** — for anything that doesn't fit the above patterns:", "", '   `broadcast({ message: "DECISION: @org-worker-1 Rename the \'overview\' section heading to \'Introduction\' for consistency" })`', "", "   **Rules for DECISION messages:**", "   - **ALWAYS** address decisions to a specific worker using `@org-worker-N`.", "   - Messages without an `@` tag are broadcast to ALL workers, which wastes", "     resources. Only use `@all-workers` when every worker needs to act.", "   - When resolving duplicates, issue the MERGE first, then the DELETE.", "     The orchestrator will automatically hold the DELETE until the MERGE", "     completes.", "   - If multiple workers need to act, issue multiple decisions each tagged", "     to the specific worker.", "", "4. **Resolve conflicts.** If two workers propose contradictory conventions", "   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 issues after all workers have completed), you can recall", "a worker by broadcasting a message with this exact prefix:", "", '  `broadcast({ message: "RECALL: @org-worker-2 Fix the broken links in auth/overview.md — update references to the renamed 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 `@org-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.", "");
+        // ── Decision guidelines ───────────────────────────────────────────
+        parts.push("## Decision guidelines", "", "- When resolving duplicate files across workers, issue **two separate**", "  DECISION messages: first a MERGE telling the worker who owns the", "  CANONICAL file to merge content from the duplicate, then a DELETE", "  telling the worker who owns the duplicate to delete it entirely.", "  The orchestrator ensures the DELETE waits for the MERGE to complete.", "  Do NOT instruct workers to create redirect stubs or placeholder files —", "  duplicates must be fully removed.", "", "- When a rename or deletion affects links in other workers' files, issue", "  an UPDATE-LINKS DECISION to each affected worker.", "", "- Keep decisions specific and actionable. Include file paths and what", "  exactly should be done.", "");
+        // ── 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/architecture-agent.d.ts

@@ -0,0 +1,148 @@
+/**
+ * LLM-assisted architecture overview generation agent for Hem.
+ *
+ * Post-processing agent that runs AFTER cross-ref and organization agents.
+ * Uses an OpenCode session to generate the top-level `architecture.md`
+ * document by reading all generated documentation files and exploration
+ * findings.
+ *
+ * Architecture (v2):
+ *   - The agent writes `architecture.md` directly via the edit tool.
+ *   - The pipeline discovers what was written by scanning disk afterward.
+ *   - Reads existing generated docs from disk for context.
+ *   - Runs as the last content agent in the pipeline (after org + xref).
+ */
+import type { Provider } from "../providers/types.js";
+import type { ExplorationFindings } from "../types.js";
+import { BaseAgent } from "./base-agent.js";
+/**
+ * Maximum character count for the full architecture prompt before
+ * switching to chunked mode. Set conservatively below typical LLM
+ * context windows (~200K tokens ≈ ~800K chars) to leave room for
+ * the agent's tool interactions and responses.
+ */
+export declare const ARCH_PROMPT_CHAR_LIMIT = 400000;
+/**
+ * Target character count per chunk when splitting findings and group
+ * summaries for chunked architecture generation. Each chunk should
+ * comfortably fit in a single prompt alongside instructions.
+ */
+export declare const ARCH_CHUNK_TARGET_CHARS = 150000;
+/** Group summary for architecture prompt input. */
+export interface ArchGroupSummary {
+    id: string;
+    label: string;
+    files: string[];
+}
+/** Summary produced by a chunk summarization pass. */
+export interface ArchChunkSummary {
+    /** Index of the chunk (0-based). */
+    chunkIndex: number;
+    /** Key architectural patterns discovered in this chunk. */
+    patterns: string[];
+    /** Cross-cutting concerns identified. */
+    crossCuttingConcerns: string[];
+    /** Key integrations and external dependencies. */
+    integrations: string[];
+    /** System components and their responsibilities. */
+    components: string[];
+    /** Significant data flows or interaction patterns. */
+    dataFlows: string[];
+    /** Raw summary text from the LLM. */
+    rawSummary: string;
+}
+/** Parameters for the architecture overview prompt. */
+export interface ArchPromptParams {
+    projectName: string;
+    sourceRoot: string;
+    destinationPath: string;
+    allFindings: ExplorationFindings[];
+    allGroupSummaries: ArchGroupSummary[];
+    /** Paths of all generated doc files (for reading context). */
+    allDocFiles: string[];
+}
+/**
+ * An agent that uses an LLM to generate the architecture overview
+ * document for a project's documentation.
+ *
+ * Writes `architecture.md` directly via the edit tool. The pipeline
+ * discovers what was written by scanning disk afterward.
+ */
+export declare class ArchitectureAgent extends BaseAgent {
+    constructor(provider: Provider);
+    /**
+     * Run the architecture overview generation pipeline.
+     *
+     * When the full prompt would exceed `ARCH_PROMPT_CHAR_LIMIT`, the agent
+     * automatically switches to chunked mode: findings and group summaries
+     * are split into manageable batches, each batch is summarised by a
+     * dedicated session, and a final synthesis session combines the chunk
+     * summaries into the architecture overview.
+     *
+     * @param params  - All inputs needed for the architecture prompt.
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    run(params: ArchPromptParams, verbose?: (msg: string) => void): Promise<void>;
+    /**
+     * Chunked architecture generation for large projects.
+     *
+     * 1. Splits exploration findings and group summaries into chunks that
+     *    fit within context limits.
+     * 2. Runs a sequential summarisation session for each chunk.
+     * 3. Runs a final synthesis session that combines all chunk summaries
+     *    and writes `architecture.md` via the edit tool.
+     */
+    private runChunked;
+    /**
+     * Builds the architecture overview prompt from exploration findings
+     * and group summaries.
+     */
+    static buildPrompt(params: ArchPromptParams): string;
+    /**
+     * Formats all exploration findings for the architecture prompt.
+     */
+    static formatAllFindings(allFindings: ExplorationFindings[]): string;
+    /**
+     * Formats file group summaries as a list for the prompt.
+     */
+    static formatGroupSummaries(groups: ArchGroupSummary[]): string;
+    /**
+     * Split exploration findings and group summaries into chunks that each
+     * stay under `targetChars` when formatted.
+     *
+     * Findings and their corresponding group summaries are kept together.
+     * Groups without findings are distributed across chunks to balance
+     * size.
+     *
+     * @returns Array of chunks, each with a subset of findings and groups.
+     */
+    static chunkFindings(allFindings: ExplorationFindings[], allGroupSummaries: ArchGroupSummary[], targetChars: number): Array<{
+        findings: ExplorationFindings[];
+        groups: ArchGroupSummary[];
+    }>;
+    /**
+     * Build a prompt for summarising a single chunk of findings and groups.
+     *
+     * The LLM should return a structured JSON summary that can be fed
+     * into the synthesis phase.
+     */
+    static buildChunkSummaryPrompt(projectName: string, findings: ExplorationFindings[], groups: ArchGroupSummary[], chunkIndex: number, totalChunks: number): string;
+    /**
+     * Parse the LLM response from a chunk summarisation session into an
+     * `ArchChunkSummary`.
+     *
+     * Falls back to a minimal summary containing just the raw response
+     * text if JSON extraction fails — chunked mode should be resilient.
+     */
+    static parseChunkSummary(response: string, chunkIndex: number): ArchChunkSummary;
+    /**
+     * Build the final synthesis prompt that combines all chunk summaries
+     * and instructs the agent to write `architecture.md`.
+     *
+     * Reuses the same quality standards and document structure as the
+     * normal-mode `buildPrompt()`, but substitutes chunk summaries for
+     * the raw findings.
+     */
+    static buildSynthesisPrompt(params: ArchPromptParams, chunkSummaries: ArchChunkSummary[]): string;
+}