@pellux/goodvibes-agent 1.1.6 → 1.2.0

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

@@ -0,0 +1,406 @@
+import { arch, cpus, freemem, platform, totalmem } from 'node:os';
+import type { CommandContext } from '../input/command-registry.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+import { readProviderHealthSignal } from './agent-harness-model-provider-health.ts';
+import { localStackFor } from './agent-harness-local-model-endpoints.ts';
+import type { LocalModelBenchmarkEvidence, LocalModelDetection, LocalModelHardwareProfile, LocalModelRecipe, LocalModelRecipeFit, ModelCandidate, ModelReadinessDimension, ModelReadinessScore, ModelRouteReadinessScore, ModelProviderHealthSignal } from './agent-harness-model-routing-types.ts';
+import { readRecord } from './agent-harness-model-routing-utils.ts';
+
+export function localRecipeStackId(recipe: LocalModelRecipe): string {
+  return recipe.id === 'openai-compatible-local' ? 'openai-compatible' : recipe.id === 'llama-cpp' ? 'llama.cpp' : recipe.id;
+}
+
+export function roundGb(bytes: number): number {
+  if (!Number.isFinite(bytes) || bytes <= 0) return 0;
+  return Math.max(0, Math.round((bytes / 1024 / 1024 / 1024) * 10) / 10);
+}
+
+export function localHardwareProfile(): LocalModelHardwareProfile {
+  const cpuList = cpus();
+  const ramGb = roundGb(totalmem());
+  const freeRamGb = roundGb(freemem());
+  const runtimePlatform = platform();
+  const runtimeArch = arch();
+  const acceleratorHint = runtimePlatform === 'darwin' && runtimeArch === 'arm64'
+    ? 'apple-silicon'
+    : (process.env.CUDA_VISIBLE_DEVICES || process.env.NVIDIA_VISIBLE_DEVICES)
+      ? 'cuda-env'
+      : 'none-detected';
+  return {
+    platform: runtimePlatform,
+    arch: runtimeArch,
+    cpuModel: previewHarnessText(cpuList[0]?.model ?? 'unknown CPU', 96),
+    cpuThreads: cpuList.length,
+    ramGb,
+    freeRamGb,
+    memoryTier: ramGb >= 64 ? 'large' : ramGb >= 32 ? 'comfortable' : ramGb >= 16 ? 'starter' : 'constrained',
+    acceleratorHint,
+    privacy: 'local-only',
+    caveat: 'Hardware scan uses local OS memory/CPU data and safe accelerator hints only; it does not probe drivers, download models, or benchmark live inference.',
+  };
+}
+
+export function fitLevel(score: number): LocalModelRecipeFit['level'] {
+  if (score >= 85) return 'strong';
+  if (score >= 70) return 'good';
+  if (score >= 50) return 'usable';
+  return 'weak';
+}
+
+export function clampFit(score: number): number {
+  return Math.max(0, Math.min(100, Math.round(score)));
+}
+
+export function modelReadinessLevel(score: number): ModelReadinessScore['level'] {
+  if (score >= 85) return 'excellent';
+  if (score >= 70) return 'good';
+  if (score >= 50) return 'usable';
+  return 'risky';
+}
+
+export function capabilityEnabled(capabilities: unknown, key: 'toolCalling' | 'multimodal'): boolean | null {
+  const value = readRecord(capabilities)[key];
+  if (typeof value === 'boolean') return value;
+  return null;
+}
+
+export function isLocalCandidate(fields: readonly string[]): boolean {
+  return fields.some((field) => Boolean(localStackFor(field)));
+}
+
+export function contextWindowScore(contextWindow: number | null): ModelReadinessDimension {
+  const score = contextWindow == null
+    ? 45
+    : contextWindow >= 128_000
+      ? 100
+      : contextWindow >= 64_000
+        ? 88
+        : contextWindow >= 32_000
+          ? 76
+          : contextWindow >= 16_000
+            ? 62
+            : 45;
+  return {
+    id: 'context-window',
+    label: 'Context window',
+    score,
+    weight: 20,
+    summary: contextWindow == null
+      ? 'No context-window metadata; inspect the provider route before long-context work.'
+      : `${contextWindow.toLocaleString()} token context window.`,
+  };
+}
+
+export function toolSupportScore(capabilities: unknown): ModelReadinessDimension {
+  const enabled = capabilityEnabled(capabilities, 'toolCalling');
+  return {
+    id: 'tool-support',
+    label: 'Tool support',
+    score: enabled === true ? 100 : enabled === false ? 35 : 55,
+    weight: 20,
+    summary: enabled === true
+      ? 'Tool calling is advertised.'
+      : enabled === false
+        ? 'Tool calling is not advertised; use for chat or drafting, not autonomous tool workflows.'
+        : 'Tool-calling support is unknown; inspect the provider before tool-heavy work.',
+  };
+}
+
+export function visionScore(capabilities: unknown): ModelReadinessDimension {
+  const enabled = capabilityEnabled(capabilities, 'multimodal');
+  return {
+    id: 'vision',
+    label: 'Vision',
+    score: enabled === true ? 100 : enabled === false ? 45 : 55,
+    weight: 10,
+    summary: enabled === true
+      ? 'Vision or multimodal input is advertised.'
+      : enabled === false
+        ? 'Vision is not advertised; avoid image/screen-heavy work on this route.'
+        : 'Vision support is unknown.',
+  };
+}
+
+export function costScore(tier: string | undefined, local: boolean): ModelReadinessDimension {
+  const normalized = (tier ?? '').toLowerCase();
+  const score = local
+    ? 100
+    : normalized === 'free'
+      ? 95
+      : normalized === 'subscription'
+        ? 86
+        : normalized === 'standard'
+          ? 72
+          : normalized === 'premium'
+            ? 55
+            : 62;
+  return {
+    id: 'cost',
+    label: 'Cost',
+    score,
+    weight: 15,
+    summary: local
+      ? 'Local route; marginal token cost is user hardware and power.'
+      : tier
+        ? `${tier} tier route.`
+        : 'Cost tier is unknown; inspect provider pricing before long runs.',
+  };
+}
+
+export function privacyScore(local: boolean, providerId: string): ModelReadinessDimension {
+  const normalized = providerId.toLowerCase();
+  const score = local
+    ? 100
+    : /subscription|account|openrouter|openai|anthropic|google|gemini|xai|mistral|cohere/.test(normalized)
+      ? 48
+      : 60;
+  return {
+    id: 'privacy',
+    label: 'Privacy',
+    score,
+    weight: 15,
+    summary: local
+      ? 'Local/private route detected.'
+      : 'Cloud/provider route; treat sensitive data according to provider policy.',
+  };
+}
+
+export function latencyScore(
+  local: boolean,
+  benchmarkCompositeScore: number | null | undefined,
+  providerHealth: ModelProviderHealthSignal,
+): ModelReadinessDimension {
+  const liveLatency = providerHealth.status === 'record-found' ? providerHealth.avgLatencyMs : undefined;
+  if (liveLatency !== undefined) {
+    const score = liveLatency <= 750
+      ? 95
+      : liveLatency <= 1500
+        ? 86
+        : liveLatency <= 3000
+          ? 72
+          : 55;
+    const details = [
+      `Live provider-health latency is ${liveLatency} ms`,
+      ...(providerHealth.minLatencyMs !== undefined || providerHealth.maxLatencyMs !== undefined
+        ? [`range ${providerHealth.minLatencyMs ?? '?'}-${providerHealth.maxLatencyMs ?? '?'} ms`]
+        : []),
+      ...(providerHealth.healthStatus ? [`provider status ${providerHealth.healthStatus}`] : []),
+      ...(providerHealth.lastErrorMessage ? [`last error: ${providerHealth.lastErrorMessage}`] : []),
+    ];
+    return {
+      id: 'latency',
+      label: 'Latency',
+      score,
+      weight: 20,
+      summary: `${details.join('; ')}.`,
+    };
+  }
+
+  const score = local
+    ? 55
+    : benchmarkCompositeScore != null
+      ? 78
+      : 70;
+  return {
+    id: 'latency',
+    label: 'Latency',
+    score,
+    weight: 20,
+    summary: local
+      ? 'Local latency is unmeasured until the user runs the benchmark prompt on this machine.'
+      : benchmarkCompositeScore != null
+        ? 'No daemon-published provider-health latency is reachable; benchmark metadata is quality context only.'
+        : 'No daemon-published provider-health latency is reachable; assume normal provider latency until measured.',
+  };
+}
+
+export function weightedReadiness(dimensions: readonly ModelReadinessDimension[]): number {
+  const totalWeight = dimensions.reduce((total, dimension) => total + dimension.weight, 0);
+  if (totalWeight <= 0) return 0;
+  return clampFit(dimensions.reduce((total, dimension) => total + (dimension.score * dimension.weight), 0) / totalWeight);
+}
+
+export function modelReadinessScore(context: CommandContext, model: ModelCandidate): ModelRouteReadinessScore {
+  const local = isLocalCandidate([model.providerId, model.registryKey, model.modelId, model.displayName]);
+  const providerHealth = readProviderHealthSignal(context, model.providerId);
+  const dimensions: readonly ModelReadinessDimension[] = [
+    latencyScore(local, model.benchmarkCompositeScore, providerHealth),
+    contextWindowScore(model.contextWindow),
+    toolSupportScore(model.capabilities),
+    visionScore(model.capabilities),
+    costScore(model.tier, local),
+    privacyScore(local, model.providerId),
+  ];
+  const score = weightedReadiness(dimensions);
+  const hasLiveLatency = providerHealth.status === 'record-found' && providerHealth.avgLatencyMs !== undefined;
+  const missingSignals = [
+    ...providerHealth.missingSignals,
+    ...(hasLiveLatency ? [] : ['No live latency benchmark has been recorded for this Agent route.']),
+    ...(model.contextWindow == null ? ['Context-window metadata is missing.'] : []),
+    ...(capabilityEnabled(model.capabilities, 'toolCalling') == null ? ['Tool-calling support is unknown.'] : []),
+    ...(capabilityEnabled(model.capabilities, 'multimodal') == null ? ['Vision support is unknown.'] : []),
+    ...(!model.tier && !local ? ['Cost tier is unknown.'] : []),
+  ];
+  return {
+    score,
+    level: modelReadinessLevel(score),
+    confidence: providerHealth.status === 'record-found' && missingSignals.length === 0
+      ? 'provider-health-backed'
+      : missingSignals.length === 0
+        ? 'metadata-backed'
+        : 'estimated',
+    dimensions,
+    missingSignals,
+    providerHealth,
+    nextStep: local
+      ? 'Run the local benchmark prompt before making this route the default.'
+      : providerHealth.status === 'record-found'
+        ? 'Use provider-health-backed route posture for triage; run a task-specific comparison before changing the default model.'
+        : 'Use this score for routing triage; wait for daemon provider-health publication or run a task-specific comparison before changing the default model.',
+  };
+}
+
+export function localRecipeReadinessScore(
+  recipe: LocalModelRecipe,
+  fit: LocalModelRecipeFit,
+  detected: boolean,
+  evidence: LocalModelBenchmarkEvidence,
+): ModelReadinessScore {
+  const contextScore = recipe.id === 'vllm' ? 70 : recipe.id === 'openai-compatible-local' ? 60 : 65;
+  const toolScore = recipe.id === 'ollama' || recipe.id === 'openai-compatible-local' ? 70 : 55;
+  const visionSupport = recipe.modelExamples.some((model) => /vision|vl|multimodal/i.test(model));
+  const reviewedWinner = evidence.winnerStacks.includes(localRecipeStackId(recipe));
+  const measured = evidence.comparisonCount > 0;
+  const dimensions: readonly ModelReadinessDimension[] = [
+    {
+      id: 'latency',
+      label: 'Latency',
+      score: reviewedWinner ? 82 : measured ? 68 : detected ? 62 : 50,
+      weight: 20,
+      summary: reviewedWinner
+        ? 'A revealed saved local benchmark judgment selected this stack.'
+        : measured
+          ? 'A saved local benchmark comparison exists, but no revealed winner is tied to this stack yet.'
+          : detected
+            ? 'Local stack is detected, but latency still needs an on-machine benchmark.'
+            : 'Latency is unknown until the local server and model are running.',
+    },
+    {
+      id: 'context-window',
+      label: 'Context window',
+      score: contextScore,
+      weight: 20,
+      summary: 'Depends on the selected local model and serving stack; verify after the route is available.',
+    },
+    {
+      id: 'tool-support',
+      label: 'Tool support',
+      score: toolScore,
+      weight: 20,
+      summary: 'Tool behavior depends on the selected local model and OpenAI-compatible server support.',
+    },
+    {
+      id: 'vision',
+      label: 'Vision',
+      score: visionSupport ? 75 : 45,
+      weight: 10,
+      summary: visionSupport ? 'Example list includes a vision-capable route.' : 'No vision route is assumed for this local recipe.',
+    },
+    {
+      id: 'cost',
+      label: 'Cost',
+      score: 100,
+      weight: 15,
+      summary: 'Local route; marginal token cost is user hardware and power.',
+    },
+    {
+      id: 'privacy',
+      label: 'Privacy',
+      score: 100,
+      weight: 15,
+      summary: 'Local route can keep prompts on user-controlled hardware.',
+    },
+  ];
+  const score = clampFit((weightedReadiness(dimensions) * 0.72) + (fit.score * 0.28));
+  return {
+    score,
+    level: modelReadinessLevel(score),
+    confidence: reviewedWinner ? 'measured' : 'estimated',
+    dimensions,
+    missingSignals: [
+      ...(measured ? [] : ['No live latency benchmark has been recorded for this local recipe.']),
+      ...(reviewedWinner ? [] : ['No revealed local benchmark judgment has selected this recipe yet.']),
+      'Context window, tool support, and vision support depend on the exact model served.',
+    ],
+    nextStep: reviewedWinner
+      ? 'Review the saved benchmark judgment, then use a separate confirmed apply/update route only if the user wants this winner as the default.'
+      : measured
+        ? 'Review the saved comparison and save a revealed judgment before recommending a default-model change.'
+        : 'Start the local server, refresh models, then run the setupPlan benchmark action before changing the default model.',
+  };
+}
+
+export function scoreLocalModelRecipe(
+  recipe: LocalModelRecipe,
+  hardware: LocalModelHardwareProfile,
+  detection: LocalModelDetection,
+): LocalModelRecipeFit {
+  const stackId = localRecipeStackId(recipe);
+  const detected = detection.stacks.includes(stackId);
+  const reasons: string[] = [];
+  let score = 45;
+  if (detected) {
+    score += 18;
+    reasons.push('matching local provider or model route already detected');
+  }
+  if (recipe.id === 'ollama') {
+    score += 20;
+    reasons.push('lowest setup friction for most local users');
+    if (hardware.ramGb >= 16) {
+      score += 12;
+      reasons.push(`${hardware.ramGb} GB RAM is enough for practical 7B/8B quantized models`);
+    } else {
+      score -= 10;
+      reasons.push('RAM is below the comfortable 16 GB local-model baseline');
+    }
+    if (hardware.acceleratorHint === 'apple-silicon') {
+      score += 10;
+      reasons.push('Apple Silicon is a good Ollama path');
+    }
+  } else if (recipe.id === 'llama-cpp') {
+    score += 16;
+    reasons.push('best offline fallback when downloads and serving stay manual');
+    if (hardware.ramGb >= 8) {
+      score += 10;
+      reasons.push('can use smaller GGUF quantized models within available system memory');
+    }
+    if (hardware.acceleratorHint === 'apple-silicon') {
+      score += 8;
+      reasons.push('Metal-backed llama.cpp is a strong local path on Apple Silicon');
+    }
+  } else if (recipe.id === 'vllm') {
+    score += hardware.acceleratorHint === 'cuda-env' ? 30 : -12;
+    reasons.push(hardware.acceleratorHint === 'cuda-env'
+      ? 'CUDA environment hints are present'
+      : 'no CUDA hint was detected; vLLM may still work, but requires GPU/driver verification');
+    if (hardware.ramGb >= 32) {
+      score += 10;
+      reasons.push('system memory is comfortable for GPU serving overhead');
+    }
+  } else {
+    score += detected ? 10 : 4;
+    reasons.push(detected
+      ? 'existing OpenAI-compatible local route can be reused'
+      : 'useful when the user already runs LM Studio, LocalAI, TGI, or another local endpoint');
+  }
+  if (hardware.cpuThreads >= 8 && recipe.id !== 'vllm') {
+    score += 5;
+    reasons.push(`${hardware.cpuThreads} CPU threads help local inference`);
+  }
+  const finalScore = clampFit(score);
+  return {
+    score: finalScore,
+    level: fitLevel(finalScore),
+    reasons,
+  };
+}

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

