pi-smart-router 0.1.0

package/.pi/extensions/smart-router/delegation-runtime.ts

@@ -0,0 +1,355 @@
+/**
+ * Delegation helpers: auth merge, event flush/sanitize, failover notice injection, registry lookups.
+ */
+
+import {
+  type Api,
+  type AssistantMessage,
+  type AssistantMessageEvent,
+  type AssistantMessageEventStream,
+  type Context,
+  type Model,
+  type SimpleStreamOptions,
+} from '@earendil-works/pi-ai/compat';
+import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
+
+import { normalizeDelegationContext } from '../../../src/domain/delegation/delegation-context.js';
+import {
+  computeOutputHeadroom,
+  type OutputHeadroomConfig,
+} from '../../../src/domain/delegation/output-headroom.js';
+import type { ModelProfile } from '../../../src/domain/types/index.js';
+import {
+  formatGeminiThoughtSignatureErrorMessage,
+  formatProviderErrorMessage,
+  isGeminiThoughtSignatureAssistantError,
+  parseAssistantMessageError,
+  sanitizeLengthStopMessage,
+  type LengthStopHints,
+} from '../../../src/infrastructure/delegation/provider-error.js';
+import type { StreamDelegationDeps } from './types.js';
+
+/** Stream options safe to forward to a delegated provider call. */
+const DELEGATION_CALLER_OPTION_KEYS = [
+  'signal',
+  'sessionId',
+  'reasoning',
+  'thinkingBudgets',
+  'temperature',
+  'maxTokens',
+  'transport',
+  'cacheRetention',
+  'timeoutMs',
+  'maxRetries',
+  'maxRetryDelayMs',
+  'metadata',
+  'websocketConnectTimeoutMs',
+] as const satisfies readonly (keyof SimpleStreamOptions)[];
+
+function pickDelegationCallerOptions(
+  callerOptions?: SimpleStreamOptions,
+): SimpleStreamOptions {
+  if (!callerOptions) {
+    return {};
+  }
+
+  const picked: SimpleStreamOptions = {};
+  const source = callerOptions as SimpleStreamOptions & Record<string, unknown>;
+  for (const key of DELEGATION_CALLER_OPTION_KEYS) {
+    if (source[key] !== undefined) {
+      (picked as Record<string, unknown>)[key] = source[key];
+    }
+  }
+  return picked;
+}
+
+export class DelegationHeadroomError extends Error {
+  readonly reason = 'delegation_output_headroom_exceeded' as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'DelegationHeadroomError';
+  }
+}
+
+export interface DelegationHeadroomContext {
+  readonly profile: ModelProfile;
+  readonly estimatedInputTokens: number;
+  readonly headroomConfig?: OutputHeadroomConfig;
+}
+
+export async function resolveDelegationOptions(
+  modelRegistry: ModelRegistry,
+  targetModel: Model<Api>,
+  callerOptions?: SimpleStreamOptions,
+  headroomContext?: DelegationHeadroomContext,
+): Promise<SimpleStreamOptions> {
+  const auth = await modelRegistry.getApiKeyAndHeaders(targetModel);
+  if (!auth.ok) {
+    throw new Error(auth.error);
+  }
+
+  const callerEnv = callerOptions?.env;
+  const mergedEnv =
+    auth.env || callerEnv
+      ? { ...(auth.env ?? {}), ...(callerEnv ?? {}) }
+      : undefined;
+
+  let maxTokens: number | undefined;
+  if (headroomContext) {
+    const headroom = computeOutputHeadroom(
+      headroomContext.profile,
+      headroomContext.estimatedInputTokens,
+      headroomContext.headroomConfig,
+      targetModel,
+    );
+    if (headroom.kind === 'no_fit') {
+      throw new DelegationHeadroomError(
+        `Output headroom below floor for ${targetModel.id}: ` +
+          `${headroomContext.estimatedInputTokens} input tokens on ` +
+          `${headroom.contextWindow} context window ` +
+          `(${headroom.availableOutputTokens} output tokens available)`,
+      );
+    }
+    maxTokens = headroom.maxTokens;
+  }
+
+  return {
+    ...pickDelegationCallerOptions(callerOptions),
+    ...(auth.apiKey !== undefined ? { apiKey: auth.apiKey } : {}),
+    ...(auth.headers !== undefined ? { headers: auth.headers } : {}),
+    ...(mergedEnv !== undefined ? { env: mergedEnv } : {}),
+    ...(maxTokens !== undefined ? { maxTokens } : {}),
+  };
+}
+
+export interface DelegatedStreamResult {
+  readonly finalMessage: AssistantMessage | undefined;
+  readonly failed: boolean;
+  readonly events: AssistantMessageEvent[];
+}
+
+export function modelToExecutionModel(model: Model<Api>) {
+  return {
+    provider: model.provider,
+    api: model.api,
+    id: model.id,
+  };
+}
+
+export function buildDelegationContext(
+  context: Context,
+  targetModel: Model<Api>,
+  deps: StreamDelegationDeps,
+  sessionId: string | undefined,
+): Context {
+  const sessionExecution = sessionId
+    ? deps.executionLedger.getLastExecution(sessionId)
+    : null;
+
+  return normalizeDelegationContext(context, targetModel, {
+    sessionExecution,
+  });
+}
+
+export function createErrorMessage(
+  model: Model<Api>,
+  options: SimpleStreamOptions | undefined,
+  error: unknown,
+): AssistantMessage {
+  return {
+    role: 'assistant',
+    content: [],
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: options?.signal?.aborted ? 'aborted' : 'error',
+    errorMessage: formatProviderErrorMessage(
+      error instanceof Error ? error.message : String(error),
+    ),
+    timestamp: Date.now(),
+  };
+}
+
+function sanitizeAssistantErrorMessage(
+  message: AssistantMessage,
+  lengthStopHints?: LengthStopHints,
+): AssistantMessage {
+  const lengthSanitized = sanitizeLengthStopMessage(message, lengthStopHints);
+  if (lengthSanitized.stopReason !== 'error' || !lengthSanitized.errorMessage) {
+    return lengthSanitized;
+  }
+
+  const formatted = isGeminiThoughtSignatureAssistantError(lengthSanitized)
+    ? formatGeminiThoughtSignatureErrorMessage(lengthSanitized.errorMessage)
+    : formatProviderErrorMessage(lengthSanitized.errorMessage);
+  if (formatted === lengthSanitized.errorMessage) {
+    return lengthSanitized;
+  }
+  return { ...lengthSanitized, errorMessage: formatted };
+}
+
+function sanitizeDelegatedErrorEvents(
+  events: AssistantMessageEvent[],
+  lengthStopHints?: LengthStopHints,
+): void {
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    if (!event) {
+      continue;
+    }
+    if (event.type === 'error') {
+      events[i] = {
+        ...event,
+        error: sanitizeAssistantErrorMessage(event.error, lengthStopHints),
+      };
+    } else if (event.type === 'done' && event.message.stopReason === 'error') {
+      events[i] = {
+        ...event,
+        message: sanitizeAssistantErrorMessage(event.message, lengthStopHints),
+      };
+    }
+  }
+}
+
+function sanitizeLengthStopEvents(
+  events: AssistantMessageEvent[],
+  lengthStopHints?: LengthStopHints,
+): void {
+  if (!lengthStopHints?.contextWindow) {
+    return;
+  }
+
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    if (!event) {
+      continue;
+    }
+
+    if (event.type === 'done' && event.message.stopReason === 'length') {
+      const sanitized = sanitizeLengthStopMessage(event.message, lengthStopHints);
+      if (sanitized.stopReason === 'error') {
+        events[i] = {
+          type: 'error',
+          reason: 'error',
+          error: sanitized,
+        };
+      } else {
+        events[i] = { ...event, message: sanitized };
+      }
+    } else if (event.type === 'error' && event.error.stopReason === 'length') {
+      const sanitized = sanitizeLengthStopMessage(event.error, lengthStopHints);
+      if (sanitized.stopReason === 'error') {
+        events[i] = { ...event, error: sanitized, reason: 'error' };
+      } else {
+        events[i] = { ...event, error: sanitized };
+      }
+    }
+  }
+}
+
+export interface FlushDelegatedEventsOptions {
+  readonly sanitizeErrors?: boolean;
+  readonly contextWindow?: number;
+}
+
+export function flushDelegatedEvents(
+  outer: AssistantMessageEventStream,
+  events: readonly AssistantMessageEvent[],
+  options?: FlushDelegatedEventsOptions,
+): void {
+  const lengthStopHints =
+    options?.contextWindow !== undefined
+      ? { contextWindow: options.contextWindow }
+      : undefined;
+  const mutableEvents = [...events];
+  sanitizeLengthStopEvents(mutableEvents, lengthStopHints);
+  if (options?.sanitizeErrors) {
+    sanitizeDelegatedErrorEvents(mutableEvents, lengthStopHints);
+  }
+  for (const event of mutableEvents) {
+    outer.push(event);
+  }
+  outer.end();
+}
+
+export function injectFailoverNotice(
+  events: AssistantMessageEvent[],
+  failedModelId: string,
+  alternateModelId: string,
+  errorObj?: ReturnType<typeof parseAssistantMessageError>,
+): void {
+  const reason = errorObj?.message || errorObj?.code || 'Unavailable';
+  const notice = `> ⚠️ **pi-smart-router failover:** \`${failedModelId}\` failed (${reason}). Retrying with \`${alternateModelId}\`...`;
+
+  let noticeInjected = false;
+
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    if (!event) {
+      continue;
+    }
+
+    if (event.type === 'start') {
+      const newPartial = { ...event.partial, content: [...event.partial.content] };
+      const firstBlock = newPartial.content[0];
+      if (firstBlock && firstBlock.type === 'text') {
+        newPartial.content[0] = { ...firstBlock, text: notice + '\n\n' + firstBlock.text };
+      } else {
+        newPartial.content.unshift({ type: 'text', text: notice + '\n\n' });
+      }
+      events[i] = { ...event, partial: newPartial };
+    }
+
+    if (!noticeInjected && event.type === 'text_delta') {
+      events[i] = { ...event, delta: notice + '\n\n' + event.delta };
+      noticeInjected = true;
+    }
+
+    if (event.type === 'done' && event.message) {
+      const newMsg = { ...event.message, content: [...event.message.content] };
+      const firstBlock = newMsg.content[0];
+      if (firstBlock && firstBlock.type === 'text') {
+        newMsg.content[0] = { ...firstBlock, text: notice + '\n\n' + firstBlock.text };
+      } else {
+        newMsg.content.unshift({ type: 'text', text: notice + '\n\n' });
+      }
+      events[i] = { ...event, message: newMsg };
+    }
+  }
+
+  if (!noticeInjected) {
+    const startIdx = events.findIndex((e) => e.type === 'start');
+    const startEvent = startIdx === -1 ? undefined : events[startIdx];
+    if (startEvent?.type === 'start') {
+      events.splice(startIdx + 1, 0, {
+        type: 'text_delta',
+        contentIndex: 0,
+        delta: notice + '\n\n',
+        partial: startEvent.partial,
+      });
+    }
+  }
+}
+
+export function findFleetProfile(
+  fleet: readonly ModelProfile[],
+  modelId: string,
+): ModelProfile | undefined {
+  return fleet.find((profile) => profile.id === modelId);
+}
+
+export function resolveRegistryModel(
+  modelRegistry: ModelRegistry,
+  profile: ModelProfile,
+): Model<Api> | undefined {
+  return modelRegistry.find(profile.provider, profile.id);
+}

