@pruddiman/hem 0.0.1-beta-5671db0

package/dist/providers/copilot.js

@@ -0,0 +1,598 @@
+/**
+ * GitHub Copilot provider implementation for Hem.
+ *
+ * Wraps the @github/copilot-sdk CopilotClient behind the {@link Provider}
+ * interface. Provides full feature parity with OpenCodeProvider:
+ *   - MCP server registration (hem-broadcast) per session
+ *   - Per-agent permission profiles (mapped from agent name to Copilot SDK permissions)
+ *   - Broadcast tool interception via `onPreToolUse` hook → normalized SSE events
+ *   - Terminable SSE event stream via central emitter pattern
+ *   - Verbose logging throughout
+ *
+ * Aligns with Dispatch's ProviderInstance pattern:
+ *   - `createSession()` — creates a Copilot session with full MCP + permission config
+ *   - `prompt(sessionId, text, { agent })` — sets agent context, sends prompt, waits for idle
+ *   - `cleanup()` — destroys all sessions, terminates SSE generators, stops the client
+ *
+ * Authentication options (checked in order by the SDK):
+ *   1. COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN env vars
+ *   2. Logged-in Copilot CLI user (default — no token needed)
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// ── Read-only bash command allowlist ────────────────────────────────────
+/**
+ * Base commands allowed in read-only bash mode.
+ * Mirrors the READ_ONLY_BASH config in OpenCodeProvider.
+ */
+const READ_ONLY_CMDS = new Set([
+    "cat", "head", "tail", "grep", "find", "ls",
+    "wc", "file", "tree", "du",
+]);
+/**
+ * Check whether a shell command is read-only (safe to run without write access).
+ * Matches READ_ONLY_BASH from OpenCodeProvider:
+ *   cat/head/tail/grep/find/ls/wc/file/tree/du → allow
+ *   git status / git diff → allow (other git subcommands → deny)
+ *   rm → allow only for ORG agents
+ *   * → deny
+ */
+function isReadOnlyCommand(cmd) {
+    const parts = cmd.trim().split(/\s+/);
+    const base = parts[0] ?? "";
+    if (READ_ONLY_CMDS.has(base))
+        return true;
+    if (base === "git") {
+        const sub = parts[1] ?? "";
+        return sub === "status" || sub === "diff";
+    }
+    return false;
+}
+/** Environment variable names checked for GitHub token, in priority order. */
+const TOKEN_ENV_VARS = ["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"];
+/** Resolve the broadcast MCP server path relative to this compiled module. */
+function resolveBroadcastMcpPath() {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    return join(thisDir, "..", "broadcast-mcp.js");
+}
+// ── Permission helpers ──────────────────────────────────────────────────
+/**
+ * Determine whether an agent name is allowed to perform write (edit) operations.
+ * Mirrors the `edit` field in OpenCodeProvider's per-agent permission profiles.
+ */
+function agentAllowsEdit(agentName) {
+    // Agents that deny edit: hem-explore, hem-group, and any unknown agent (default-deny)
+    return agentName === "hem-doc" ||
+        agentName === "hem-arch" ||
+        agentName === "hem-index" ||
+        agentName === "hem-org" ||
+        agentName === "hem-xref";
+}
+/**
+ * Determine whether a shell command is allowed for the given agent.
+ * Mirrors the `bash` field in OpenCodeProvider's per-agent permission profiles.
+ */
+function agentAllowsShell(agentName, command) {
+    // hem-group uses READ_ONLY_BASH too (bash is explicitly read-only, not "deny")
+    if (isReadOnlyCommand(command))
+        return true;
+    // hem-org additionally allows rm (mirrors ORG_AGENT_BASH)
+    if (agentName === "hem-org" && command.trim().split(/\s+/)[0] === "rm")
+        return true;
+    return false;
+}
+/**
+ * Determine whether an agent is allowed to fetch URLs (webfetch).
+ * Mirrors the `webfetch` field in OpenCodeProvider's per-agent permission profiles.
+ */
+function agentAllowsWebfetch(agentName) {
+    // hem-group denies webfetch; all others allow it
+    return agentName !== "hem-group";
+}
+// ── CopilotProvider ─────────────────────────────────────────────────────
+/**
+ * Provider implementation backed by the GitHub Copilot SDK.
+ *
+ * Provides full feature parity with OpenCodeProvider:
+ *   - MCP server: hem-broadcast registered on every session
+ *   - Per-agent permissions: mapped from agent name via onPermissionRequest
+ *   - Broadcast relay: onPreToolUse hook emits normalized message.part.updated events
+ *   - SSE events: central emitter with terminable generators
+ *   - Verbose logging throughout
+ *
+ * When no token is found in environment variables the SDK uses the
+ * Copilot CLI's own auth state (set up via `gh auth login`).
+ *
+ * @example
+ * ```ts
+ * const provider = await CopilotProvider.create(config);
+ * const sessionId = await provider.createSession();
+ * const result = await provider.prompt(sessionId, "Explain this code", { agent: "hem-doc" });
+ * await provider.cleanup();
+ * ```
+ */
+export class CopilotProvider {
+    _config;
+    _client = null;
+    _stopFn = null;
+    _factory;
+    _sessions = new Map();
+    _sessionMeta = new Map();
+    _modelValue;
+    _modelDetected = false;
+    // ── Central SSE event emitter ──────────────────────────────────────
+    _eventHandlers = new Set();
+    _sseCleanupHandlers = new Set();
+    /** Low-level session operations (implementing Provider interface). */
+    session;
+    /** SSE event subscription (implementing Provider interface). */
+    event;
+    /**
+     * Creates a new Copilot provider.
+     *
+     * @param config  - Provider configuration (model, destination, permissions).
+     * @param factory - Optional client factory override for testing.
+     */
+    constructor(config, factory) {
+        this._config = config;
+        this._factory = factory ?? (async (token) => {
+            const { CopilotClient } = await import("@github/copilot-sdk");
+            const copilot = new CopilotClient(token ? { githubToken: token } : {});
+            await copilot.start();
+            return {
+                client: copilot,
+                stop: async () => { await copilot.stop(); },
+            };
+        });
+        const self = this;
+        this.session = {
+            async promptAsync(options) {
+                // Set agent context before sending so the permission handler is primed
+                const meta = self._sessionMeta.get(options.path.id);
+                if (meta && options.body.agent && !meta.agentContext.name) {
+                    meta.agentContext.name = options.body.agent;
+                }
+                const copilotSession = self._sessions.get(options.path.id);
+                if (!copilotSession)
+                    return { error: "Session not found" };
+                const text = options.body.parts.map((p) => p.text).join("\n");
+                try {
+                    await copilotSession.send({ prompt: text });
+                    return { data: undefined };
+                }
+                catch (error) {
+                    return { error };
+                }
+            },
+            async abort(options) {
+                const copilotSession = self._sessions.get(options.path.id);
+                if (!copilotSession)
+                    return { data: false };
+                try {
+                    await copilotSession.abort();
+                    return { data: true };
+                }
+                catch (error) {
+                    return { error };
+                }
+            },
+            async delete(options) {
+                const copilotSession = self._sessions.get(options.path.id);
+                if (!copilotSession)
+                    return { data: false };
+                try {
+                    await copilotSession.destroy();
+                    if (self._client) {
+                        await self._client.deleteSession(options.path.id);
+                    }
+                    self._sessions.delete(options.path.id);
+                    self._sessionMeta.delete(options.path.id);
+                    return { data: true };
+                }
+                catch (error) {
+                    return { error };
+                }
+            },
+        };
+        this.event = {
+            async subscribe() {
+                if (!self._client) {
+                    throw new Error("CopilotProvider not initialized. Call initialize() first.");
+                }
+                const eventQueue = [];
+                let waiting = null;
+                let stopped = false;
+                const handler = (event) => {
+                    eventQueue.push(event);
+                    waiting?.();
+                    waiting = null;
+                };
+                const cleanupFn = () => {
+                    stopped = true;
+                    self._eventHandlers.delete(handler);
+                    waiting?.();
+                    waiting = null;
+                };
+                self._eventHandlers.add(handler);
+                self._sseCleanupHandlers.add(cleanupFn);
+                const stream = (async function* () {
+                    try {
+                        while (!stopped) {
+                            while (eventQueue.length > 0) {
+                                yield eventQueue.shift();
+                            }
+                            if (stopped)
+                                break;
+                            await new Promise((resolve) => {
+                                waiting = resolve;
+                            });
+                        }
+                    }
+                    finally {
+                        self._sseCleanupHandlers.delete(cleanupFn);
+                        self._eventHandlers.delete(handler);
+                    }
+                })();
+                return { stream };
+            },
+        };
+    }
+    // ── Identity ───────────────────────────────────────────────────────
+    get name() { return "copilot"; }
+    get model() {
+        return this._modelValue ? `github-copilot/${this._modelValue}` : undefined;
+    }
+    get config() { return this._config; }
+    // ── Static factory ─────────────────────────────────────────────────
+    /**
+     * Creates and initializes a CopilotProvider.
+     * Mirrors Dispatch's `boot()` pattern — callers receive a ready-to-use
+     * provider without calling `initialize()` separately.
+     */
+    static async create(config, factory) {
+        const provider = new CopilotProvider(config, factory);
+        await provider.initialize();
+        return provider;
+    }
+    // ── Private helpers ─────────────────────────────────────────────────
+    /** Fan out an SSE event to all active subscribers. */
+    _emit(event) {
+        for (const handler of this._eventHandlers) {
+            handler(event);
+        }
+    }
+    /**
+     * Build a Copilot SDK permission handler that enforces the OpenCode-equivalent
+     * permission profile for the given agent context.
+     *
+     * Defaults to approve-all when `agentContext.name` is not yet set (i.e., before
+     * the first `prompt()` call). In practice, all tool calls arrive after the
+     * prompt, so the agent name is always set before any permission request.
+     */
+    _buildPermissionHandler(agentContext) {
+        return (request) => {
+            const agent = agentContext.name;
+            // No agent context yet — default to approve-all.
+            if (!agent) {
+                return { kind: "approved" };
+            }
+            switch (request.kind) {
+                case "write":
+                    return agentAllowsEdit(agent)
+                        ? { kind: "approved" }
+                        : { kind: "denied-by-rules" };
+                case "shell": {
+                    const cmd = request.command ?? "";
+                    return agentAllowsShell(agent, cmd)
+                        ? { kind: "approved" }
+                        : { kind: "denied-by-rules" };
+                }
+                case "url":
+                    return agentAllowsWebfetch(agent)
+                        ? { kind: "approved" }
+                        : { kind: "denied-by-rules" };
+                case "mcp":
+                case "read":
+                case "custom-tool":
+                    // Always allow MCP (broadcast), read-only access, and custom tools.
+                    return { kind: "approved" };
+                default:
+                    return { kind: "denied-by-rules" };
+            }
+        };
+    }
+    /**
+     * Build the full session config for a new Copilot session.
+     *
+     * Includes:
+     *   - MCP server: hem-broadcast (mirrors OpenCodeProvider's MCP config)
+     *   - onPermissionRequest: agent-aware permission handler
+     *   - hooks.onPreToolUse: intercepts broadcast tool calls → emits normalized SSE
+     *   - workingDirectory: scoped to destination path
+     */
+    _buildSessionConfig(agentContext) {
+        const broadcastMcpPath = resolveBroadcastMcpPath();
+        const modelId = this._config.model.modelID !== "default"
+            ? this._config.model.modelID
+            : undefined;
+        return {
+            ...(modelId ? { model: modelId } : {}),
+            workingDirectory: this._config.destinationPath,
+            mcpServers: {
+                "hem-broadcast": {
+                    type: "local",
+                    command: "node",
+                    args: [broadcastMcpPath],
+                    tools: ["*"],
+                },
+            },
+            onPermissionRequest: this._buildPermissionHandler(agentContext),
+            hooks: {
+                onPreToolUse: async ({ toolName, toolArgs }, { sessionId }) => {
+                    // Intercept broadcast tool calls and emit a normalized SSE event.
+                    // Mirrors OpenCode's message.part.updated SSE event for broadcast detection
+                    // in OrganizationAgent and CrossRefAgent.
+                    // NOTE: Copilot CLI passes plain MCP tool names (e.g. "broadcast"), not the
+                    // "{server}_{tool}" format OpenCode uses in SSE events.
+                    if (toolName === "broadcast") {
+                        const message = toolArgs?.message;
+                        if (message) {
+                            this._emit({
+                                type: "message.part.updated",
+                                properties: {
+                                    part: {
+                                        type: "tool",
+                                        sessionID: sessionId,
+                                        tool: "hem-broadcast_broadcast",
+                                        state: { status: "running", input: { message } },
+                                    },
+                                },
+                            });
+                        }
+                    }
+                },
+            },
+        };
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    /**
+     * Starts the Copilot client.
+     *
+     * Checks `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, and `GITHUB_TOKEN` environment
+     * variables and passes the token to the SDK when found. When no token is
+     * present the SDK uses the Copilot CLI's own auth state.
+     *
+     * Registers the client-level `session.created` listener once (used by agents
+     * that monitor child session creation via the SSE event stream).
+     *
+     * Idempotent — subsequent calls are no-ops if already initialized.
+     *
+     * @throws {Error} If the Copilot client fails to start.
+     */
+    async initialize() {
+        if (this._client)
+            return;
+        const token = CopilotProvider._findToken();
+        if (this._config.verbose) {
+            this._config.verbose(`[copilot] Starting client${token ? ` (token from ${CopilotProvider._findTokenSource()})` : " (CLI auth)"}`);
+        }
+        try {
+            const { client, stop } = await this._factory(token);
+            this._client = client;
+            this._stopFn = stop;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to start Copilot client: ${message}\n` +
+                `  Ensure the Copilot CLI is installed and authenticated.\n` +
+                `  Run \`gh auth login\` or set the COPILOT_GITHUB_TOKEN environment variable.\n` +
+                `  Run with --verbose for detailed logs.`);
+        }
+        // Register client-level session.created listener once.
+        // Agents (OrganizationAgent, CrossRefAgent) use this to track child sessions.
+        this._client.on("session.created", (...args) => {
+            const event = args[0];
+            if (event?.sessionId) {
+                this._emit({
+                    type: "session.created",
+                    properties: {
+                        session: { id: event.sessionId, parentID: undefined },
+                    },
+                });
+            }
+        });
+        if (this._config.verbose) {
+            this._config.verbose("[copilot] Client started");
+        }
+    }
+    // ── Provider interface methods ─────────────────────────────────────
+    /**
+     * Create a new Copilot session with MCP server and permission configuration.
+     *
+     * Each session is created with:
+     *   - hem-broadcast MCP server (matches OpenCodeProvider's MCP config)
+     *   - A permission handler that enforces agent-specific rules once the agent
+     *     name is set via `prompt()` or `session.promptAsync()`
+     *   - An `onPreToolUse` hook for broadcast interception
+     *   - SSE event listeners for session.idle and session.error
+     *
+     * @returns The session ID.
+     * @throws {Error} If the provider is not initialized.
+     */
+    async createSession() {
+        if (!this._client) {
+            throw new Error("CopilotProvider not initialized. Call initialize() first.");
+        }
+        const agentContext = { name: undefined };
+        const copilotSession = await this._client.createSession(this._buildSessionConfig(agentContext));
+        const sid = copilotSession.sessionId;
+        this._sessions.set(sid, copilotSession);
+        this._sessionMeta.set(sid, { agentContext });
+        // Detect the actual default model from the first session (best-effort).
+        if (!this._modelDetected) {
+            this._modelDetected = true;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const result = await copilotSession.rpc?.model.getCurrent();
+                if (result?.modelId) {
+                    this._modelValue = result.modelId;
+                }
+            }
+            catch {
+                // Best-effort — not fatal if model detection fails.
+            }
+        }
+        // Emit session lifecycle events into the central SSE stream so agents
+        // that monitor the event stream (via event.subscribe()) can track completion.
+        copilotSession.on("session.idle", () => {
+            this._emit({
+                type: "session.idle",
+                properties: { sessionID: sid },
+            });
+        });
+        copilotSession.on("session.error", (...args) => {
+            const err = args[0];
+            this._emit({
+                type: "session.error",
+                properties: {
+                    sessionID: sid,
+                    error: err?.data?.message ?? "unknown error",
+                },
+            });
+        });
+        if (this._config.verbose) {
+            const modelHint = this._config.model.modelID !== "default"
+                ? ` (model: ${this._config.model.modelID})`
+                : "";
+            this._config.verbose(`[copilot] Session created: ${sid}${modelHint}`);
+        }
+        return sid;
+    }
+    /**
+     * Send a prompt to a Copilot session and wait for the response.
+     *
+     * Sets the agent context from `options.agent` so the permission handler
+     * enforces the correct per-agent policy for all subsequent tool calls.
+     *
+     * Flow:
+     *   1. Set agent context (for permission enforcement)
+     *   2. `session.send()` — fires the prompt
+     *   3. Wait for `session.idle` or `session.error` event
+     *   4. `session.getMessages()` — fetch the completed response
+     *   5. Return the last `assistant.message` content, or null
+     *
+     * @param sessionId - The session ID returned by `createSession()`.
+     * @param text      - The prompt text.
+     * @param options   - Optional: `agent` sets the permission profile for this session.
+     */
+    async prompt(sessionId, text, options) {
+        const copilotSession = this._sessions.get(sessionId);
+        if (!copilotSession) {
+            throw new Error(`Copilot session ${sessionId} not found`);
+        }
+        // Set agent context so the permission handler knows which policy to apply.
+        const meta = this._sessionMeta.get(sessionId);
+        if (meta && options?.agent && !meta.agentContext.name) {
+            meta.agentContext.name = options.agent;
+        }
+        if (this._config.verbose) {
+            this._config.verbose(`[copilot] Prompt → ${sessionId.slice(0, 8)}…` +
+                (options?.agent ? ` (agent: ${options.agent})` : "") +
+                ` [${text.length.toLocaleString()} chars]`);
+        }
+        // 1. Fire the prompt
+        await copilotSession.send({ prompt: text });
+        // 2. Wait for completion
+        await new Promise((resolve, reject) => {
+            const unsubIdle = copilotSession.on("session.idle", () => {
+                unsubIdle();
+                unsubErr();
+                resolve();
+            });
+            const unsubErr = copilotSession.on("session.error", (...args) => {
+                unsubIdle();
+                unsubErr();
+                const event = args[0];
+                const msg = event?.data?.message ?? "unknown error";
+                reject(new Error(`Copilot session error: ${msg}`));
+            });
+        });
+        if (this._config.verbose) {
+            this._config.verbose(`[copilot] Session idle: ${sessionId.slice(0, 8)}…`);
+        }
+        // 3. Fetch messages and return the last assistant text
+        const events = (await copilotSession.getMessages());
+        const last = [...events]
+            .reverse()
+            .find((e) => e.type === "assistant.message");
+        return last?.data?.content ?? null;
+    }
+    /**
+     * Shuts down the Copilot client and releases all resources.
+     *
+     * 1. Terminates all active SSE generators (unblocks pending iterators).
+     * 2. Destroys all active sessions.
+     * 3. Stops the Copilot client.
+     *
+     * After cleanup, the provider instance must not be reused.
+     * No-op if the provider was never initialized or already shut down.
+     */
+    async cleanup() {
+        // 1. Terminate all active SSE generators so subscribers don't hang.
+        for (const cleanupFn of this._sseCleanupHandlers) {
+            cleanupFn();
+        }
+        this._sseCleanupHandlers.clear();
+        if (this._config.verbose && this._sessions.size > 0) {
+            this._config.verbose(`[copilot] Cleaning up ${this._sessions.size} session(s)`);
+        }
+        // 2. Destroy all active sessions.
+        const destroyOps = [...this._sessions.values()].map((s) => s.destroy().catch(() => { }));
+        await Promise.all(destroyOps);
+        this._sessions.clear();
+        this._sessionMeta.clear();
+        // 3. Stop the client.
+        if (this._stopFn) {
+            await this._stopFn();
+            this._client = null;
+            this._stopFn = null;
+        }
+        if (this._config.verbose) {
+            this._config.verbose("[copilot] Client stopped");
+        }
+    }
+    /**
+     * Alias for `cleanup()` — kept for backward compatibility with callers
+     * that use the old `shutdown()` name.
+     */
+    async shutdown() {
+        return this.cleanup();
+    }
+    /**
+     * Discovers a GitHub token from well-known environment variables.
+     *
+     * Returns `undefined` when no token is set — the SDK will then use the
+     * Copilot CLI's own auth state instead.
+     *
+     * @internal
+     */
+    static _findToken() {
+        for (const envVar of TOKEN_ENV_VARS) {
+            const value = process.env[envVar];
+            if (value)
+                return value;
+        }
+        return undefined;
+    }
+    /**
+     * Returns the name of the env var that provided the token, for logging.
+     * @internal
+     */
+    static _findTokenSource() {
+        for (const envVar of TOKEN_ENV_VARS) {
+            if (process.env[envVar])
+                return envVar;
+        }
+        return "unknown";
+    }
+}

