@pruddiman/hem 0.0.1-beta-5671db0

package/dist/providers/copilot.d.ts

@@ -0,0 +1,247 @@
+/**
+ * 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 type { Provider, ProviderConfig } from "./types.js";
+/** Permission request kind from the Copilot SDK. */
+type PermissionKind = "shell" | "write" | "mcp" | "read" | "url" | "custom-tool";
+/** Minimal permission request shape. */
+interface PermissionRequest {
+    kind: PermissionKind;
+    command?: string;
+    [key: string]: unknown;
+}
+/** Minimal permission result returned to the SDK. */
+interface PermissionResult {
+    kind: "approved" | "denied-by-rules";
+}
+/**
+ * Minimal interface for a Copilot session, matching the subset of
+ * `CopilotSession` from `@github/copilot-sdk` used by the provider.
+ */
+export interface CopilotSessionLike {
+    sessionId: string;
+    send(options: {
+        prompt: string;
+    }): Promise<string>;
+    abort(): Promise<void>;
+    destroy(): Promise<void>;
+    getMessages(): Promise<Array<{
+        type: string;
+        data?: {
+            content?: string;
+        };
+    }>>;
+    on(eventType: string, handler: (...args: unknown[]) => void): () => void;
+}
+/**
+ * Minimal interface for a Copilot client, matching the subset of
+ * `CopilotClient` from `@github/copilot-sdk` used by the provider.
+ */
+export interface CopilotClientLike {
+    createSession(config?: {
+        model?: string;
+        workingDirectory?: string;
+        onPermissionRequest?: (request: PermissionRequest, ctx: {
+            sessionId: string;
+        }) => PermissionResult | Promise<PermissionResult>;
+        mcpServers?: Record<string, {
+            type?: string;
+            command?: string;
+            args?: string[];
+            tools?: string[];
+        }>;
+        hooks?: {
+            onPreToolUse?: (input: {
+                toolName: string;
+                toolArgs: unknown;
+            }, ctx: {
+                sessionId: string;
+            }) => Promise<{
+                permissionDecision?: string;
+            } | void> | void;
+        };
+    }): Promise<CopilotSessionLike>;
+    deleteSession(sessionId: string): Promise<void>;
+    on(eventType: string, handler: (...args: unknown[]) => void): () => void;
+}
+/**
+ * Factory function type for creating a CopilotClient instance.
+ * Accepts an optional GitHub token (used when an env-var token is found).
+ * Returns an object with a client and stop method.
+ * Overridable in tests.
+ */
+export type CreateCopilotClientFn = (token?: string) => Promise<{
+    client: CopilotClientLike;
+    stop: () => Promise<void>;
+}>;
+/**
+ * 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 declare class CopilotProvider implements Provider {
+    private _config;
+    private _client;
+    private _stopFn;
+    private _factory;
+    private _sessions;
+    private _sessionMeta;
+    private _modelValue;
+    private _modelDetected;
+    private _eventHandlers;
+    private _sseCleanupHandlers;
+    /** Low-level session operations (implementing Provider interface). */
+    readonly session: Provider["session"];
+    /** SSE event subscription (implementing Provider interface). */
+    readonly event: Provider["event"];
+    /**
+     * Creates a new Copilot provider.
+     *
+     * @param config  - Provider configuration (model, destination, permissions).
+     * @param factory - Optional client factory override for testing.
+     */
+    constructor(config: ProviderConfig, factory?: CreateCopilotClientFn);
+    get name(): string;
+    get model(): string | undefined;
+    get config(): ProviderConfig;
+    /**
+     * Creates and initializes a CopilotProvider.
+     * Mirrors Dispatch's `boot()` pattern — callers receive a ready-to-use
+     * provider without calling `initialize()` separately.
+     */
+    static create(config: ProviderConfig, factory?: CreateCopilotClientFn): Promise<CopilotProvider>;
+    /** Fan out an SSE event to all active subscribers. */
+    private _emit;
+    /**
+     * 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.
+     */
+    private _buildPermissionHandler;
+    /**
+     * 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
+     */
+    private _buildSessionConfig;
+    /**
+     * 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.
+     */
+    initialize(): Promise<void>;
+    /**
+     * 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.
+     */
+    createSession(): Promise<string>;
+    /**
+     * 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.
+     */
+    prompt(sessionId: string, text: string, options?: {
+        agent?: string;
+    }): Promise<string | 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.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Alias for `cleanup()` — kept for backward compatibility with callers
+     * that use the old `shutdown()` name.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * 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(): string | undefined;
+    /**
+     * Returns the name of the env var that provided the token, for logging.
+     * @internal
+     */
+    static _findTokenSource(): string;
+}
+export {};