@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-harness-model-routing.ts

@@ -1,175 +1,17 @@
+import { arch, cpus, freemem, platform, totalmem } from 'node:os';
+import type { ArtifactDescriptor } from '@pellux/goodvibes-sdk/platform/artifacts';
 import type { CommandContext } from '../input/command-registry.ts';
 import { requireProviderApi } from '../input/commands/runtime-services.ts';
 import { previewHarnessText } from './agent-harness-text.ts';
-
-export interface AgentHarnessModelRoutingArgs {
-  readonly modelRouteId?: unknown;
-  readonly target?: unknown;
-  readonly query?: unknown;
-  readonly includeParameters?: unknown;
-  readonly limit?: unknown;
-}
-
-type ModelRouteResolution =
-  | { readonly status: 'found'; readonly route: Record<string, unknown> }
-  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
-  | { readonly status: 'missing_lookup'; readonly usage: string };
-
-type ModelRouteLookupSource = 'modelRouteId' | 'target' | 'query';
-
-interface ModelCandidate {
-  readonly kind: 'model';
-  readonly id: string;
-  readonly registryKey: string;
-  readonly modelId: string;
-  readonly providerId: string;
-  readonly displayName: string;
-  readonly current: boolean;
-  readonly contextWindow: number | null;
-  readonly reasoningEffort: readonly string[];
-  readonly capabilities: unknown;
-  readonly pinned: boolean;
-}
-
-interface RouteCandidate {
-  readonly kind: 'route';
-  readonly id: string;
-  readonly label: string;
-  readonly detail: string;
-  readonly currentValue: unknown;
-  readonly settingKeys: readonly string[];
-  readonly commands: readonly string[];
-  readonly uiSurfaces: readonly string[];
-}
-
-interface ProviderApiLike {
-  readonly getFavorites: () => Promise<unknown>;
-  readonly getCurrentModel: () => Promise<unknown>;
-  readonly listModels: (options?: { readonly selectableOnly?: boolean }) => Promise<readonly unknown[]>;
-  readonly listProviderIds: () => readonly string[];
-}
-
-function readString(value: unknown): string {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-function readLimit(value: unknown, fallback: number): number {
-  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
-  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
-  return Math.max(1, Math.min(500, Math.trunc(parsed)));
-}
-
-function readRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === 'object' ? value as Record<string, unknown> : {};
-}
-
-function readStringArray(value: unknown): readonly string[] {
-  return Array.isArray(value) ? value.map((entry) => readString(entry)).filter(Boolean) : [];
-}
-
-function readConfig(context: CommandContext, key: string): unknown {
-  try {
-    return (context.platform.configManager as { get(settingKey: string): unknown }).get(key);
-  } catch {
-    return undefined;
-  }
-}
-
-function contextWindowFor(context: CommandContext, model: unknown): number | null {
-  try {
-    const registry = context.provider.providerRegistry as { getContextWindowForModel(candidate: unknown): number };
-    const value = registry.getContextWindowForModel(model);
-    return typeof value === 'number' && Number.isFinite(value) ? value : null;
-  } catch {
-    return null;
-  }
-}
-
-function modelRegistryKey(model: unknown): string {
-  const record = readRecord(model);
-  return readString(record.registryKey) || readString(record.id) || readString(record.modelId);
-}
-
-function modelProviderId(model: unknown): string {
-  const record = readRecord(model);
-  return readString(record.providerId) || readString(record.provider);
-}
-
-function modelModelId(model: unknown): string {
-  const record = readRecord(model);
-  return readString(record.modelId) || readString(record.id) || modelRegistryKey(model);
-}
-
-function modelDisplayName(model: unknown): string {
-  const record = readRecord(model);
-  return readString(record.displayName) || readString(record.name) || modelRegistryKey(model);
-}
-
-function modelCurrent(model: unknown): boolean {
-  const record = readRecord(model);
-  return record.current === true;
-}
-
-function modelReasoning(model: unknown): readonly string[] {
-  const record = readRecord(model);
-  return readStringArray(record.reasoningEffort);
-}
-
-function modelCapabilities(model: unknown): unknown {
-  return readRecord(model).capabilities ?? null;
-}
-
-function readProviderApi(context: CommandContext): ProviderApiLike | null {
-  try {
-    return requireProviderApi(context) as ProviderApiLike;
-  } catch {
-    return null;
-  }
-}
-
-async function loadPinnedModelIds(context: CommandContext): Promise<ReadonlySet<string>> {
-  const providerApi = readProviderApi(context);
-  if (!providerApi) return new Set();
-  try {
-    const favorites = await providerApi.getFavorites();
-    const pinned = readRecord(favorites).pinned;
-    if (!Array.isArray(pinned)) return new Set();
-    return new Set(pinned.flatMap((entry) => {
-      const record = readRecord(entry);
-      return [readString(record.registryKey), readString(record.modelId)].filter(Boolean);
-    }));
-  } catch {
-    return new Set();
-  }
-}
-
-async function loadModels(context: CommandContext): Promise<readonly ModelCandidate[]> {
-  const providerApi = readProviderApi(context);
-  if (!providerApi) return [];
-  const pinned = await loadPinnedModelIds(context);
-  const models = await providerApi.listModels({ selectableOnly: true });
-  return models.map((model) => {
-    const registryKey = modelRegistryKey(model);
-    const modelId = modelModelId(model);
-    return {
-      kind: 'model',
-      id: registryKey,
-      registryKey,
-      modelId,
-      providerId: modelProviderId(model),
-      displayName: modelDisplayName(model),
-      current: modelCurrent(model) || registryKey === context.session.runtime.model,
-      contextWindow: contextWindowFor(context, model),
-      reasoningEffort: modelReasoning(model),
-      capabilities: modelCapabilities(model),
-      pinned: pinned.has(registryKey) || pinned.has(modelId),
-    };
-  });
-}
-
-function listProviderIds(context: CommandContext): readonly string[] {
-  return readProviderApi(context)?.listProviderIds() ?? [];
-}
+import { localModelCookbook } from './agent-harness-local-model-cookbook.ts';
+import { collectLocalServerEndpointCandidates, describeLocalServerEndpoint, localModelDetection, localModelServerHealthMap, runLocalModelServerSmoke } from './agent-harness-local-model-endpoints.ts';
+import { localHardwareProfile, modelReadinessScore } from './agent-harness-model-readiness.ts';
+import { contextWindowFor, loadModels, listProviderIds, modelBenchmarkCompositeScore, modelBenchmarkQualityTier, modelCapabilities, modelCurrent, modelDisplayName, modelModelId, modelProviderId, modelReasoning, modelRegistryKey, modelTier, readConfig, readProviderApi } from './agent-harness-model-catalog.ts';
+import type { AgentHarnessModelRoutingArgs, LocalModelServerEndpoint, ModelCandidate, ModelProviderHealthSignal, ModelRouteLookupSource, ModelRouteResolution, RouteCandidate } from './agent-harness-model-routing-types.ts';
+import { readLimit, readString } from './agent-harness-model-routing-utils.ts';
+export type { AgentHarnessModelRoutingArgs } from './agent-harness-model-routing-types.ts';
+export { localModelCookbook } from './agent-harness-local-model-cookbook.ts';
+export { runLocalModelServerSmoke } from './agent-harness-local-model-endpoints.ts';
 
 async function readCurrentModel(context: CommandContext): Promise<unknown> {
   try {
@@ -253,6 +95,20 @@ function routeCandidates(context: CommandContext): readonly RouteCandidate[] {
       commands: ['/refresh-models'],
       uiSurfaces: ['model-picker'],
     },
+    {
+      kind: 'route',
+      id: 'local-model-cookbook',
+      label: 'Local model cookbook',
+      detail: 'Hardware-aware recommendations for Ollama, llama.cpp, vLLM, and local OpenAI-compatible servers.',
+      currentValue: {
+        detected: localModelDetection(context),
+        hardwareProfile: localHardwareProfile(),
+        localServerHealth: localModelServerHealthMap(context, false),
+      },
+      settingKeys: [],
+      commands: ['/provider add <name> <baseURL> [apiKey] --yes', '/refresh-models', '/model'],
+      uiSurfaces: ['provider-picker', 'model-picker', 'settings'],
+    },
     {
       kind: 'route',
       id: 'pinned-models',
@@ -310,7 +166,39 @@ function modelSearchText(model: ModelCandidate): string {
   ].join('\n').toLowerCase();
 }
 
-function describeRoute(route: RouteCandidate, options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {}): Record<string, unknown> {
+function localEndpointSearchText(endpoint: LocalModelServerEndpoint): string {
+  return [
+    endpoint.id,
+    endpoint.providerId ?? '',
+    endpoint.stack ?? '',
+    endpoint.baseUrl,
+    endpoint.modelsUrl,
+    endpoint.diagnosticStatus,
+    ...endpoint.sources,
+    ...endpoint.sourceDetails,
+    ...endpoint.modelRoutes,
+    ...endpoint.notes,
+  ].join('\n').toLowerCase();
+}
+
+function describeLocalServerEndpointRoute(endpoint: LocalModelServerEndpoint, lookup?: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...endpoint,
+    ...(lookup ? { lookup } : {}),
+    modelRouteId: endpoint.id,
+    label: `Local model server ${endpoint.baseUrl}`,
+    modelRoute: endpoint.inspectRoute,
+    modelAccess: {
+      smoke: endpoint.smokeRoute,
+      refresh: endpoint.refreshRoute,
+      addProvider: endpoint.addProviderRoute,
+      cookbook: 'models action:"local" includeParameters:true',
+    },
+    policy: endpoint.diagnostics?.policy ?? 'Read-only local model endpoint inspection. The smoke test, refresh, provider add, benchmark, and route changes remain separate visible confirmed actions.',
+  };
+}
+
+function describeRoute(route: RouteCandidate, options: { readonly context: CommandContext; readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> }): Record<string, unknown> {
   return {
     kind: 'route',
     modelRouteId: route.id,
@@ -324,6 +212,7 @@ function describeRoute(route: RouteCandidate, options: { readonly includeParamet
       uiSurfaces: route.uiSurfaces,
     } : {}),
     ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(route.id === 'local-model-cookbook' && options.includeParameters === true ? { localCookbook: localModelCookbook(options.context, true) } : {}),
     ...(options.includeParameters ? {
       policy: {
         effect: 'read-only',
@@ -331,10 +220,10 @@ function describeRoute(route: RouteCandidate, options: { readonly includeParamet
         mutation: 'Model/provider selection, catalog refresh, favorites, custom provider edits, and route setting changes stay explicit user-facing picker, settings, workspace, or slash-command flows.',
       },
       modelAccess: {
-        inspectRouting: 'agent_harness mode:"model_routing"',
+        inspectRouting: 'models action:"status"',
         inspectRoute: 'agent_harness mode:"model_route"',
-        settingRead: 'agent_harness mode:"get_setting"',
-        settingMutation: 'agent_harness mode:"set_setting" confirm:true explicitUserRequest:"..."',
+        settingRead: 'settings action:"get"',
+        settingMutation: 'settings action:"set" confirm:true explicitUserRequest:"..."',
         openModelPicker: 'agent_harness mode:"open_ui_surface" surfaceId:"model-picker" confirm:true explicitUserRequest:"..."',
         openProviderPicker: 'agent_harness mode:"open_ui_surface" surfaceId:"provider-picker" confirm:true explicitUserRequest:"..."',
       },
@@ -342,7 +231,21 @@ function describeRoute(route: RouteCandidate, options: { readonly includeParamet
   };
 }
 
-function describeModel(model: ModelCandidate, options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {}): Record<string, unknown> {
+function compactProviderHealthSignal(signal: ModelProviderHealthSignal): Record<string, unknown> {
+  return {
+    status: signal.status,
+    sdkContract: signal.sdkContract,
+    daemonPublication: signal.daemonPublication,
+    agentConsumption: signal.agentConsumption,
+    ...(signal.healthStatus ? { healthStatus: signal.healthStatus } : {}),
+    ...(signal.avgLatencyMs !== undefined ? { avgLatencyMs: signal.avgLatencyMs } : {}),
+    missingSignals: signal.missingSignals,
+    policy: signal.policy,
+  };
+}
+
+function describeModel(model: ModelCandidate, options: { readonly context: CommandContext; readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> }): Record<string, unknown> {
+  const readiness = modelReadinessScore(options.context, model);
   return {
     kind: 'model',
     modelRouteId: model.registryKey,
@@ -354,6 +257,20 @@ function describeModel(model: ModelCandidate, options: { readonly includeParamet
     pinned: model.pinned,
     contextWindow: model.contextWindow,
     reasoningEffort: model.reasoningEffort,
+    tier: model.tier ?? null,
+    benchmarkCompositeScore: model.benchmarkCompositeScore ?? null,
+    benchmarkQualityTier: model.benchmarkQualityTier ?? null,
+    readinessScore: readiness.score,
+    readinessLevel: readiness.level,
+    readiness: options.includeParameters
+      ? readiness
+      : {
+        score: readiness.score,
+        level: readiness.level,
+        confidence: readiness.confidence,
+        providerHealth: compactProviderHealthSignal(readiness.providerHealth),
+        nextStep: readiness.nextStep,
+      },
     modelRoute: modelCandidateModelRoute(),
     ...(options.lookup ? { lookup: options.lookup } : {}),
     ...(options.includeParameters ? {
@@ -367,7 +284,7 @@ function describeModel(model: ModelCandidate, options: { readonly includeParamet
         selectProviderCommand: `/provider ${model.providerId}`,
         pinCommand: `/pin ${model.registryKey}`,
         unpinCommand: `/unpin ${model.registryKey}`,
-        setMainModel: `agent_harness mode:"set_setting" key:"provider.model" value:"${model.registryKey}" confirm:true explicitUserRequest:"..."`,
+        setMainModel: `settings action:"set" key:"provider.model" value:"${model.registryKey}" confirm:true explicitUserRequest:"..."`,
       },
     } : {}),
   };
@@ -393,8 +310,19 @@ function describeCandidate(entry: RouteCandidate | ModelCandidate): Record<strin
   };
 }
 
+function describeEndpointCandidate(endpoint: LocalModelServerEndpoint): Record<string, unknown> {
+  return {
+    kind: endpoint.kind,
+    modelRouteId: endpoint.id,
+    baseUrl: endpoint.baseUrl,
+    stack: endpoint.stack,
+    diagnosticStatus: endpoint.diagnosticStatus,
+    modelRoute: endpoint.inspectRoute,
+  };
+}
+
 function modelRoutingModelRoute(): string {
-  return 'agent_harness mode:"model_route" or mode:"run_command"';
+  return 'models action:"route" or action:"smoke"';
 }
 
 function modelCandidateModelRoute(): string {
@@ -447,12 +375,16 @@ export async function modelRoutingSummary(context: CommandContext, args: AgentHa
         contextWindow: contextWindowFor(context, currentModel),
         reasoningEffort: modelReasoning(currentModel),
         capabilities: modelCapabilities(currentModel),
+        tier: modelTier(currentModel),
+        benchmarkCompositeScore: modelBenchmarkCompositeScore(currentModel),
+        benchmarkQualityTier: modelBenchmarkQualityTier(currentModel),
         pinned: false,
-      }, { includeParameters }) : null,
+      }, { context, includeParameters }) : null,
     },
     providers: providerIds,
-    routes: filteredRoutes.slice(0, limit).map((route) => describeRoute(route, { includeParameters })),
-    models: filteredModels.slice(0, limit).map((model) => describeModel(model, { includeParameters })),
+    localCookbook: localModelCookbook(context, includeParameters),
+    routes: filteredRoutes.slice(0, limit).map((route) => describeRoute(route, { context, includeParameters })),
+    models: filteredModels.slice(0, limit).map((model) => describeModel(model, { context, includeParameters })),
     returned: {
       routes: Math.min(filteredRoutes.length, limit),
       models: Math.min(filteredModels.length, limit),
@@ -475,42 +407,57 @@ export async function describeHarnessModelRoute(context: CommandContext, args: A
   if (!lookup) {
     return {
       status: 'missing_lookup',
-      usage: 'model_route requires modelRouteId, target, or query. Use mode:"model_routing" to inspect route and model ids.',
+      usage: 'model_route requires modelRouteId, target, or query. Prefer models action:"status" to inspect route, model, and local endpoint ids.',
     };
   }
   const [models] = await Promise.all([loadModels(context)]);
   const routes = routeCandidates(context);
+  const endpoints = collectLocalServerEndpointCandidates(context).map((endpoint) => describeLocalServerEndpoint(endpoint, true));
   const normalized = lookup.input.toLowerCase();
   const exactRoute = routes.find((route) => route.id === lookup.input);
-  if (exactRoute) return { status: 'found', route: describeRoute(exactRoute, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'route-id' } }) };
+  if (exactRoute) return { status: 'found', route: describeRoute(exactRoute, { context, includeParameters: true, lookup: { ...lookup, resolvedBy: 'route-id' } }) };
   const exactModel = models.find((model) => model.registryKey === lookup.input || model.modelId === lookup.input);
-  if (exactModel) return { status: 'found', route: describeModel(exactModel, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'model-id' } }) };
+  if (exactModel) return { status: 'found', route: describeModel(exactModel, { context, includeParameters: true, lookup: { ...lookup, resolvedBy: 'model-id' } }) };
+  const exactEndpoint = endpoints.find((endpoint) => endpoint.id === lookup.input || endpoint.baseUrl === lookup.input || endpoint.modelsUrl === lookup.input);
+  if (exactEndpoint) return { status: 'found', route: describeLocalServerEndpointRoute(exactEndpoint, { ...lookup, resolvedBy: 'local-endpoint-id' }) };
   const insensitiveRoute = routes.find((route) => route.id.toLowerCase() === normalized);
-  if (insensitiveRoute) return { status: 'found', route: describeRoute(insensitiveRoute, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-route-id' } }) };
+  if (insensitiveRoute) return { status: 'found', route: describeRoute(insensitiveRoute, { context, includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-route-id' } }) };
   const insensitiveModel = models.find((model) => model.registryKey.toLowerCase() === normalized || model.modelId.toLowerCase() === normalized);
-  if (insensitiveModel) return { status: 'found', route: describeModel(insensitiveModel, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-model-id' } }) };
+  if (insensitiveModel) return { status: 'found', route: describeModel(insensitiveModel, { context, includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-model-id' } }) };
+  const insensitiveEndpoint = endpoints.find((endpoint) => endpoint.id.toLowerCase() === normalized || endpoint.baseUrl.toLowerCase() === normalized || endpoint.modelsUrl.toLowerCase() === normalized);
+  if (insensitiveEndpoint) return { status: 'found', route: describeLocalServerEndpointRoute(insensitiveEndpoint, { ...lookup, resolvedBy: 'case-insensitive-local-endpoint-id' }) };
   const searched = [
     ...routes.filter((route) => routeSearchText(route).includes(normalized)),
     ...models.filter((model) => modelSearchText(model).includes(normalized)),
   ];
-  if (searched.length === 1) {
+  const searchedEndpoints = endpoints.filter((endpoint) => localEndpointSearchText(endpoint).includes(normalized));
+  if (searched.length === 0 && searchedEndpoints.length === 1) {
+    return {
+      status: 'found',
+      route: describeLocalServerEndpointRoute(searchedEndpoints[0]!, { ...lookup, resolvedBy: 'local-endpoint-search' }),
+    };
+  }
+  if (searched.length === 1 && searchedEndpoints.length === 0) {
     const found = searched[0]!;
     return {
       status: 'found',
       route: found.kind === 'route'
-        ? describeRoute(found, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } })
-        : describeModel(found, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }),
+        ? describeRoute(found, { context, includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } })
+        : describeModel(found, { context, includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }),
     };
   }
-  if (searched.length > 1) {
+  if (searched.length + searchedEndpoints.length > 1) {
     return {
       status: 'ambiguous',
       input: lookup.input,
-      candidates: searched.slice(0, 8).map(describeCandidate),
+      candidates: [
+        ...searched.slice(0, 8).map(describeCandidate),
+        ...searchedEndpoints.slice(0, Math.max(0, 8 - searched.length)).map(describeEndpointCandidate),
+      ],
     };
   }
   return {
     status: 'missing_lookup',
-    usage: `Unknown model route ${lookup.input}. Use mode:"model_routing" to inspect route and model ids.`,
+    usage: `Unknown model route ${lookup.input}. Prefer models action:"status" to inspect route, model, and local endpoint ids.`,
   };
 }