feat(M3-001): refactor ProviderService into IProviderAdapter pattern (#306)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

apps/gateway/src/agent/__tests__/provider.service.test.ts

@@ -34,9 +34,9 @@ describe('ProviderService', () => {
     }
   });
 
-  it('skips API-key providers when env vars are missing (no models become available)', () => {
+  it('skips API-key providers when env vars are missing (no models become available)', async () => {
     const service = new ProviderService();
-    service.onModuleInit();
+    await service.onModuleInit();
 
     // Pi's built-in registry may include model definitions for all providers, but
     // without API keys none of them should be available (usable).
@@ -54,11 +54,11 @@ describe('ProviderService', () => {
     }
   });
 
-  it('registers Anthropic provider with correct models when ANTHROPIC_API_KEY is set', () => {
+  it('registers Anthropic provider with correct models when ANTHROPIC_API_KEY is set', async () => {
     process.env['ANTHROPIC_API_KEY'] = 'test-anthropic';
 
     const service = new ProviderService();
-    service.onModuleInit();
+    await service.onModuleInit();
 
     const providers = service.listProviders();
     const anthropic = providers.find((p) => p.id === 'anthropic');
@@ -77,11 +77,11 @@ describe('ProviderService', () => {
     }
   });
 
-  it('registers OpenAI provider with correct models when OPENAI_API_KEY is set', () => {
+  it('registers OpenAI provider with correct models when OPENAI_API_KEY is set', async () => {
     process.env['OPENAI_API_KEY'] = 'test-openai';
 
     const service = new ProviderService();
-    service.onModuleInit();
+    await service.onModuleInit();
 
     const providers = service.listProviders();
     const openai = providers.find((p) => p.id === 'openai');
@@ -90,11 +90,11 @@ describe('ProviderService', () => {
     expect(openai!.models.map((m) => m.id)).toEqual(['gpt-4o', 'gpt-4o-mini', 'o3-mini']);
   });
 
-  it('registers Z.ai provider with correct models when ZAI_API_KEY is set', () => {
+  it('registers Z.ai provider with correct models when ZAI_API_KEY is set', async () => {
     process.env['ZAI_API_KEY'] = 'test-zai';
 
     const service = new ProviderService();
-    service.onModuleInit();
+    await service.onModuleInit();
 
     const providers = service.listProviders();
     const zai = providers.find((p) => p.id === 'zai');
@@ -103,13 +103,13 @@ describe('ProviderService', () => {
     expect(zai!.models.map((m) => m.id)).toEqual(['glm-4.5', 'glm-4.5-air', 'glm-4.5-flash']);
   });
 
-  it('registers all three providers when all keys are set', () => {
+  it('registers all three providers when all keys are set', async () => {
     process.env['ANTHROPIC_API_KEY'] = 'test-anthropic';
     process.env['OPENAI_API_KEY'] = 'test-openai';
     process.env['ZAI_API_KEY'] = 'test-zai';
 
     const service = new ProviderService();
-    service.onModuleInit();
+    await service.onModuleInit();
 
     const providerIds = service.listProviders().map((p) => p.id);
     expect(providerIds).toContain('anthropic');
@@ -117,11 +117,11 @@ describe('ProviderService', () => {
     expect(providerIds).toContain('zai');
   });
 
-  it('can find registered Anthropic models by provider+id', () => {
+  it('can find registered Anthropic models by provider+id', async () => {
     process.env['ANTHROPIC_API_KEY'] = 'test-anthropic';
 
     const service = new ProviderService();
-    service.onModuleInit();
+    await service.onModuleInit();
 
     const sonnet = service.findModel('anthropic', 'claude-sonnet-4-6');
     expect(sonnet).toBeDefined();
@@ -129,11 +129,11 @@ describe('ProviderService', () => {
     expect(sonnet!.id).toBe('claude-sonnet-4-6');
   });
 
-  it('can find registered Z.ai models by provider+id', () => {
+  it('can find registered Z.ai models by provider+id', async () => {
     process.env['ZAI_API_KEY'] = 'test-zai';
 
     const service = new ProviderService();
-    service.onModuleInit();
+    await service.onModuleInit();
 
     const glm = service.findModel('zai', 'glm-4.5');
     expect(glm).toBeDefined();

apps/gateway/src/agent/adapters/index.ts

@@ -0,0 +1 @@
+export { OllamaAdapter } from './ollama.adapter.js';

apps/gateway/src/agent/adapters/ollama.adapter.ts

@@ -0,0 +1,125 @@
+import { Logger } from '@nestjs/common';
+import type { ModelRegistry } from '@mariozechner/pi-coding-agent';
+import type {
+  CompletionEvent,
+  CompletionParams,
+  IProviderAdapter,
+  ModelInfo,
+  ProviderHealth,
+} from '@mosaic/types';
+
+/**
+ * Ollama provider adapter.
+ *
+ * Registers local Ollama models with the Pi ModelRegistry via the OpenAI-compatible
+ * completions API. Configuration is driven by environment variables:
+ *   OLLAMA_BASE_URL or OLLAMA_HOST — base URL of the Ollama instance
+ *   OLLAMA_MODELS              — comma-separated list of model IDs (default: llama3.2,codellama,mistral)
+ */
+export class OllamaAdapter implements IProviderAdapter {
+  readonly name = 'ollama';
+
+  private readonly logger = new Logger(OllamaAdapter.name);
+  private registeredModels: ModelInfo[] = [];
+
+  constructor(private readonly registry: ModelRegistry) {}
+
+  async register(): Promise<void> {
+    const ollamaUrl = process.env['OLLAMA_BASE_URL'] ?? process.env['OLLAMA_HOST'];
+    if (!ollamaUrl) {
+      this.logger.debug('Skipping Ollama provider registration: OLLAMA_BASE_URL not set');
+      return;
+    }
+
+    const modelsEnv = process.env['OLLAMA_MODELS'] ?? 'llama3.2,codellama,mistral';
+    const modelIds = modelsEnv
+      .split(',')
+      .map((id: string) => id.trim())
+      .filter(Boolean);
+
+    this.registry.registerProvider('ollama', {
+      baseUrl: `${ollamaUrl}/v1`,
+      apiKey: 'ollama',
+      api: 'openai-completions' as never,
+      models: modelIds.map((id) => ({
+        id,
+        name: id,
+        reasoning: false,
+        input: ['text'] as ('text' | 'image')[],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 8192,
+        maxTokens: 4096,
+      })),
+    });
+
+    this.registeredModels = modelIds.map((id) => ({
+      id,
+      provider: 'ollama',
+      name: id,
+      reasoning: false,
+      contextWindow: 8192,
+      maxTokens: 4096,
+      inputTypes: ['text'] as ('text' | 'image')[],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    }));
+
+    this.logger.log(
+      `Ollama provider registered at ${ollamaUrl} with models: ${modelIds.join(', ')}`,
+    );
+  }
+
+  listModels(): ModelInfo[] {
+    return this.registeredModels;
+  }
+
+  async healthCheck(): Promise<ProviderHealth> {
+    const ollamaUrl = process.env['OLLAMA_BASE_URL'] ?? process.env['OLLAMA_HOST'];
+    if (!ollamaUrl) {
+      return {
+        status: 'down',
+        lastChecked: new Date().toISOString(),
+        error: 'OLLAMA_BASE_URL not configured',
+      };
+    }
+
+    const checkUrl = `${ollamaUrl}/v1/models`;
+    const start = Date.now();
+
+    try {
+      const res = await fetch(checkUrl, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+        signal: AbortSignal.timeout(5000),
+      });
+      const latencyMs = Date.now() - start;
+
+      if (!res.ok) {
+        return {
+          status: 'degraded',
+          latencyMs,
+          lastChecked: new Date().toISOString(),
+          error: `HTTP ${res.status}`,
+        };
+      }
+
+      return { status: 'healthy', latencyMs, lastChecked: new Date().toISOString() };
+    } catch (err) {
+      const latencyMs = Date.now() - start;
+      const error = err instanceof Error ? err.message : String(err);
+      return { status: 'down', latencyMs, lastChecked: new Date().toISOString(), error };
+    }
+  }
+
+  /**
+   * createCompletion is reserved for future direct-completion use.
+   * The current integration routes completions through Pi SDK's ModelRegistry/AgentSession.
+   */
+  async *createCompletion(_params: CompletionParams): AsyncIterable<CompletionEvent> {
+    throw new Error(
+      'OllamaAdapter.createCompletion is not yet implemented. ' +
+        'Use Pi SDK AgentSession for completions.',
+    );
+    // Satisfy the AsyncGenerator return type — unreachable but required for TypeScript.
+    yield undefined as never;
+  }
+}

apps/gateway/src/agent/provider.service.ts

@@ -1,19 +1,43 @@
 import { Injectable, Logger, type OnModuleInit } from '@nestjs/common';
 import { ModelRegistry, AuthStorage } from '@mariozechner/pi-coding-agent';
 import { getModel, type Model, type Api } from '@mariozechner/pi-ai';
-import type { ModelInfo, ProviderInfo, CustomProviderConfig } from '@mosaic/types';
+import type {
+  CustomProviderConfig,
+  IProviderAdapter,
+  ModelInfo,
+  ProviderHealth,
+  ProviderInfo,
+} from '@mosaic/types';
+import { OllamaAdapter } from './adapters/index.js';
 import type { TestConnectionResultDto } from './provider.dto.js';
 
+/** DI injection token for the provider adapter array. */
+export const PROVIDER_ADAPTERS = Symbol('PROVIDER_ADAPTERS');
+
 @Injectable()
 export class ProviderService implements OnModuleInit {
   private readonly logger = new Logger(ProviderService.name);
   private registry!: ModelRegistry;
 
-  onModuleInit(): void {
+  /**
+   * Adapters registered with this service.
+   * Built-in adapters (Ollama) are always present; additional adapters can be
+   * supplied via the PROVIDER_ADAPTERS injection token in the future.
+   */
+  private adapters: IProviderAdapter[] = [];
+
+  async onModuleInit(): Promise<void> {
     const authStorage = AuthStorage.inMemory();
     this.registry = new ModelRegistry(authStorage);
 
-    this.registerOllamaProvider();
+    // Build the default set of adapters that rely on the registry
+    this.adapters = [new OllamaAdapter(this.registry)];
+
+    // Run all adapter registrations first (Ollama, and any future adapters)
+    await this.registerAll();
+
+    // Register API-key providers directly (Anthropic, OpenAI, Z.ai, custom)
+    // These do not yet have dedicated adapter classes (M3-002 through M3-005).
     this.registerAnthropicProvider();
     this.registerOpenAIProvider();
     this.registerZaiProvider();
@@ -23,6 +47,59 @@ export class ProviderService implements OnModuleInit {
     this.logger.log(`Providers initialized: ${available.length} models available`);
   }
 
+  // ---------------------------------------------------------------------------
+  // Adapter-pattern API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Call register() on each adapter in order.
+   * Errors from individual adapters are logged and do not abort the others.
+   */
+  async registerAll(): Promise<void> {
+    for (const adapter of this.adapters) {
+      try {
+        await adapter.register();
+      } catch (err) {
+        this.logger.error(
+          `Adapter "${adapter.name}" registration failed`,
+          err instanceof Error ? err.stack : String(err),
+        );
+      }
+    }
+  }
+
+  /**
+   * Return the adapter registered under the given provider name, or undefined.
+   */
+  getAdapter(providerName: string): IProviderAdapter | undefined {
+    return this.adapters.find((a) => a.name === providerName);
+  }
+
+  /**
+   * Run healthCheck() on all adapters and return results keyed by provider name.
+   */
+  async healthCheckAll(): Promise<Record<string, ProviderHealth>> {
+    const results: Record<string, ProviderHealth> = {};
+    await Promise.all(
+      this.adapters.map(async (adapter) => {
+        try {
+          results[adapter.name] = await adapter.healthCheck();
+        } catch (err) {
+          results[adapter.name] = {
+            status: 'down',
+            lastChecked: new Date().toISOString(),
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+      }),
+    );
+    return results;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Legacy / Pi-SDK-facing API (preserved for AgentService and RoutingService)
+  // ---------------------------------------------------------------------------
+
   getRegistry(): ModelRegistry {
     return this.registry;
   }
@@ -69,6 +146,18 @@ export class ProviderService implements OnModuleInit {
   }
 
   async testConnection(providerId: string, baseUrl?: string): Promise<TestConnectionResultDto> {
+    // Delegate to the adapter when one exists and no URL override is given
+    const adapter = this.getAdapter(providerId);
+    if (adapter && !baseUrl) {
+      const health = await adapter.healthCheck();
+      return {
+        providerId,
+        reachable: health.status !== 'down',
+        latencyMs: health.latencyMs,
+        error: health.error,
+      };
+    }
+
     // Resolve baseUrl: explicit override > registered provider > ollama env
     let resolvedUrl = baseUrl;
 
@@ -143,6 +232,11 @@ export class ProviderService implements OnModuleInit {
     this.logger.log(`Registered custom provider: ${config.id} (${config.models.length} models)`);
   }
 
+  // ---------------------------------------------------------------------------
+  // Private helpers — direct registry registration for providers without adapters yet
+  // (Anthropic, OpenAI, Z.ai will move to adapters in M3-002 through M3-005)
+  // ---------------------------------------------------------------------------
+
   private registerAnthropicProvider(): void {
     const apiKey = process.env['ANTHROPIC_API_KEY'];
     if (!apiKey) {
@@ -203,36 +297,6 @@ export class ProviderService implements OnModuleInit {
     this.logger.log('Z.ai provider registered with 3 models');
   }
 
-  private registerOllamaProvider(): void {
-    const ollamaUrl = process.env['OLLAMA_BASE_URL'] ?? process.env['OLLAMA_HOST'];
-    if (!ollamaUrl) return;
-
-    const modelsEnv = process.env['OLLAMA_MODELS'] ?? 'llama3.2,codellama,mistral';
-    const modelIds = modelsEnv
-      .split(',')
-      .map((modelId: string) => modelId.trim())
-      .filter(Boolean);
-
-    this.registry.registerProvider('ollama', {
-      baseUrl: `${ollamaUrl}/v1`,
-      apiKey: 'ollama',
-      api: 'openai-completions' as never,
-      models: modelIds.map((id) => ({
-        id,
-        name: id,
-        reasoning: false,
-        input: ['text'] as ('text' | 'image')[],
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-        contextWindow: 8192,
-        maxTokens: 4096,
-      })),
-    });
-
-    this.logger.log(
-      `Ollama provider registered at ${ollamaUrl} with models: ${modelIds.join(', ')}`,
-    );
-  }
-
   private registerCustomProviders(): void {
     const customJson = process.env['MOSAIC_CUSTOM_PROVIDERS'];
     if (!customJson) return;