@pruddiman/hem 0.0.1-beta-5671db0

package/dist/search-mcp.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Standalone stdio-based MCP server exposing the Hem doc search index.
+ *
+ * Exposes two tools:
+ *   - `search_docs({ query, limit? })` — FTS5 keyword search over indexed docs
+ *   - `get_docs_for_source({ source_path })` — find docs covering a source file
+ *
+ * Receives the SQLite DB path as the first CLI argument:
+ *   node dist/search-mcp.js /path/to/.hem/search-index.db
+ *
+ * Opens the DB in read-only mode. Multiple agent processes may connect
+ * simultaneously; SQLite WAL mode handles concurrent reads safely.
+ *
+ * Registered in OpenCode via config.mcp as:
+ *   { type: "local", command: ["node", "dist/search-mcp.js", dbPath], enabled: true }
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { fileURLToPath } from "node:url";
+import { z } from "zod/v4";
+import { SearchIndex } from "./search-index.js";
+/**
+ * Build the hem-search MCP server bound to the given SearchIndex.
+ * Exported for tests; the CLI bootstrap below wires it up to a stdio
+ * transport with a real read-only SQLite-backed index.
+ */
+export function createSearchMcpServer(index) {
+    const server = new McpServer({
+        name: "hem-search",
+        version: "1.0.0",
+    });
+    server.registerTool("search_docs", {
+        description: "Search existing documentation files by keyword. Returns the most relevant " +
+            "docs with short snippets. Use this before creating or updating a doc to find " +
+            "existing coverage. Example: search_docs({ query: 'authentication session token' })",
+        inputSchema: {
+            query: z.string().describe("Search terms — keywords, phrases, or topic names"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .describe("Maximum results to return (default 5, max 20)"),
+        },
+    }, ({ query, limit }) => {
+        const results = index.search(query, limit ?? 5);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ results }),
+                },
+            ],
+        };
+    });
+    server.registerTool("get_docs_for_source", {
+        description: "Find documentation files that cover a given source code file. " +
+            "Useful for checking whether a source file is already documented. " +
+            "Example: get_docs_for_source({ source_path: 'src/auth/login.ts' })",
+        inputSchema: {
+            source_path: z
+                .string()
+                .describe("Relative path to the source file, e.g. 'src/auth/login.ts'"),
+        },
+    }, ({ source_path }) => {
+        const doc_paths = index.getDocsForSource(source_path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ doc_paths }),
+                },
+            ],
+        };
+    });
+    return server;
+}
+async function main() {
+    const dbPath = process.argv[2];
+    if (!dbPath) {
+        console.error("[hem-search] Usage: node search-mcp.js <dbPath>");
+        process.exit(1);
+    }
+    const index = SearchIndex.open(dbPath, /* readonly */ true);
+    const server = createSearchMcpServer(index);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[hem-search] MCP server running on stdio");
+}
+// Only auto-run when invoked directly (not when imported by tests).
+const isDirectRun = process.argv[1] !== undefined &&
+    fileURLToPath(import.meta.url) === process.argv[1];
+if (isDirectRun) {
+    main().catch((err) => {
+        console.error("[hem-search] Fatal:", err);
+        process.exit(1);
+    });
+}

package/dist/server-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Server lifecycle utilities for Hem.
+ *
+ * Provides:
+ *   - `findFreePort()` — discovers an available TCP port to avoid conflicts
+ *     with stale OpenCode server processes from previous runs.
+ *   - `trackServer()` / `untrackServer()` — registers the active server's
+ *     `close()` function for automatic cleanup on process exit or signal
+ *     (SIGINT, SIGTERM, SIGHUP, uncaughtException, unhandledRejection),
+ *     preventing zombie child processes.
+ */
+/**
+ * Find a free TCP port on 127.0.0.1.
+ *
+ * Binds a temporary server to port 0 (letting the OS assign an ephemeral
+ * port), reads the assigned port, then closes the server. This avoids
+ * the SDK's default port 4096 which may be held by a stale process.
+ */
+export declare function findFreePort(): Promise<number>;
+/**
+ * Register a server's `close()` function for automatic cleanup on
+ * process exit, signal (SIGINT, SIGTERM, SIGHUP), uncaughtException, or
+ * unhandledRejection.
+ *
+ * Call this immediately after `createOpencode()` resolves.
+ * Replaces any previously tracked server.
+ */
+export declare function trackServer(closeFn: () => void): void;
+/**
+ * Clear the tracked server cleanup function.
+ *
+ * Call this after `server.close()` in a `finally` block to prevent
+ * double-close on normal shutdown.
+ */
+export declare function untrackServer(): void;
+/**
+ * Attempt a `findFreePort` + server-creation sequence with automatic retry
+ * on port-conflict errors (`EADDRINUSE` and similar).
+ *
+ * Calls `factory()` up to `maxAttempts` times. If the factory throws an
+ * error whose message matches a port-conflict pattern, the error is
+ * swallowed and the next attempt proceeds. Non-port-conflict errors
+ * propagate immediately without further retries.
+ *
+ * The factory callback is responsible for calling `findFreePort()` and
+ * passing the result to `createOpencode()` (or equivalent). This keeps
+ * the retry logic decoupled from any specific server-creation API.
+ *
+ * @param factory     - Async callback that discovers a port and creates
+ *                      the server. Called once per attempt.
+ * @param maxAttempts - Maximum number of attempts (default 3).
+ * @returns The value returned by a successful `factory()` call.
+ * @throws The last port-conflict error if all attempts are exhausted,
+ *         or any non-port-conflict error immediately.
+ */
+export declare function startWithRetry<T>(factory: () => Promise<T>, maxAttempts?: number): Promise<T>;