package/dist/providers/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Provider abstraction barrel export for Hem.
+ *
+ * Re-exports the {@link Provider} interface, {@link ProviderConfig},
+ * the provider implementations, and permission constants so consumers
+ * can import everything from `providers/` in a single statement.
+ *
+ * Note: SessionClient, SessionTracker, CopilotSessionAdapter are no longer
+ * exported — they are internal implementation details of the providers.
+ */
+export type { Provider, ProviderConfig, SseEvent, } from "./types.js";
+export { OpenCodeProvider, READ_ONLY_BASH, ORG_AGENT_BASH } from "./opencode.js";
+export type { CreateOpencodeFn } from "./opencode.js";
+export { CopilotProvider } from "./copilot.js";
+export type { CreateCopilotClientFn, CopilotClientLike, CopilotSessionLike, } from "./copilot.js";

package/dist/providers/index.js

@@ -0,0 +1,12 @@
+/**
+ * Provider abstraction barrel export for Hem.
+ *
+ * Re-exports the {@link Provider} interface, {@link ProviderConfig},
+ * the provider implementations, and permission constants so consumers
+ * can import everything from `providers/` in a single statement.
+ *
+ * Note: SessionClient, SessionTracker, CopilotSessionAdapter are no longer
+ * exported — they are internal implementation details of the providers.
+ */
+export { OpenCodeProvider, READ_ONLY_BASH, ORG_AGENT_BASH } from "./opencode.js";
+export { CopilotProvider } from "./copilot.js";