sofia-cli 0.1.1

package/src/shared/activitySpinner.ts

@@ -0,0 +1,108 @@
+/**
+ * Activity spinner module.
+ *
+ * Wraps `ora` to provide unified visual feedback during LLM processing,
+ * tool calls, and internal operations (FR-043a, FR-043c).
+ *
+ * Spinner lifecycle:
+ *   User input → startThinking() → "Thinking..."
+ *     → ToolCall event → startToolCall(name) → "⠋ <name>..."
+ *     → ToolResult event → completeToolCall(name, summary) → "✓ <name>: <summary>"
+ *                        → startThinking() (if more processing expected)
+ *     → TextDelta event → stop() → stream text
+ *
+ * All operations are no-ops when non-TTY or JSON mode.
+ */
+import ora from 'ora';
+import type { Ora } from 'ora';
+
+export interface ActivitySpinnerOptions {
+  isTTY: boolean;
+  isJsonMode: boolean;
+  debugMode?: boolean;
+  /** Override stream for testing (default: process.stderr). */
+  stream?: NodeJS.WritableStream;
+}
+
+export class ActivitySpinner {
+  private spinner: Ora | null = null;
+  private _active = false;
+  private readonly enabled: boolean;
+  private readonly debug: boolean;
+  private readonly stream: NodeJS.WritableStream;
+
+  constructor(options: ActivitySpinnerOptions) {
+    this.enabled = options.isTTY && !options.isJsonMode;
+    this.debug = options.debugMode ?? false;
+    this.stream = options.stream ?? process.stderr;
+  }
+
+  /** Display "Thinking..." spinner during silent gaps. */
+  startThinking(): void {
+    if (!this.enabled) return;
+
+    if (this._active && this.spinner) {
+      this.spinner.text = 'Thinking...';
+      return;
+    }
+
+    this.spinner = ora({
+      text: 'Thinking...',
+      stream: this.stream,
+      discardStdin: false,
+    }).start();
+    this._active = true;
+  }
+
+  /** Transition spinner to show tool-specific status. */
+  startToolCall(toolName: string): void {
+    if (!this.enabled) return;
+
+    if (this._active && this.spinner) {
+      this.spinner.text = `${toolName}...`;
+    } else {
+      this.spinner = ora({
+        text: `${toolName}...`,
+        stream: this.stream,
+        discardStdin: false,
+      }).start();
+      this._active = true;
+    }
+  }
+
+  /**
+   * Stop spinner and print a one-line tool completion summary.
+   * The summary line remains visible in the output stream.
+   */
+  completeToolCall(_toolName: string, _summary: string): void {
+    if (!this.enabled) return;
+
+    if (this._active && this.spinner) {
+      this.spinner.stop();
+    }
+    this._active = false;
+    // Summary output is handled by io.writeToolSummary() to respect
+    // JSON/debug mode — no duplicate write here.
+  }
+
+  /** Stop any active spinner. */
+  stop(): void {
+    if (this.spinner) {
+      this.spinner.stop();
+    }
+    this.spinner = null;
+    this._active = false;
+  }
+
+  /** Check if a spinner is currently active. */
+  isActive(): boolean {
+    return this._active;
+  }
+}
+
+/**
+ * Create a no-op spinner for tests or non-TTY environments.
+ */
+export function createNoOpSpinner(): ActivitySpinner {
+  return new ActivitySpinner({ isTTY: false, isJsonMode: true });
+}

package/src/shared/copilotClient.ts