package/dist/server-utils.js

@@ -0,0 +1,135 @@
+/**
+ * Server lifecycle utilities for Hem.
+ *
+ * Provides:
+ *   - `findFreePort()` — discovers an available TCP port to avoid conflicts
+ *     with stale OpenCode server processes from previous runs.
+ *   - `trackServer()` / `untrackServer()` — registers the active server's
+ *     `close()` function for automatic cleanup on process exit or signal
+ *     (SIGINT, SIGTERM, SIGHUP, uncaughtException, unhandledRejection),
+ *     preventing zombie child processes.
+ */
+import { createServer } from "node:net";
+// ── Free port discovery ─────────────────────────────────────────────
+/**
+ * Find a free TCP port on 127.0.0.1.
+ *
+ * Binds a temporary server to port 0 (letting the OS assign an ephemeral
+ * port), reads the assigned port, then closes the server. This avoids
+ * the SDK's default port 4096 which may be held by a stale process.
+ */
+export function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            if (addr === null || typeof addr === "string") {
+                srv.close(() => reject(new Error("Failed to determine port from server address")));
+                return;
+            }
+            const port = addr.port;
+            srv.close(() => resolve(port));
+        });
+        srv.on("error", reject);
+    });
+}
+// ── Server process cleanup ──────────────────────────────────────────
+//
+// Only one OpenCode server is active at a time (the auth server is closed
+// before the generation server starts), so a single `activeCleanup` slot
+// is sufficient.
+let activeCleanup = null;
+let handlersRegistered = false;
+function onExit() {
+    if (activeCleanup) {
+        activeCleanup();
+        activeCleanup = null;
+    }
+}
+function onSignal(signal) {
+    onExit();
+    // Re-raise the signal so the process exits with the correct code.
+    // We must remove our listener first to avoid infinite recursion.
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+}
+function ensureHandlers() {
+    if (handlersRegistered)
+        return;
+    handlersRegistered = true;
+    process.on("exit", onExit);
+    process.on("SIGINT", () => onSignal("SIGINT"));
+    process.on("SIGTERM", () => onSignal("SIGTERM"));
+    process.on("SIGHUP", () => onSignal("SIGHUP"));
+    process.on("uncaughtException", () => {
+        onExit();
+        process.exit(1);
+    });
+    process.on("unhandledRejection", () => {
+        onExit();
+        process.exit(1);
+    });
+}
+/**
+ * Register a server's `close()` function for automatic cleanup on
+ * process exit, signal (SIGINT, SIGTERM, SIGHUP), uncaughtException, or
+ * unhandledRejection.
+ *
+ * Call this immediately after `createOpencode()` resolves.
+ * Replaces any previously tracked server.
+ */
+export function trackServer(closeFn) {
+    ensureHandlers();
+    activeCleanup = closeFn;
+}
+/**
+ * Clear the tracked server cleanup function.
+ *
+ * Call this after `server.close()` in a `finally` block to prevent
+ * double-close on normal shutdown.
+ */
+export function untrackServer() {
+    activeCleanup = null;
+}
+// ── Retry utility for port acquisition ──────────────────────────────
+/** Default number of retry attempts for port acquisition. */
+const DEFAULT_MAX_ATTEMPTS = 3;
+/** Regex to detect port-conflict errors worth retrying. */
+const PORT_CONFLICT_RE = /EADDRINUSE|port.*in use|already.*listening/i;
+/**
+ * Attempt a `findFreePort` + server-creation sequence with automatic retry
+ * on port-conflict errors (`EADDRINUSE` and similar).
+ *
+ * Calls `factory()` up to `maxAttempts` times. If the factory throws an
+ * error whose message matches a port-conflict pattern, the error is
+ * swallowed and the next attempt proceeds. Non-port-conflict errors
+ * propagate immediately without further retries.
+ *
+ * The factory callback is responsible for calling `findFreePort()` and
+ * passing the result to `createOpencode()` (or equivalent). This keeps
+ * the retry logic decoupled from any specific server-creation API.
+ *
+ * @param factory     - Async callback that discovers a port and creates
+ *                      the server. Called once per attempt.
+ * @param maxAttempts - Maximum number of attempts (default 3).
+ * @returns The value returned by a successful `factory()` call.
+ * @throws The last port-conflict error if all attempts are exhausted,
+ *         or any non-port-conflict error immediately.
+ */
+export async function startWithRetry(factory, maxAttempts = DEFAULT_MAX_ATTEMPTS) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await factory();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!PORT_CONFLICT_RE.test(message)) {
+                throw error;
+            }
+            lastError = error;
+            // Port conflict — retry with a fresh port on next iteration
+        }
+    }
+    throw lastError;
+}