package/.pi/extensions/smart-router/extension-setup.ts

@@ -0,0 +1,115 @@
+import {
+  AuthStorage,
+  ModelRegistry,
+  type ExtensionAPI,
+} from '@earendil-works/pi-coding-agent';
+
+import { ExecutionLedger } from '../../../src/domain/delegation/execution-ledger.js';
+import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
+import type { SessionRoutingSnapshot } from '../../../src/infrastructure/telemetry/outcome-recorder.js';
+import { createRouterFromFleet, LifecycleHookState } from '../../../src/index.js';
+
+import { registerSmartRouterCommand } from './commands.js';
+import {
+  createExtensionDatasetRecorder,
+  createExtensionOutcomeRecorder,
+} from './dataset-export.js';
+import { createDispatchOptions, initHydraMatcher } from './fleet-bootstrap.js';
+import { setupSessionHooks } from './session-lifecycle.js';
+import { createStreamSimple } from './stream-delegation.js';
+import type { SmartRouterRuntime } from './types.js';
+import { createExtensionStore } from './utils.js';
+
+const PROVIDER_NAME = 'smart-router' as const;
+const AUTO_MODEL_ID = 'auto' as const;
+
+export type DatasetNotify = {
+  fn: ((message: string) => void) | undefined;
+};
+
+export async function createSmartRouterRuntime(cwd: string): Promise<{
+  runtime: SmartRouterRuntime;
+  datasetNotify: DatasetNotify;
+}> {
+  const authStorage = AuthStorage.create();
+  const modelRegistry = ModelRegistry.inMemory(authStorage);
+  const hydraMatcher = await initHydraMatcher();
+  const store = createExtensionStore(cwd);
+  const sessionPinner = new SessionPinner({ store });
+  const executionLedger = new ExecutionLedger();
+  const lifecycleHookState = new LifecycleHookState();
+  const datasetNotify: DatasetNotify = {
+    fn: undefined,
+  };
+  const datasetRecorder = createExtensionDatasetRecorder(store, cwd, (message) => {
+    datasetNotify.fn?.(message);
+  });
+  const outcomeRecorder = createExtensionOutcomeRecorder(store);
+  const sessionRouting = new Map<string, SessionRoutingSnapshot>();
+
+  const runtime: SmartRouterRuntime = {
+    fleetMode: 'scoped',
+    lastDecision: undefined,
+    priceCatalog: null,
+    modelRegistry,
+    store,
+    sessionPinner,
+    executionLedger,
+    lifecycleHookState,
+    hydraMatcher,
+    datasetRecorder,
+    outcomeRecorder,
+    sessionRouting,
+    streamDeps: {
+      router: createRouterFromFleet([], {
+        ...createDispatchOptions(store, sessionPinner, hydraMatcher),
+        lifecycleHookState,
+      }),
+      modelRegistry,
+      fleet: [],
+      executionLedger,
+      lifecycleHookState,
+      datasetRecorder,
+      outcomeRecorder,
+      sessionPinner,
+      sessionRouting,
+      onRoutingDecision(decision) {
+        runtime.lastDecision = decision;
+      },
+      onDelegatedModel(model) {
+        runtime.setLmuStatus?.(model.id);
+      },
+    },
+  };
+
+  return { runtime, datasetNotify };
+}
+
+export async function wireSmartRouterExtension(
+  pi: ExtensionAPI,
+  runtime: SmartRouterRuntime,
+  datasetNotify: DatasetNotify,
+): Promise<void> {
+  registerSmartRouterCommand(pi, runtime);
+
+  setupSessionHooks(pi, runtime, runtime.sessionPinner, datasetNotify);
+
+  pi.registerProvider(PROVIDER_NAME, {
+    name: 'Smart Router',
+    baseUrl: 'https://smart-router.local',
+    apiKey: 'local',
+    api: 'openai-responses',
+    models: [
+      {
+        id: AUTO_MODEL_ID,
+        name: 'Auto (Smart Router)',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 200_000,
+        maxTokens: 16_384,
+      },
+    ],
+    streamSimple: createStreamSimple(runtime.streamDeps),
+  });
+}