@@ -0,0 +1,266 @@
+import type { ArtifactDescriptor } from '@pellux/goodvibes-sdk/platform/artifacts';
+
+export interface AgentHarnessModelRoutingArgs {
+  readonly modelRouteId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly fields?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+  readonly timeoutMs?: unknown;
+}
+
+export 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 };
+
+export type ModelRouteLookupSource = 'modelRouteId' | 'target' | 'query';
+
+export 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 tier?: string;
+  readonly benchmarkCompositeScore?: number | null;
+  readonly benchmarkQualityTier?: string;
+  readonly pinned: boolean;
+}
+
+export 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[];
+}
+
+export interface LocalModelDetection {
+  readonly providerIds: readonly string[];
+  readonly modelRoutes: readonly string[];
+  readonly stacks: readonly string[];
+}
+
+export interface LocalModelHardwareProfile {
+  readonly platform: string;
+  readonly arch: string;
+  readonly cpuModel: string;
+  readonly cpuThreads: number;
+  readonly ramGb: number;
+  readonly freeRamGb: number;
+  readonly memoryTier: 'constrained' | 'starter' | 'comfortable' | 'large';
+  readonly acceleratorHint: 'apple-silicon' | 'cuda-env' | 'none-detected';
+  readonly privacy: 'local-only';
+  readonly caveat: string;
+}
+
+export interface LocalModelRecipe {
+  readonly id: string;
+  readonly label: string;
+  readonly fit: string;
+  readonly bestFor: string;
+  readonly hardware: string;
+  readonly setup: readonly string[];
+  readonly modelExamples: readonly string[];
+  readonly cautions: readonly string[];
+}
+
+export interface LocalModelRecipeFit {
+  readonly score: number;
+  readonly level: 'weak' | 'usable' | 'good' | 'strong';
+  readonly reasons: readonly string[];
+}
+
+export interface ModelReadinessDimension {
+  readonly id: 'latency' | 'context-window' | 'tool-support' | 'vision' | 'cost' | 'privacy';
+  readonly label: string;
+  readonly score: number;
+  readonly weight: number;
+  readonly summary: string;
+}
+
+export interface ModelProviderHealthSignal {
+  readonly status: 'not-reachable-in-command-context' | 'read-model-empty' | 'read-model-error' | 'record-found';
+  readonly providerId: string;
+  readonly sdkContract: {
+    readonly providerHealthTypes: 'available';
+    readonly importSurface: string;
+    readonly note: string;
+  };
+  readonly daemonPublication: {
+    readonly status: 'not-published' | 'published-read-model';
+    readonly requiredPath: string;
+    readonly evidence: string;
+  };
+  readonly agentConsumption: {
+    readonly status: 'waiting-for-published-feed' | 'consumed';
+    readonly readModelPath: string | null;
+    readonly evidence: string;
+  };
+  readonly healthStatus?: string;
+  readonly isConfigured?: boolean;
+  readonly isActive?: boolean;
+  readonly avgLatencyMs?: number;
+  readonly minLatencyMs?: number;
+  readonly maxLatencyMs?: number;
+  readonly lastSuccessAt?: string | null;
+  readonly lastErrorAt?: string | null;
+  readonly lastErrorMessage?: string;
+  readonly lastCheckedAt?: string | null;
+  readonly rateLimitResetAt?: string | null;
+  readonly missingSignals: readonly string[];
+  readonly policy: string;
+}
+
+export interface ModelReadinessScore {
+  readonly score: number;
+  readonly level: 'risky' | 'usable' | 'good' | 'excellent';
+  readonly confidence: 'estimated' | 'metadata-backed' | 'provider-health-backed' | 'measured';
+  readonly dimensions: readonly ModelReadinessDimension[];
+  readonly missingSignals: readonly string[];
+  readonly providerHealth?: ModelProviderHealthSignal;
+  readonly nextStep: string;
+}
+
+export interface ModelRouteReadinessScore extends ModelReadinessScore {
+  readonly providerHealth: ModelProviderHealthSignal;
+}
+
+export interface LocalModelBenchmarkPlan {
+  readonly status: 'plan-ready';
+  readonly prompt: string;
+  readonly measurements: readonly string[];
+  readonly workspaceActionRoute: string;
+  readonly compareRoute: string;
+  readonly refreshRoute: string;
+  readonly notes: readonly string[];
+}
+
+export interface LocalModelBenchmarkWinner {
+  readonly judgmentArtifactId: string;
+  readonly sourceArtifactId: string | null;
+  readonly registryKey: string;
+  readonly stack: string | null;
+  readonly promptPreview: string;
+  readonly reviewRoute: string;
+  readonly exportRoute: string;
+  readonly applyRoute: string;
+}
+
+export interface LocalModelBenchmarkEvidence {
+  readonly status: 'unavailable' | 'unmeasured' | 'comparison-saved' | 'reviewed-winner';
+  readonly comparisonCount: number;
+  readonly completedCandidateCount: number;
+  readonly revealedJudgmentCount: number;
+  readonly hiddenJudgmentCount: number;
+  readonly winnerStacks: readonly string[];
+  readonly winnerModels: readonly LocalModelBenchmarkWinner[];
+  readonly summary: string;
+  readonly confidence: 'estimated' | 'measured';
+}
+
+export type LocalModelEndpointSource = 'provider-registry' | 'model-registry' | 'environment';
+
+export interface LocalModelServerEndpoint {
+  readonly kind: 'local-server-endpoint';
+  readonly id: string;
+  readonly providerId: string | null;
+  readonly stack: string | null;
+  readonly baseUrl: string;
+  readonly modelsUrl: string;
+  readonly diagnosticStatus: 'registered-route-needs-smoke' | 'needs-provider-after-smoke';
+  readonly inspectRoute: string;
+  readonly sources: readonly LocalModelEndpointSource[];
+  readonly sourceDetails: readonly string[];
+  readonly modelRoutes: readonly string[];
+  readonly smokeCommand: string;
+  readonly smokeRoute: string;
+  readonly refreshRoute: string;
+  readonly addProviderRoute: string | null;
+  readonly notes: readonly string[];
+  readonly diagnostics?: {
+    readonly liveProbe: 'not-run';
+    readonly successCriteria: readonly string[];
+    readonly failureTriage: readonly string[];
+    readonly afterSmoke: readonly string[];
+    readonly policy: string;
+  };
+}
+
+export interface LocalModelServerDefaultEndpoint {
+  readonly id: string;
+  readonly label: string;
+  readonly stack: string;
+  readonly baseUrl: string;
+  readonly modelsUrl: string;
+  readonly smokeCommand: string;
+  readonly addProviderRoute: string;
+  readonly startHint: string;
+}
+
+export interface LocalModelServerHealthMap {
+  readonly status: 'candidate-endpoints' | 'no-local-endpoints';
+  readonly liveProbe: 'not-run';
+  readonly endpointCount: number;
+  readonly returnedEndpoints: number;
+  readonly endpoints: readonly LocalModelServerEndpoint[];
+  readonly suggestedDefaults: readonly LocalModelServerDefaultEndpoint[];
+  readonly nextActions: readonly string[];
+  readonly policy: string;
+}
+
+export interface LocalModelSmokeTarget {
+  readonly kind: 'local-server-endpoint' | 'suggested-local-server';
+  readonly id: string;
+  readonly label: string;
+  readonly providerId: string | null;
+  readonly stack: string | null;
+  readonly baseUrl: string;
+  readonly modelsUrl: string;
+  readonly smokeCommand: string;
+  readonly smokeRoute: string;
+  readonly refreshRoute: string;
+  readonly addProviderRoute: string | null;
+  readonly source: string;
+  readonly notes: readonly string[];
+}
+
+export interface MutableLocalModelServerEndpoint {
+  providerId: string | null;
+  stack: string | null;
+  readonly baseUrl: string;
+  readonly sources: Set<LocalModelEndpointSource>;
+  readonly sourceDetails: Set<string>;
+  readonly modelRoutes: Set<string>;
+  readonly notes: Set<string>;
+}
+
+export interface LocalModelSetupPlan {
+  readonly status: 'detected' | 'ready-to-try' | 'needs-hardware-review';
+  readonly priority: number;
+  readonly downloadGuidance: readonly string[];
+  readonly providerRoutes: readonly string[];
+  readonly benchmarkPlan: LocalModelBenchmarkPlan;
+  readonly confirmationBoundary: string;
+}
+
+export interface ArtifactListLike {
+  readonly list?: (limit?: number) => readonly ArtifactDescriptor[];
+}
+
+export interface ProviderApiLike {
+  readonly getFavorites: () => Promise<unknown>;
+  readonly getCurrentModel: () => Promise<unknown>;
+  readonly listModels: (options?: { readonly selectableOnly?: boolean }) => Promise<readonly unknown[]>;
+  readonly listProviderIds: () => readonly string[];
+}

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

@@ -0,0 +1,30 @@
+export function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export 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)));
+}
+
+export function readRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : {};
+}
+
+export function readFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+export function readBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+export function readStringArray(value: unknown): readonly string[] {
+  return Array.isArray(value) ? value.map((entry) => readString(entry)).filter(Boolean) : [];
+}
+
+export function safeIso(value: number | null | undefined): string | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
+  return new Date(value).toISOString();
+}