package/dist/session.d.ts

@@ -0,0 +1,227 @@
+/**
+ * OpenCode session utilities for Hem.
+ *
+ * Provides the `SessionClient` interface, the centralized `SessionTracker`
+ * for monitoring session completion, the shared `promptAndWait()` helper
+ * for sending prompts, and JSON extraction helpers used by agent classes.
+ *
+ * `promptAndWait()` uses the async prompt flow:
+ *   1. `session.promptAsync()` — fire the prompt without blocking
+ *   2. Register the session with the centralized `SessionTracker`
+ *   3. Wait for the tracker to resolve (session disappears from the
+ *      server's status map, meaning it has completed)
+ *   4. Read `session.messages()` to extract the response
+ *
+ * LLM-specific prompt building and session orchestration have been
+ * extracted into dedicated agent classes under `src/agents/`.
+ */
+/** How often the tracker polls session status (ms). */
+export declare const POLL_INTERVAL_MS = 250;
+/** Hard ceiling timeout — if a session hasn't completed after this long,
+ *  give up and recover from tool history (ms). */
+export declare const MAX_PROMPT_TIMEOUT_MS: number;
+/** Tighter timeout for exploration sessions — they typically finish in 2-3 min.
+ *  Surfaces hangs 25 minutes earlier than the default ceiling. */
+export declare const EXPLORATION_TIMEOUT_MS: number;
+/** Timeout for documentation generation sessions — more complex than
+ *  exploration but still bounded; surfaces hangs 20 minutes earlier. */
+export declare const DOCUMENTATION_TIMEOUT_MS: number;
+/**
+ * Status of an individual session as reported by the OpenCode server.
+ */
+export interface SessionStatus {
+    type: "idle" | "busy" | "retry";
+    /** Present when type is "retry". */
+    attempt?: number;
+    message?: string;
+    next?: number;
+}
+/**
+ * A part from a message response. This is the union of all part types
+ * the SDK may return. We keep it loose to avoid coupling to every SDK
+ * part variant — callers inspect `type` to narrow.
+ */
+export interface MessagePart {
+    type: string;
+    text?: string;
+    /** Present on "patch" parts — lists file paths the edit tool touched. */
+    files?: string[];
+    /** Present on "tool" parts — name of the tool invoked. */
+    tool?: string;
+    /** Present on "tool" parts — tool call state with input/output. */
+    state?: {
+        status?: string;
+        input?: Record<string, unknown>;
+        output?: string;
+    };
+}
+/**
+ * Minimal client interface required by agents.
+ *
+ * Mirrors the subset of `OpencodeClient` used for session creation,
+ * async prompting, status polling, and message retrieval.
+ * Easy to mock in tests without importing the SDK.
+ */
+export interface SessionClient {
+    session: {
+        create(options?: {
+            body?: {
+                title?: string;
+            };
+        }): Promise<{
+            data?: {
+                id: string;
+            };
+            error?: unknown;
+        }>;
+        promptAsync(options: {
+            path: {
+                id: string;
+            };
+            body: {
+                parts: Array<{
+                    type: "text";
+                    text: string;
+                }>;
+                agent?: string;
+            };
+        }): Promise<{
+            data?: void;
+            error?: unknown;
+        }>;
+        status(options?: {
+            query?: {
+                directory?: string;
+            };
+        }): Promise<{
+            data?: Record<string, SessionStatus>;
+            error?: unknown;
+        }>;
+        messages(options: {
+            path: {
+                id: string;
+            };
+        }): Promise<{
+            data?: Array<{
+                info: {
+                    role: string;
+                };
+                parts: Array<MessagePart>;
+            }>;
+            error?: unknown;
+        }>;
+        abort(options: {
+            path: {
+                id: string;
+            };
+        }): Promise<{
+            data?: boolean;
+            error?: unknown;
+        }>;
+        delete(options: {
+            path: {
+                id: string;
+            };
+        }): Promise<{
+            data?: boolean;
+            error?: unknown;
+        }>;
+    };
+    event: {
+        subscribe(options?: {
+            query?: {
+                directory?: string;
+            };
+        }): Promise<{
+            stream: AsyncGenerator<SseEvent, void, unknown>;
+        }>;
+    };
+}
+/**
+ * Minimal SSE event type for broadcast interception.
+ * We only need to match `message.part.updated` and `session.created` events.
+ */
+export interface SseEvent {
+    type: string;
+    properties: Record<string, unknown>;
+}
+/**
+ * Centralized session completion tracker.
+ *
+ * Runs a single poll loop that calls `GET /session/status` once per
+ * interval and resolves individual session promises as they disappear
+ * from the server's status map (meaning they have completed).
+ *
+ * The OpenCode server only reports actively-processing sessions in the
+ * status map — completed sessions are removed entirely. The tracker
+ * exploits this: "present in map" = busy, "absent from map" = done.
+ *
+ * **Subagent awareness**: subscribes to SSE `session.created` events to
+ * detect child sessions spawned by any tracked parent. A parent session
+ * is not resolved as "done" until the parent itself AND all its
+ * descendants have disappeared from the status map.
+ *
+ * The poll loop is lazy: it starts on the first `track()` call and
+ * pauses when the tracked set becomes empty.
+ */
+export interface SessionTracker {
+    /**
+     * Register a session ID to track.
+     *
+     * @param sessionId - The session to monitor.
+     * @param label     - Human-readable label for logging (e.g., group ID).
+     *                    Defaults to truncated session ID.
+     * @returns A promise that resolves to `"done"` when the session completes,
+     *          or `"timeout"` if the per-session deadline is exceeded.
+     */
+    track(sessionId: string, label?: string): Promise<"done" | "timeout">;
+    /** Stop the poll loop, SSE subscription, and clean up. */
+    stop(): void;
+}
+/**
+ * Creates a centralized session tracker with subagent awareness.
+ *
+ * The tracker subscribes to SSE `session.created` events to detect child
+ * sessions spawned by tracked parents. A parent is only resolved as "done"
+ * when both the parent and all its descendants have completed.
+ *
+ * If the SSE subscription fails, the tracker gracefully degrades to the
+ * original poll-only behavior (no child tracking).
+ *
+ * @param client  - The OpenCode SDK client (for `session.status()` and `event.subscribe()`).
+ * @param options - Configuration: verbose logger, poll interval, per-session timeout.
+ * @returns A `SessionTracker` instance.
+ */
+export declare function createSessionTracker(client: SessionClient, options?: {
+    verbose?: (msg: string) => void;
+    pollIntervalMs?: number;
+    maxTimeoutMs?: number;
+}): SessionTracker;
+/**
+ * Sends a prompt to an OpenCode session and returns the complete response.
+ *
+ * Uses the async prompt flow:
+ *   1. `session.promptAsync()` fires the prompt without blocking.
+ *   2. Registers the session with the centralized `SessionTracker` and
+ *      waits for it to complete (disappear from the status map).
+ *   3. Reads `session.messages()` to extract the assistant's response.
+ *   4. If the hard ceiling is hit, recovers file paths from tool history.
+ *
+ * @param client    - The OpenCode SDK client.
+ * @param sessionId - The session to prompt.
+ * @param parts     - The message parts to send.
+ * @param options   - Settings: tracker (required), verbose callback, agent selection.
+ * @returns The response parts from the assistant message.
+ * @throws {AuthExpiredError} If auth expires during the API call.
+ * @throws {Error} If the prompt fails to be accepted.
+ */
+export declare function promptAndWait(client: SessionClient, sessionId: string, parts: Array<{
+    type: "text";
+    text: string;
+}>, options: {
+    verbose?: (msg: string) => void;
+    agent?: string;
+    tracker: SessionTracker;
+    /** Human-readable label for tracker logging. */
+    label?: string;
+}): Promise<Array<MessagePart>>;