@@ -0,0 +1,291 @@
+/**
+ * Copilot client abstraction.
+ *
+ * Wraps Copilot SDK interactions behind a small interface so that
+ * tests can use deterministic fakes instead of live LLM calls.
+ */
+import type { SofiaEvent } from './events.js';
+import { createTextDeltaEvent } from './events.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface CopilotMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters?: Record<string, unknown>;
+}
+
+export interface SessionOptions {
+  systemPrompt: string;
+  tools?: ToolDefinition[];
+  references?: string[];
+  /**
+   * MCP server configurations to forward to the Copilot SDK's
+   * `createSession()`. The SDK manages server lifecycle (spawn/connect,
+   * JSON-RPC, tool dispatch) for LLM-initiated tool calls.
+   *
+   * Format: `Record<string, MCPServerConfig>` matching the SDK's expected
+   * shape (MCPLocalServerConfig or MCPRemoteServerConfig).
+   * Uses `import('@github/copilot-sdk').MCPServerConfig` when SDK is available.
+   */
+  mcpServers?: Record<
+    string,
+    {
+      type?: string;
+      tools: string[];
+      timeout?: number;
+      command?: string;
+      args?: string[];
+      env?: Record<string, string>;
+      cwd?: string;
+      url?: string;
+      headers?: Record<string, string>;
+    }
+  >;
+  /**
+   * Optional hooks for SDK tool-call visibility (FR-021, FR-022).
+   * Forwarded to SDK `createSession({ hooks })` so tool-call activity
+   * is emitted to the CLI spinner via the activity event system.
+   *
+   * Shapes match the SDK's `SessionHooks` signatures:
+   * - `onPreToolUse(input: { toolName, toolArgs }, invocation)`
+   * - `onPostToolUse(input: { toolName, toolArgs, toolResult }, invocation)`
+   * - `onErrorOccurred(input: { error }, invocation)`
+   */
+  hooks?: {
+    onPreToolUse?: (
+      input: { toolName: string; toolArgs: unknown },
+      invocation: { sessionId: string },
+    ) => Promise<{ permissionDecision?: 'allow' | 'deny' | 'ask' } | void> | void;
+    onPostToolUse?: (
+      input: { toolName: string; toolArgs: unknown; toolResult: unknown },
+      invocation: { sessionId: string },
+    ) => Promise<void> | void;
+    onErrorOccurred?: (
+      input: { error: string; errorContext?: string; recoverable?: boolean },
+      invocation: { sessionId: string },
+    ) => Promise<void> | void;
+  };
+  /**
+   * Infinite session configuration for persistent workspaces and automatic
+   * context compaction. When enabled, sessions automatically manage context
+   * limits and persist state. Passed through to SDK `createSession()`.
+   *
+   * Recommended for Ralph Loop sessions to prevent context window exhaustion
+   * during extended multi-iteration conversations (FR-023).
+   */
+  infiniteSessions?: {
+    enabled?: boolean;
+    backgroundCompactionThreshold?: number;
+    bufferExhaustionThreshold?: number;
+  };
+  /**
+   * Callback invoked when the SDK emits `assistant.usage` events (FR-024).
+   * Called with token usage data from each model interaction.
+   * Consumers can use this for debug logging or cumulative tracking.
+   */
+  onUsage?: (usage: {
+    model: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+  }) => void;
+}
+
+/**
+ * A conversation session with the LLM.
+ * Supports multi-turn conversations with streaming.
+ */
+export interface ConversationSession {
+  /** Send a message and receive streaming events. */
+  send(message: CopilotMessage): AsyncIterable<SofiaEvent>;
+  /** Get the full conversation history. */
+  getHistory(): CopilotMessage[];
+}
+
+/**
+ * Client interface for creating conversation sessions.
+ * Live implementations wrap the Copilot SDK; fakes provide deterministic behavior.
+ */
+export interface CopilotClient {
+  createSession(options: SessionOptions): Promise<ConversationSession>;
+}
+
+// ── Fake implementation for tests ────────────────────────────────────────────
+
+interface FakeClientOptions {
+  tools?: ToolDefinition[];
+  /** Override the send behavior entirely for custom test scenarios (e.g., transient failures). */
+  onChat?: (message: CopilotMessage) => Promise<CopilotMessage>;
+}
+
+/**
+ * Create a fake CopilotClient that returns predetermined responses.
+ * Used in unit and integration tests for deterministic behavior.
+ */
+export function createFakeCopilotClient(
+  responses: CopilotMessage[],
+  _options?: FakeClientOptions,
+): CopilotClient {
+  let responseIndex = 0;
+
+  return {
+    async createSession(_sessionOptions: SessionOptions): Promise<ConversationSession> {
+      const history: CopilotMessage[] = [];
+
+      return {
+        send(message: CopilotMessage): AsyncIterable<SofiaEvent> {
+          history.push(message);
+
+          // If onChat override is provided, use it (allows throwing for retry tests)
+          if (_options?.onChat) {
+            const chatFn = _options.onChat;
+            return {
+              async *[Symbol.asyncIterator]() {
+                const response = await chatFn(message);
+                history.push(response);
+                yield createTextDeltaEvent(response.content);
+              },
+            };
+          }
+
+          const response = responses[responseIndex] ?? {
+            role: 'assistant' as const,
+            content: '[No more responses configured]',
+          };
+          responseIndex++;
+          history.push(response);
+
+          return {
+            async *[Symbol.asyncIterator]() {
+              // Simulate streaming by yielding the full content as a single TextDelta
+              yield createTextDeltaEvent(response.content);
+            },
+          };
+        },
+        getHistory(): CopilotMessage[] {
+          return [...history];
+        },
+      };
+    },
+  };
+}
+
+// ── Live Copilot SDK client (created when SDK is available) ──────────────────
+
+/**
+ * Create a real CopilotClient using the GitHub Copilot SDK.
+ * Wraps the SDK's CopilotClient + CopilotSession behind our
+ * CopilotClient / ConversationSession interfaces so the rest of
+ * the codebase (ConversationLoop, phaseHandlers) stays decoupled.
+ *
+ * Throws a clear error if the SDK is not installed.
+ */
+export async function createCopilotClient(): Promise<CopilotClient> {
+  // Dynamic import — SDK is listed in dependencies but may fail in
+  // environments where the native add-on cannot build.
+  let sdk: typeof import('@github/copilot-sdk');
+  try {
+    sdk = await import('@github/copilot-sdk');
+  } catch (err: unknown) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`GitHub Copilot SDK (@github/copilot-sdk) is not available: ${detail}`);
+  }
+
+  const { CopilotClient: SdkClient, approveAll } = sdk;
+
+  // A single SDK client instance is shared across sessions.
+  // autoStart: true (default) means `start()` is called lazily on
+  // the first `createSession`.
+  const sdkClient = new SdkClient();
+
+  return {
+    async createSession(options: SessionOptions): Promise<ConversationSession> {
+      const sessionConfig = {
+        onPermissionRequest: approveAll,
+        systemMessage: {
+          mode: 'replace' as const,
+          content: options.systemPrompt,
+        },
+        // Forward MCP server configs to the SDK so it manages server lifecycle
+        // (spawn, connect, JSON-RPC dispatch) for LLM-initiated tool calls.
+        // Cast needed because our SessionOptions uses a portable shape that
+        // doesn't carry the SDK's discriminated-union literal types.
+        ...(options.mcpServers && Object.keys(options.mcpServers).length > 0
+          ? {
+              mcpServers: options.mcpServers as Record<
+                string,
+                import('@github/copilot-sdk').MCPServerConfig
+              >,
+            }
+          : {}),
+        // Forward SDK hooks for tool-call visibility (FR-021, FR-022).
+        ...(options.hooks ? { hooks: options.hooks } : {}),
+        // Forward infinite sessions config for context management (FR-023).
+        ...(options.infiniteSessions ? { infiniteSessions: options.infiniteSessions } : {}),
+      };
+
+      const sdkSession = await sdkClient.createSession(sessionConfig);
+
+      // Subscribe to assistant.usage events for token usage tracking (FR-024).
+      if (options.onUsage) {
+        const usageCb = options.onUsage;
+        sdkSession.on(
+          'assistant.usage',
+          (event: {
+            data: {
+              model: string;
+              inputTokens?: number;
+              outputTokens?: number;
+              cacheReadTokens?: number;
+              cacheWriteTokens?: number;
+            };
+          }) => {
+            usageCb(event.data);
+          },
+        );
+      }
+
+      const history: CopilotMessage[] = [];
+
+      return {
+        send(message: CopilotMessage): AsyncIterable<SofiaEvent> {
+          history.push(message);
+
+          // Return an AsyncIterable that bridges SDK events → SofiaEvents.
+          // We use `sendAndWait` which blocks until the assistant is idle
+          // and then yield the complete response as a single TextDelta,
+          // keeping the same contract the fake client provides.
+          return {
+            async *[Symbol.asyncIterator]() {
+              const response = await sdkSession.sendAndWait(
+                { prompt: message.content },
+                120_000, // 2-minute timeout
+              );
+
+              const content = response?.data.content ?? '';
+              if (content) {
+                const assistantMsg: CopilotMessage = {
+                  role: 'assistant',
+                  content,
+                };
+                history.push(assistantMsg);
+                yield createTextDeltaEvent(content);
+              }
+            },
+          };
+        },
+
+        getHistory(): CopilotMessage[] {
+          return [...history];
+        },
+      };
+    },
+  };
+}