@pruddiman/hem 0.0.1-beta-5671db0

package/dist/providers/opencode.d.ts

@@ -0,0 +1,156 @@
+/**
+ * OpenCode SDK provider implementation for Hem.
+ *
+ * Wraps the OpenCode server lifecycle, permission configuration,
+ * MCP tool registration, and model string formatting behind the
+ * {@link Provider} interface.
+ *
+ * Aligns with Dispatch's ProviderInstance pattern:
+ *   - `createSession()` — delegates to `client.session.create()`
+ *   - `prompt(sessionId, text)` — uses `promptAsync` + SSE wait (avoids
+ *     HTTP timeout on slow LLM responses)
+ *   - `cleanup()` — stops the server
+ *
+ * Also exposes low-level `session` and `event` properties that delegate
+ * directly to the underlying OpenCode client, for agents that need
+ * fire-and-forget prompting or SSE monitoring (OrganizationAgent etc.).
+ *
+ * Reference: FR-005, FR-006, FR-007.
+ */
+import { createOpencode } from "@opencode-ai/sdk";
+import type { Provider, ProviderConfig } from "./types.js";
+/**
+ * Read-only bash permission set for agents that need filesystem inspection
+ * but must never modify files or run arbitrary commands.
+ *
+ * Reference: T005.
+ */
+export declare const READ_ONLY_BASH: {
+    readonly "cat *": "allow";
+    readonly "head *": "allow";
+    readonly "tail *": "allow";
+    readonly "grep *": "allow";
+    readonly "find *": "allow";
+    readonly "ls *": "allow";
+    readonly "wc *": "allow";
+    readonly "file *": "allow";
+    readonly "tree *": "allow";
+    readonly "du *": "allow";
+    readonly "git status *": "allow";
+    readonly "git diff *": "allow";
+    readonly "*": "deny";
+};
+/**
+ * Extended bash permission set for organization workers. Inherits all
+ * read-only commands from {@link READ_ONLY_BASH} and additionally allows
+ * `rm` so workers can delete files when executing arbiter DELETE decisions
+ * instead of writing empty content as a deletion proxy.
+ */
+export declare const ORG_AGENT_BASH: {
+    readonly "rm *": "allow";
+    readonly "cat *": "allow";
+    readonly "head *": "allow";
+    readonly "tail *": "allow";
+    readonly "grep *": "allow";
+    readonly "find *": "allow";
+    readonly "ls *": "allow";
+    readonly "wc *": "allow";
+    readonly "file *": "allow";
+    readonly "tree *": "allow";
+    readonly "du *": "allow";
+    readonly "git status *": "allow";
+    readonly "git diff *": "allow";
+    readonly "*": "deny";
+};
+/** Overridable factory for `createOpencode`, used for testing. */
+export type CreateOpencodeFn = typeof createOpencode;
+/**
+ * Provider implementation backed by the OpenCode SDK.
+ *
+ * Manages the full OpenCode server lifecycle: port discovery, server
+ * startup (with retry), permission scoping, MCP tool registration,
+ * and clean shutdown.
+ *
+ * @example
+ * ```ts
+ * const provider = await OpenCodeProvider.create(config);
+ * const sessionId = await provider.createSession();
+ * const result = await provider.prompt(sessionId, "Explain this code");
+ * await provider.cleanup();
+ * ```
+ */
+export declare class OpenCodeProvider implements Provider {
+    private _config;
+    private _client;
+    private _shutdownFn;
+    private _factory;
+    private _findPort;
+    private _modelOverride;
+    /** Low-level session operations (implementing Provider interface). */
+    readonly session: Provider["session"];
+    /** SSE event subscription (implementing Provider interface). */
+    readonly event: Provider["event"];
+    /**
+     * Creates a new OpenCode provider.
+     *
+     * @param config   - Provider configuration (model, destination, permissions).
+     * @param factory  - Optional `createOpencode` override for testing.
+     * @param findPort - Optional port finder override for testing.
+     */
+    constructor(config: ProviderConfig, factory?: CreateOpencodeFn, findPort?: () => Promise<number>);
+    get name(): string;
+    get model(): string | undefined;
+    get config(): ProviderConfig;
+    /**
+     * Creates and initializes an OpenCodeProvider.
+     * Mirrors Dispatch's `boot()` pattern — callers receive a ready-to-use
+     * provider without calling `initialize()` separately.
+     */
+    static create(config: ProviderConfig, factory?: CreateOpencodeFn, findPort?: () => Promise<number>): Promise<OpenCodeProvider>;
+    /**
+     * Starts the OpenCode server and configures permissions and MCP tools.
+     *
+     * Must be called exactly once before using the provider. Subsequent
+     * calls are no-ops if already initialized.
+     *
+     * @throws {Error} If `destinationPath` is empty or blank.
+     * @throws {Error} If the OpenCode server fails to start.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create a new OpenCode session.
+     *
+     * @returns The session ID.
+     * @throws {Error} If the provider is not initialized.
+     */
+    createSession(): Promise<string>;
+    /**
+     * Send a prompt to an OpenCode session and wait for the response.
+     *
+     * Uses the async prompt flow to avoid HTTP timeout issues on slow LLM
+     * responses (mirrors Dispatch's OpenCode provider):
+     *   1. `promptAsync()` — fire-and-forget POST that returns 204 immediately
+     *   2. `event.subscribe()` — SSE stream for session lifecycle events
+     *   3. Wait for `session.idle` (success) or `session.error` (failure)
+     *   4. `session.messages()` — fetch the completed response
+     *
+     * @param sessionId - The session ID returned by `createSession()`.
+     * @param text      - The prompt text.
+     * @param options   - Optional: `agent` selects the permission profile.
+     */
+    prompt(sessionId: string, text: string, options?: {
+        agent?: string;
+    }): Promise<string | null>;
+    /**
+     * Shuts down the OpenCode server and releases all resources.
+     *
+     * After cleanup, the provider instance must not be reused.
+     * No-op if the provider was never initialized or already shut down.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Alias for `cleanup()` — kept for backward compatibility with callers
+     * that use the old `shutdown()` name.
+     */
+    shutdown(): Promise<void>;
+}