package/.pi/extensions/smart-router/fleet-bootstrap.ts

@@ -0,0 +1,244 @@
+import type { Api, Model } from '@earendil-works/pi-ai/compat';
+import {
+  ModelRegistry,
+  SettingsManager,
+  type ExtensionAPI,
+} from '@earendil-works/pi-coding-agent';
+
+import { mapFleetFromRegistry } from '../../../src/config/pi-model-mapper.js';
+import { DEFAULT_OPERATOR_CONFIG } from '../../../src/config/defaults.js';
+import {
+  HydraMatcher,
+  createOnnxEmbeddingProvider,
+} from '../../../src/domain/matching/hydra-matcher.js';
+import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
+import type { ModelProfile, PriceCatalog } from '../../../src/domain/types/index.js';
+import type { StorePort } from '../../../src/domain/types/store-port.js';
+import { getDefaultSystemInfo } from '../../../src/infrastructure/hardware/hardware-probe.js';
+import { DEFAULT_LOCAL_CONFIG } from '../../../src/infrastructure/local/local-zero-tier.js';
+import { RoutingTelemetryEmitter } from '../../../src/infrastructure/telemetry/routing-telemetry.js';
+import { applyCatalogPricesToFleet } from '../../../src/infrastructure/pricing/price-broker.js';
+import {
+  createRouterFromFleet,
+  type GatewayDispatchOptions,
+  type PiExtensionHooks,
+} from '../../../src/index.js';
+import { resolveModelScope } from './pi-model-scope.js';
+import type { FleetMode, SmartRouterRuntime } from './types.js';
+import { resolveRateLimiter } from './utils.js';
+
+/** Minimal settings surface used for scoped fleet discovery. */
+export interface ScopedSettingsReader {
+  getEnabledModels(): string[] | null | undefined;
+}
+
+export interface DiscoverFleetDeps {
+  settingsFactory?: (cwd: string) => ScopedSettingsReader;
+}
+
+/** Footer label for the last model that successfully served a delegated stream. */
+export function formatLmuStatus(
+  modelId: string,
+  theme?: { fg: (color: string, text: string) => string },
+): string {
+  const label = `LMU: ${modelId}`;
+  return theme ? theme.fg('dim', label) : label;
+}
+
+export function createHooksAdapter(pi: ExtensionAPI): PiExtensionHooks {
+  return {
+    on(event, handler) {
+      // PiExtensionHooks event names are a subset of ExtensionAPI; cast bridges the gap.
+      pi.on(event as never, handler as never);
+    },
+  };
+}
+
+function registryModelsToFleetInput(models: readonly Model<Api>[]) {
+  return models.map((model) => ({
+    provider: model.provider,
+    id: model.id,
+    ...(model.name !== undefined ? { name: model.name } : {}),
+    cost: {
+      input: model.cost.input,
+      output: model.cost.output,
+      cacheRead: model.cost.cacheRead,
+      cacheWrite: model.cost.cacheWrite,
+    },
+  }));
+}
+
+/** Bind pi's shared model registry (includes package-registered providers). */
+export function bindSharedModelRegistry(
+  runtime: SmartRouterRuntime,
+  modelRegistry: ModelRegistry,
+): void {
+  runtime.modelRegistry = modelRegistry;
+  runtime.streamDeps.modelRegistry = modelRegistry;
+}
+
+export function computeFleetScopeFingerprint(
+  mode: FleetMode,
+  patterns: readonly string[] | null | undefined,
+  available: readonly Model<Api>[],
+  catalogLastUpdated: string | null | undefined,
+): string {
+  const patternPart = patterns?.join('\n') ?? '';
+  const modelPart = available
+    .map((model) => `${model.provider}/${model.id}`)
+    .sort()
+    .join('\n');
+  return `${mode}\0${patternPart}\0${modelPart}\0${catalogLastUpdated ?? ''}`;
+}
+
+async function readScopeFingerprintInputs(
+  runtime: SmartRouterRuntime,
+  cwd: string,
+  deps?: DiscoverFleetDeps,
+): Promise<{ patterns: string[] | null | undefined; available: Model<Api>[] }> {
+  const available = await Promise.resolve(runtime.modelRegistry.getAvailable());
+  if (runtime.fleetMode !== 'scoped') {
+    return { patterns: null, available };
+  }
+
+  const settingsFactory = deps?.settingsFactory ?? SettingsManager.create;
+  const settings = settingsFactory(cwd);
+  return { patterns: settings.getEnabledModels(), available };
+}
+
+export async function computeCurrentFleetScopeFingerprint(
+  runtime: SmartRouterRuntime,
+  cwd: string,
+  deps?: DiscoverFleetDeps,
+): Promise<string> {
+  const { patterns, available } = await readScopeFingerprintInputs(runtime, cwd, deps);
+  const catalogLastUpdated = runtime.priceCatalog?.last_updated;
+  return computeFleetScopeFingerprint(
+    runtime.fleetMode,
+    patterns,
+    available,
+    catalogLastUpdated,
+  );
+}
+
+export async function discoverFleet(
+  modelRegistry: ModelRegistry,
+  mode: FleetMode,
+  cwd: string,
+  store: StorePort,
+  deps?: DiscoverFleetDeps,
+): Promise<{ fleet: ModelProfile[]; catalog: PriceCatalog | null }> {
+  const available = await Promise.resolve(modelRegistry.getAvailable());
+  let models = available;
+
+  if (mode === 'scoped') {
+    const settingsFactory = deps?.settingsFactory ?? SettingsManager.create;
+    const settings = settingsFactory(cwd);
+    const patterns = settings.getEnabledModels();
+    if (patterns && patterns.length > 0) {
+      const scopedModels = await resolveModelScope(patterns, modelRegistry);
+      models = scopedModels.map((scoped) => scoped.model);
+    }
+  }
+
+  const mappedFleet = mapFleetFromRegistry(registryModelsToFleetInput(models));
+  const catalog = await store.getPriceCatalog();
+  const fleet = applyCatalogPricesToFleet(mappedFleet, catalog);
+
+  return { fleet, catalog };
+}
+
+export function createDispatchOptions(
+  store: StorePort,
+  sessionPinner: SessionPinner,
+  hydraMatcher?: HydraMatcher,
+): GatewayDispatchOptions {
+  const telemetryEmitter = new RoutingTelemetryEmitter({
+    onRecord: (record) => {
+      store.appendTelemetry(record);
+    },
+  });
+  const rateLimiter = resolveRateLimiter(store);
+
+  return {
+    sessionPinner,
+    hardwareConfig: DEFAULT_OPERATOR_CONFIG.local,
+    systemInfoProvider: getDefaultSystemInfo,
+    localConfig: DEFAULT_LOCAL_CONFIG,
+    loopEscalationConfig: DEFAULT_OPERATOR_CONFIG.loop_escalation,
+    ...(hydraMatcher ? { hydraMatcher } : {}),
+    ...(rateLimiter ? { rateLimiter } : {}),
+    telemetryEmitter,
+  };
+}
+
+export async function rebuildFleet(
+  runtime: SmartRouterRuntime,
+  pi: ExtensionAPI,
+  cwd: string,
+  deps?: DiscoverFleetDeps,
+): Promise<void> {
+  const fingerprint = await computeCurrentFleetScopeFingerprint(runtime, cwd, deps);
+  const { fleet, catalog } = await discoverFleet(
+    runtime.modelRegistry,
+    runtime.fleetMode,
+    cwd,
+    runtime.store,
+    deps,
+  );
+  runtime.priceCatalog = catalog;
+  runtime.fleetScopeFingerprint = fingerprint;
+  const router = createRouterFromFleet(fleet, {
+    ...createDispatchOptions(runtime.store, runtime.sessionPinner, runtime.hydraMatcher),
+    lifecycleHookState: runtime.lifecycleHookState,
+  });
+  router.register(createHooksAdapter(pi));
+  runtime.streamDeps.router = router;
+  runtime.streamDeps.fleet = fleet;
+}
+
+/**
+ * Rebuild fleet only when scope fingerprint changed (mode, enabledModels, registry, pricing).
+ */
+export async function ensureFleetFresh(
+  runtime: SmartRouterRuntime,
+  pi: ExtensionAPI,
+  cwd: string,
+  deps?: DiscoverFleetDeps,
+): Promise<void> {
+  const fingerprint = await computeCurrentFleetScopeFingerprint(runtime, cwd, deps);
+  if (fingerprint === runtime.fleetScopeFingerprint) {
+    return;
+  }
+  await rebuildFleet(runtime, pi, cwd, deps);
+}
+
+/**
+ * Optional HyDRA matcher bootstrap.
+ *
+ * Requires `@huggingface/transformers` at runtime (see root package.json).
+ * Install: `npm i @huggingface/transformers`
+ *
+ * pi exposes no extension teardown hook — ONNX provider dispose is a no-op.
+ */
+export interface HydraInitDeps {
+  readonly createOnnxEmbeddingProvider?: typeof createOnnxEmbeddingProvider;
+}
+
+export async function initHydraMatcher(
+  deps?: HydraInitDeps,
+): Promise<HydraMatcher | undefined> {
+  const createProvider = deps?.createOnnxEmbeddingProvider ?? createOnnxEmbeddingProvider;
+  const artifactCachePath = DEFAULT_OPERATOR_CONFIG.hydra.artifact_cache_path;
+
+  try {
+    const provider = await createProvider(artifactCachePath);
+    return new HydraMatcher(provider, { artifactCachePath });
+  } catch (error) {
+    console.warn(
+      '[smart-router] HyDRA matcher disabled',
+      error instanceof Error ? error.message : String(error),
+    );
+    return undefined;
+  }
+}