package/dist/providers/opencode.js

@@ -0,0 +1,416 @@
+/**
+ * OpenCode SDK provider implementation for Hem.
+ *
+ * Wraps the OpenCode server lifecycle, permission configuration,
+ * MCP tool registration, and model string formatting behind the
+ * {@link Provider} interface.
+ *
+ * Aligns with Dispatch's ProviderInstance pattern:
+ *   - `createSession()` — delegates to `client.session.create()`
+ *   - `prompt(sessionId, text)` — uses `promptAsync` + SSE wait (avoids
+ *     HTTP timeout on slow LLM responses)
+ *   - `cleanup()` — stops the server
+ *
+ * Also exposes low-level `session` and `event` properties that delegate
+ * directly to the underlying OpenCode client, for agents that need
+ * fire-and-forget prompting or SSE monitoring (OrganizationAgent etc.).
+ *
+ * Reference: FR-005, FR-006, FR-007.
+ */
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createOpencode } from "@opencode-ai/sdk";
+import { findFreePort, trackServer, untrackServer, startWithRetry } from "../server-utils.js";
+// ── Permission Constants ────────────────────────────────────────────────
+/**
+ * Read-only bash permission set for agents that need filesystem inspection
+ * but must never modify files or run arbitrary commands.
+ *
+ * Reference: T005.
+ */
+export const READ_ONLY_BASH = {
+    "cat *": "allow",
+    "head *": "allow",
+    "tail *": "allow",
+    "grep *": "allow",
+    "find *": "allow",
+    "ls *": "allow",
+    "wc *": "allow",
+    "file *": "allow",
+    "tree *": "allow",
+    "du *": "allow",
+    "git status *": "allow",
+    "git diff *": "allow",
+    "*": "deny",
+};
+/**
+ * Extended bash permission set for organization workers. Inherits all
+ * read-only commands from {@link READ_ONLY_BASH} and additionally allows
+ * `rm` so workers can delete files when executing arbiter DELETE decisions
+ * instead of writing empty content as a deletion proxy.
+ */
+export const ORG_AGENT_BASH = {
+    ...READ_ONLY_BASH,
+    "rm *": "allow",
+};
+// ── OpenCode Provider ───────────────────────────────────────────────────
+/**
+ * Provider implementation backed by the OpenCode SDK.
+ *
+ * Manages the full OpenCode server lifecycle: port discovery, server
+ * startup (with retry), permission scoping, MCP tool registration,
+ * and clean shutdown.
+ *
+ * @example
+ * ```ts
+ * const provider = await OpenCodeProvider.create(config);
+ * const sessionId = await provider.createSession();
+ * const result = await provider.prompt(sessionId, "Explain this code");
+ * await provider.cleanup();
+ * ```
+ */
+export class OpenCodeProvider {
+    _config;
+    _client = null;
+    _shutdownFn = null;
+    _factory;
+    _findPort;
+    _modelOverride;
+    /** Low-level session operations (implementing Provider interface). */
+    session;
+    /** SSE event subscription (implementing Provider interface). */
+    event;
+    /**
+     * Creates a new OpenCode provider.
+     *
+     * @param config   - Provider configuration (model, destination, permissions).
+     * @param factory  - Optional `createOpencode` override for testing.
+     * @param findPort - Optional port finder override for testing.
+     */
+    constructor(config, factory = createOpencode, findPort = findFreePort) {
+        this._config = config;
+        this._factory = factory;
+        this._findPort = findPort;
+        // Parse model override from config for use in prompt() calls.
+        // The SDK concatenates providerID + "/" + modelID, so for encoded modelIDs like
+        // "github-copilot/claude-opus-4.6" (opencode sub-provider), split them so the
+        // SDK receives { providerID: "github-copilot", modelID: "claude-opus-4.6" }.
+        if (config.model.modelID !== "default") {
+            const { providerID, modelID } = config.model;
+            if (modelID.includes("/")) {
+                const slashIdx = modelID.indexOf("/");
+                this._modelOverride = {
+                    providerID: modelID.slice(0, slashIdx),
+                    modelID: modelID.slice(slashIdx + 1),
+                };
+            }
+            else {
+                this._modelOverride = { providerID, modelID };
+            }
+        }
+        // Low-level session ops — delegate to underlying client
+        const self = this;
+        this.session = {
+            async promptAsync(options) {
+                if (!self._client)
+                    throw new Error("OpenCodeProvider not initialized");
+                return self._client.session.promptAsync(options);
+            },
+            async abort(options) {
+                if (!self._client)
+                    throw new Error("OpenCodeProvider not initialized");
+                return self._client.session.abort(options);
+            },
+            async delete(options) {
+                if (!self._client)
+                    throw new Error("OpenCodeProvider not initialized");
+                return self._client.session.delete(options);
+            },
+        };
+        this.event = {
+            async subscribe(options) {
+                if (!self._client)
+                    throw new Error("OpenCodeProvider not initialized");
+                // The underlying SDK returns SdkEvent; cast to SseEvent (same shape).
+                const result = await self._client.event.subscribe(options);
+                return result;
+            },
+        };
+    }
+    // ── Identity ───────────────────────────────────────────────────────
+    get name() { return "opencode"; }
+    get model() {
+        if (this._config.model.modelID === "default")
+            return undefined;
+        const { providerID, modelID } = this._config.model;
+        // modelID may already include a sub-provider prefix (e.g. "github-copilot/opus-4.6")
+        // when the user picked an opencode sub-provider model via `hem config`. Use it as-is.
+        return modelID.includes("/") ? modelID : `${providerID}/${modelID}`;
+    }
+    get config() { return this._config; }
+    // ── Static factory ─────────────────────────────────────────────────
+    /**
+     * Creates and initializes an OpenCodeProvider.
+     * Mirrors Dispatch's `boot()` pattern — callers receive a ready-to-use
+     * provider without calling `initialize()` separately.
+     */
+    static async create(config, factory, findPort) {
+        const provider = new OpenCodeProvider(config, factory, findPort);
+        await provider.initialize();
+        return provider;
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    /**
+     * Starts the OpenCode server and configures permissions and MCP tools.
+     *
+     * Must be called exactly once before using the provider. Subsequent
+     * calls are no-ops if already initialized.
+     *
+     * @throws {Error} If `destinationPath` is empty or blank.
+     * @throws {Error} If the OpenCode server fails to start.
+     */
+    async initialize() {
+        if (this._client)
+            return;
+        const absoluteDestination = resolve(this._config.destinationPath);
+        if (absoluteDestination.trim() === "") {
+            throw new Error("destinationPath must be a non-empty string. " +
+                "Provide a valid directory path for generated documentation.");
+        }
+        const { providerID, modelID } = this._config.model;
+        const modelString = modelID === "default"
+            ? undefined
+            // modelID may already include a sub-provider prefix (e.g. "github-copilot/opus-4.6")
+            // when the user picked an opencode sub-provider model via `hem config`. Use it as-is.
+            : modelID.includes("/") ? modelID : `${providerID}/${modelID}`;
+        // Writing agents get scoped access to the destination directory.
+        const writingAgentPermission = {
+            edit: "allow",
+            bash: READ_ONLY_BASH,
+            webfetch: "allow",
+            external_directory: "allow",
+        };
+        // Organization workers additionally need `rm` to execute arbiter DELETE
+        // decisions (instead of writing empty content as a deletion proxy).
+        const orgAgentPermission = {
+            edit: "allow",
+            bash: ORG_AGENT_BASH,
+            webfetch: "allow",
+            external_directory: "allow",
+        };
+        // Resolve the path to the compiled broadcast MCP server script.
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        const broadcastMcpPath = join(thisDir, "..", "broadcast-mcp.js");
+        const searchMcpPath = join(thisDir, "..", "search-mcp.js");
+        const searchDbPath = this._config.searchDbPath;
+        try {
+            const { client, server } = await startWithRetry(async () => {
+                const port = await this._findPort();
+                return this._factory({
+                    port,
+                    config: {
+                        ...(modelString != null && { model: modelString }),
+                        mcp: {
+                            "hem-broadcast": {
+                                type: "local",
+                                command: ["node", broadcastMcpPath],
+                                enabled: true,
+                            },
+                            ...(searchDbPath && {
+                                "hem-search": {
+                                    type: "local",
+                                    command: ["node", searchMcpPath, searchDbPath],
+                                    enabled: true,
+                                },
+                            }),
+                        },
+                        permission: {
+                            edit: "deny",
+                            bash: "deny",
+                            webfetch: "deny",
+                        },
+                        agent: {
+                            "hem-explore": {
+                                permission: {
+                                    edit: "deny",
+                                    bash: READ_ONLY_BASH,
+                                    webfetch: "allow",
+                                },
+                            },
+                            "hem-doc": {
+                                permission: writingAgentPermission,
+                            },
+                            "hem-arch": {
+                                permission: writingAgentPermission,
+                            },
+                            "hem-index": {
+                                permission: writingAgentPermission,
+                            },
+                            "hem-org": {
+                                permission: orgAgentPermission,
+                            },
+                            "hem-xref": {
+                                permission: writingAgentPermission,
+                            },
+                            "hem-group": {
+                                permission: {
+                                    edit: "deny",
+                                    bash: READ_ONLY_BASH,
+                                    webfetch: "deny",
+                                },
+                            },
+                        },
+                    },
+                });
+            });
+            trackServer(() => server.close());
+            this._client = client;
+            this._shutdownFn = async () => {
+                server.close();
+                untrackServer();
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const isPortConflict = /EADDRINUSE|port.*in use|already.*listening/i.test(message);
+            const hint = isPortConflict
+                ? `  A process is already using this port. Kill stale OpenCode processes or restart your terminal.\n`
+                : `  This may be a Node.js version issue (requires 20+) or a network problem.\n`;
+            throw new Error(`Failed to start OpenCode server: ${message}\n` +
+                hint +
+                `  Run with --verbose for detailed logs.`);
+        }
+    }
+    // ── Provider interface methods ─────────────────────────────────────
+    /**
+     * Create a new OpenCode session.
+     *
+     * @returns The session ID.
+     * @throws {Error} If the provider is not initialized.
+     */
+    async createSession() {
+        if (!this._client) {
+            throw new Error("OpenCodeProvider not initialized. Call initialize() first.");
+        }
+        const { data: session, error } = await this._client.session.create();
+        if (error || !session) {
+            throw new Error(`Failed to create OpenCode session: ${String(error ?? "unknown error")}`);
+        }
+        return session.id;
+    }
+    /**
+     * Send a prompt to an OpenCode session and wait for the response.
+     *
+     * Uses the async prompt flow to avoid HTTP timeout issues on slow LLM
+     * responses (mirrors Dispatch's OpenCode provider):
+     *   1. `promptAsync()` — fire-and-forget POST that returns 204 immediately
+     *   2. `event.subscribe()` — SSE stream for session lifecycle events
+     *   3. Wait for `session.idle` (success) or `session.error` (failure)
+     *   4. `session.messages()` — fetch the completed response
+     *
+     * @param sessionId - The session ID returned by `createSession()`.
+     * @param text      - The prompt text.
+     * @param options   - Optional: `agent` selects the permission profile.
+     */
+    async prompt(sessionId, text, options) {
+        if (!this._client) {
+            throw new Error("OpenCodeProvider not initialized. Call initialize() first.");
+        }
+        // 1. Fire-and-forget prompt
+        const { error: promptError } = await this._client.session.promptAsync({
+            path: { id: sessionId },
+            body: {
+                parts: [{ type: "text", text }],
+                agent: options?.agent,
+                ...(this._modelOverride ? { model: this._modelOverride } : {}),
+            },
+        });
+        if (promptError) {
+            throw new Error(`OpenCode promptAsync failed: ${JSON.stringify(promptError)}`);
+        }
+        // 2. Subscribe to SSE events
+        const controller = new AbortController();
+        const { stream } = await this._client.event.subscribe({
+            signal: controller.signal,
+        });
+        // 3. Wait for session.idle or session.error
+        try {
+            for await (const event of stream) {
+                if (!isSessionEvent(event, sessionId))
+                    continue;
+                if (event.type === "session.error") {
+                    const err = event.properties?.error;
+                    throw new Error(`OpenCode session error: ${err ? JSON.stringify(err) : "unknown error"}`);
+                }
+                if (event.type === "session.idle") {
+                    break;
+                }
+            }
+        }
+        finally {
+            controller.abort();
+        }
+        // 4. Fetch completed messages
+        const { data: messages } = await this._client.session.messages({
+            path: { id: sessionId },
+        });
+        if (!messages || messages.length === 0)
+            return null;
+        const lastAssistant = [...messages]
+            .reverse()
+            .find((m) => m.info.role === "assistant");
+        if (!lastAssistant)
+            return null;
+        // Check for assistant-level error
+        if (lastAssistant.info.error) {
+            throw new Error(`OpenCode assistant error: ${JSON.stringify(lastAssistant.info.error)}`);
+        }
+        // Extract text parts
+        const textParts = lastAssistant.parts.filter((p) => p.type === "text" && "text" in p);
+        return textParts.map((p) => p.text).join("\n") || null;
+    }
+    /**
+     * Shuts down the OpenCode server and releases all resources.
+     *
+     * After cleanup, the provider instance must not be reused.
+     * No-op if the provider was never initialized or already shut down.
+     */
+    async cleanup() {
+        if (this._shutdownFn) {
+            await this._shutdownFn();
+            this._client = null;
+            this._shutdownFn = null;
+        }
+    }
+    /**
+     * Alias for `cleanup()` — kept for backward compatibility with callers
+     * that use the old `shutdown()` name.
+     */
+    async shutdown() {
+        return this.cleanup();
+    }
+}
+// ── SSE event filter ────────────────────────────────────────────────────
+/**
+ * Check whether an SSE event belongs to the given session.
+ *
+ * Different event types store the session ID in different places:
+ *   - `session.*` events → `properties.sessionID`
+ *   - `message.*` events → `properties.info.sessionID` or `properties.part.sessionID`
+ */
+function isSessionEvent(event, sessionId) {
+    const props = event.properties;
+    if (props.sessionID === sessionId)
+        return true;
+    if (props.info &&
+        typeof props.info === "object" &&
+        props.info.sessionID === sessionId) {
+        return true;
+    }
+    if (props.part &&
+        typeof props.part === "object" &&
+        props.part.sessionID === sessionId) {
+        return true;
+    }
+    return false;
+}