feat(image-analysis): resolve backend status per profile

src/utils/hooks/get-image-analysis-hook-env.ts

@@ -8,6 +8,11 @@
  */
 
 import { getImageAnalysisConfig } from '../../config/unified-config-loader';
+import { mapExternalProviderName } from '../../cliproxy/provider-capabilities';
+import {
+  resolveImageAnalysisStatus,
+  type ImageAnalysisResolutionContext,
+} from './image-analysis-backend-resolver';
 
 /**
  * Serialize provider_models map to env var format: provider:model,provider:model
@@ -22,21 +27,30 @@ function serializeProviderModels(providerModels: Record<string, string>): string
  * Get image analysis hook environment variables.
  * These env vars control the hook's behavior via Claude Code hook system.
  *
- * @param provider - Current CLIProxy provider (e.g., 'agy', 'gemini', 'codex')
+ * @param input - Current runtime context
  * @returns Environment variables for image analysis hook
  */
-export function getImageAnalysisHookEnv(provider?: string): Record<string, string> {
+export function getImageAnalysisHookEnv(
+  input?: string | ImageAnalysisResolutionContext
+): Record<string, string> {
   const config = getImageAnalysisConfig();
-
-  // Check if current provider has a vision model configured
-  const hasVisionModel = provider && config.provider_models[provider];
-  const skipImageAnalysis = !config.enabled || !hasVisionModel;
+  const context =
+    typeof input === 'string'
+      ? {
+          profileName: input,
+          cliproxyProvider: mapExternalProviderName(input) ?? undefined,
+        }
+      : input;
+  const status = context
+    ? resolveImageAnalysisStatus(context, config)
+    : resolveImageAnalysisStatus({ profileName: '' }, config);
+  const skipImageAnalysis = !status.supported;
 
   return {
     CCS_IMAGE_ANALYSIS_ENABLED: config.enabled ? '1' : '0',
     CCS_IMAGE_ANALYSIS_TIMEOUT: String(Number(config.timeout) || 60),
     CCS_IMAGE_ANALYSIS_PROVIDER_MODELS: serializeProviderModels(config.provider_models),
-    CCS_CURRENT_PROVIDER: provider || '',
+    CCS_CURRENT_PROVIDER: status.backendId || '',
     CCS_IMAGE_ANALYSIS_SKIP: skipImageAnalysis ? '1' : '0',
   };
 }

src/utils/hooks/image-analysis-backend-resolver.ts

@@ -0,0 +1,379 @@
+import {
+  DEFAULT_IMAGE_ANALYSIS_CONFIG,
+  type ImageAnalysisConfig,
+} from '../../config/unified-config-types';
+import {
+  getProviderDisplayName,
+  isCLIProxyProvider,
+  mapExternalProviderName,
+} from '../../cliproxy/provider-capabilities';
+import { extractProviderFromPathname } from '../../cliproxy/model-id-normalizer';
+import type { CliproxyBridgeMetadata } from '../../api/services/profile-types';
+import type { Settings } from '../../types/config';
+import type { ProfileType } from '../../types/profile';
+
+export type ImageAnalysisResolutionSource =
+  | 'cliproxy-provider'
+  | 'cliproxy-variant'
+  | 'cliproxy-composite'
+  | 'copilot-alias'
+  | 'cliproxy-bridge'
+  | 'profile-backend'
+  | 'fallback-backend'
+  | 'disabled'
+  | 'unsupported-profile'
+  | 'unresolved'
+  | 'missing-model';
+
+export type ImageAnalysisStatusCode =
+  | 'active'
+  | 'mapped'
+  | 'attention'
+  | 'disabled'
+  | 'skipped'
+  | 'hook-missing';
+
+export interface ImageAnalysisResolutionContext {
+  profileName: string;
+  profileType?: ProfileType;
+  settingsPath?: string | null;
+  cliproxyProvider?: string | null;
+  isComposite?: boolean;
+  settings?: Pick<Settings, 'env'> | null;
+  cliproxyBridge?: CliproxyBridgeMetadata | null;
+  hookInstalled?: boolean;
+  sharedHookInstalled?: boolean;
+}
+
+export interface ImageAnalysisStatus {
+  enabled: boolean;
+  supported: boolean;
+  status: ImageAnalysisStatusCode;
+  backendId: string | null;
+  backendDisplayName: string | null;
+  model: string | null;
+  resolutionSource: ImageAnalysisResolutionSource;
+  reason: string | null;
+  shouldPersistHook: boolean;
+  persistencePath: string | null;
+  runtimePath: string | null;
+  usesCurrentTarget: boolean | null;
+  usesCurrentAuthToken: boolean | null;
+  hookInstalled: boolean | null;
+  sharedHookInstalled: boolean | null;
+}
+
+function resolveProviderFromBaseUrl(baseUrl: unknown): string | null {
+  if (typeof baseUrl !== 'string' || baseUrl.trim().length === 0) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(baseUrl);
+    const extracted = extractProviderFromPathname(parsed.pathname);
+    return extracted ? mapExternalProviderName(extracted) : null;
+  } catch {
+    const extracted = extractProviderFromPathname(baseUrl);
+    return extracted ? mapExternalProviderName(extracted) : null;
+  }
+}
+
+function findCaseInsensitiveKey(
+  entries: Record<string, string> | undefined,
+  requestedKey: string
+): string | null {
+  if (!entries) {
+    return null;
+  }
+
+  const normalizedRequestedKey = requestedKey.trim().toLowerCase();
+  for (const key of Object.keys(entries)) {
+    if (key.trim().toLowerCase() === normalizedRequestedKey) {
+      return key;
+    }
+  }
+
+  return null;
+}
+
+export function normalizeImageAnalysisBackendId(
+  value: string | null | undefined,
+  knownBackends: Iterable<string> = []
+): string | null {
+  if (!value || value.trim().length === 0) {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  const canonicalProvider = mapExternalProviderName(trimmed.toLowerCase());
+  if (canonicalProvider) {
+    return canonicalProvider;
+  }
+
+  const knownBackendList = Array.from(knownBackends);
+  const exactKey = knownBackendList.find((backend) => backend === trimmed);
+  if (exactKey) {
+    return exactKey;
+  }
+
+  const caseInsensitiveKey = knownBackendList.find(
+    (backend) => backend.trim().toLowerCase() === trimmed.toLowerCase()
+  );
+  if (caseInsensitiveKey) {
+    return caseInsensitiveKey;
+  }
+
+  return trimmed.toLowerCase();
+}
+
+export function canonicalizeImageAnalysisConfig(config: ImageAnalysisConfig): ImageAnalysisConfig {
+  const normalizedProviderModels = Object.entries(config.provider_models ?? {}).reduce(
+    (acc, [backend, model]) => {
+      const normalizedBackend = normalizeImageAnalysisBackendId(
+        backend,
+        Object.keys(DEFAULT_IMAGE_ANALYSIS_CONFIG.provider_models)
+      );
+      if (!normalizedBackend || typeof model !== 'string' || model.trim().length === 0) {
+        return acc;
+      }
+
+      acc[normalizedBackend] = model.trim();
+      return acc;
+    },
+    {} as Record<string, string>
+  );
+
+  const normalizedFallbackBackend =
+    normalizeImageAnalysisBackendId(
+      config.fallback_backend ?? DEFAULT_IMAGE_ANALYSIS_CONFIG.fallback_backend,
+      Object.keys(normalizedProviderModels)
+    ) ?? DEFAULT_IMAGE_ANALYSIS_CONFIG.fallback_backend;
+
+  const normalizedProfileBackends = Object.entries(config.profile_backends ?? {}).reduce(
+    (acc, [profileName, backend]) => {
+      const trimmedProfileName = profileName.trim();
+      const normalizedBackend = normalizeImageAnalysisBackendId(
+        backend,
+        Object.keys(normalizedProviderModels)
+      );
+      if (!trimmedProfileName || !normalizedBackend) {
+        return acc;
+      }
+
+      acc[trimmedProfileName] = normalizedBackend;
+      return acc;
+    },
+    {} as Record<string, string>
+  );
+
+  return {
+    enabled: config.enabled,
+    timeout: config.timeout,
+    provider_models: normalizedProviderModels,
+    fallback_backend: normalizedFallbackBackend,
+    profile_backends: normalizedProfileBackends,
+  };
+}
+
+function resolveConfiguredProfileBackend(
+  profileName: string,
+  config: ImageAnalysisConfig
+): string | null {
+  if (!config.profile_backends) {
+    return null;
+  }
+
+  const exactKey = config.profile_backends[profileName];
+  if (exactKey) {
+    return normalizeImageAnalysisBackendId(exactKey, Object.keys(config.provider_models));
+  }
+
+  const matchedKey = findCaseInsensitiveKey(config.profile_backends, profileName);
+  if (!matchedKey) {
+    return null;
+  }
+
+  return normalizeImageAnalysisBackendId(
+    config.profile_backends[matchedKey],
+    Object.keys(config.provider_models)
+  );
+}
+
+function getBackendDisplayName(backendId: string | null): string | null {
+  if (!backendId) {
+    return null;
+  }
+
+  return isCLIProxyProvider(backendId) ? getProviderDisplayName(backendId) : backendId;
+}
+
+function getRuntimePath(backendId: string | null): string | null {
+  if (!backendId) {
+    return null;
+  }
+
+  return `/api/provider/${backendId}`;
+}
+
+function resolveBackend(
+  context: ImageAnalysisResolutionContext,
+  config: ImageAnalysisConfig
+): Pick<ImageAnalysisStatus, 'backendId' | 'backendDisplayName' | 'resolutionSource' | 'reason'> {
+  const { profileName, profileType, cliproxyProvider, isComposite, cliproxyBridge, settings } =
+    context;
+
+  if (!config.enabled) {
+    return {
+      backendId: null,
+      backendDisplayName: null,
+      resolutionSource: 'disabled',
+      reason: 'Disabled globally.',
+    };
+  }
+
+  if (profileType === 'default' || profileType === 'account') {
+    return {
+      backendId: null,
+      backendDisplayName: null,
+      resolutionSource: 'unsupported-profile',
+      reason: 'This profile type is not currently covered by image-analysis runtime.',
+    };
+  }
+
+  if (profileType === 'copilot' || profileName === 'copilot') {
+    const backendId = normalizeImageAnalysisBackendId('ghcp', Object.keys(config.provider_models));
+    return {
+      backendId,
+      backendDisplayName: getBackendDisplayName(backendId),
+      resolutionSource: 'copilot-alias',
+      reason: null,
+    };
+  }
+
+  const normalizedCliproxyProvider = normalizeImageAnalysisBackendId(
+    cliproxyProvider,
+    Object.keys(config.provider_models)
+  );
+  if (normalizedCliproxyProvider) {
+    return {
+      backendId: normalizedCliproxyProvider,
+      backendDisplayName: getBackendDisplayName(normalizedCliproxyProvider),
+      resolutionSource:
+        isComposite || profileName.startsWith('composite-')
+          ? 'cliproxy-composite'
+          : profileName === normalizedCliproxyProvider
+            ? 'cliproxy-provider'
+            : 'cliproxy-variant',
+      reason: null,
+    };
+  }
+
+  const bridgeBackend = normalizeImageAnalysisBackendId(
+    cliproxyBridge?.provider ??
+      resolveProviderFromBaseUrl(settings?.env?.ANTHROPIC_BASE_URL ?? undefined),
+    Object.keys(config.provider_models)
+  );
+  if (bridgeBackend) {
+    return {
+      backendId: bridgeBackend,
+      backendDisplayName: getBackendDisplayName(bridgeBackend),
+      resolutionSource: 'cliproxy-bridge',
+      reason: null,
+    };
+  }
+
+  const mappedBackend = resolveConfiguredProfileBackend(profileName, config);
+  if (mappedBackend) {
+    return {
+      backendId: mappedBackend,
+      backendDisplayName: getBackendDisplayName(mappedBackend),
+      resolutionSource: 'profile-backend',
+      reason: null,
+    };
+  }
+
+  const fallbackBackend = normalizeImageAnalysisBackendId(
+    config.fallback_backend,
+    Object.keys(config.provider_models)
+  );
+  if (fallbackBackend) {
+    return {
+      backendId: fallbackBackend,
+      backendDisplayName: getBackendDisplayName(fallbackBackend),
+      resolutionSource: 'fallback-backend',
+      reason: null,
+    };
+  }
+
+  return {
+    backendId: null,
+    backendDisplayName: null,
+    resolutionSource: 'unresolved',
+    reason: 'No supported backend could be resolved.',
+  };
+}
+
+export function resolveImageAnalysisStatus(
+  context: ImageAnalysisResolutionContext,
+  rawConfig: ImageAnalysisConfig = DEFAULT_IMAGE_ANALYSIS_CONFIG
+): ImageAnalysisStatus {
+  const config = canonicalizeImageAnalysisConfig(rawConfig);
+  const resolution = resolveBackend(context, config);
+  const model = resolution.backendId
+    ? (config.provider_models[resolution.backendId] ?? null)
+    : null;
+  const shouldPersistHook =
+    config.enabled && context.profileType !== 'default' && context.profileType !== 'account';
+
+  let status: ImageAnalysisStatusCode = 'active';
+  let reason = resolution.reason;
+
+  if (!config.enabled) {
+    status = 'disabled';
+    reason ??=
+      'This profile falls back to native Read because image analysis is turned off in CCS config.';
+  } else if (!resolution.backendId) {
+    status = 'skipped';
+    reason ??= 'No supported backend could be resolved.';
+  } else if (!model) {
+    status = 'skipped';
+    reason = 'Resolved backend has no image-analysis model configured.';
+  } else if (
+    shouldPersistHook &&
+    (context.hookInstalled === false || context.sharedHookInstalled === false)
+  ) {
+    status = 'hook-missing';
+    reason =
+      context.sharedHookInstalled === false
+        ? 'Shared image-analysis hook is not installed.'
+        : 'Profile hook is missing from the persisted settings file.';
+  } else if (
+    resolution.resolutionSource === 'cliproxy-bridge' &&
+    context.cliproxyBridge &&
+    (!context.cliproxyBridge.usesCurrentTarget || !context.cliproxyBridge.usesCurrentAuthToken)
+  ) {
+    status = 'attention';
+    reason =
+      'Active, but runtime uses the current CLIProxy target instead of the stale route saved in this profile.';
+  } else if (resolution.resolutionSource === 'profile-backend') {
+    status = 'mapped';
+  }
+
+  return {
+    enabled: config.enabled,
+    supported: Boolean(config.enabled && resolution.backendId && model),
+    status,
+    backendId: resolution.backendId,
+    backendDisplayName: resolution.backendDisplayName,
+    model,
+    resolutionSource: resolution.resolutionSource,
+    reason,
+    shouldPersistHook,
+    persistencePath: shouldPersistHook ? `${context.profileName}.settings.json` : null,
+    runtimePath: getRuntimePath(resolution.backendId),
+    usesCurrentTarget: context.cliproxyBridge?.usesCurrentTarget ?? null,
+    usesCurrentAuthToken: context.cliproxyBridge?.usesCurrentAuthToken ?? null,
+    hookInstalled: context.hookInstalled ?? null,
+    sharedHookInstalled: context.sharedHookInstalled ?? null,
+  };
+}

src/utils/hooks/image-analyzer-profile-hook-injector.ts

@@ -4,7 +4,7 @@
  * Injects image analyzer hooks into per-profile settings files.
  * This replaces the global ~/.claude/settings.json approach.
  *
- * Injects for profiles configured in image_analysis.provider_models.
+ * Injects for profiles that resolve to a supported image-analysis backend.
  *
  * @module utils/hooks/image-analyzer-profile-injector
  */
@@ -18,9 +18,13 @@ import {
 } from './image-analyzer-hook-configuration';
 import { getImageAnalysisConfig } from '../../config/unified-config-loader';
 import { getCcsDir } from '../config-manager';
+import {
+  resolveImageAnalysisStatus,
+  type ImageAnalysisResolutionContext,
+} from './image-analysis-backend-resolver';
 
-// Valid profile name pattern (alphanumeric, dash, underscore only)
-const VALID_PROFILE_NAME = /^[a-zA-Z0-9_-]+$/;
+// Valid profile name pattern (alphanumeric, dot, dash, underscore only)
+const VALID_PROFILE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 
 /**
  * Get migration marker path (respects CCS_HOME for test isolation)
@@ -51,6 +55,39 @@ function hasCcsHook(settings: Record<string, unknown>): boolean {
   });
 }
 
+export function getImageAnalysisProfileSettingsPath(
+  profileName: string,
+  settingsPath?: string | null
+): string {
+  if (typeof settingsPath === 'string' && settingsPath.trim().length > 0) {
+    return settingsPath;
+  }
+
+  return path.join(getCcsDir(), `${profileName}.settings.json`);
+}
+
+export function hasImageAnalysisProfileHook(
+  profileName: string,
+  settingsPath?: string | null
+): boolean {
+  if (!VALID_PROFILE_NAME.test(profileName)) {
+    return false;
+  }
+
+  const resolvedSettingsPath = getImageAnalysisProfileSettingsPath(profileName, settingsPath);
+  if (!fs.existsSync(resolvedSettingsPath)) {
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(resolvedSettingsPath, 'utf8');
+    const settings = JSON.parse(content) as Record<string, unknown>;
+    return hasCcsHook(settings);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * One-time migration marker management
  */
@@ -79,13 +116,14 @@ function migrateGlobalHook(): void {
 /**
  * Ensure image analyzer hook is configured in profile's settings file
  *
- * Only injects for CLIProxy profiles with vision support (agy, gemini).
- *
- * @param profileName - Name of the profile (e.g., 'agy', 'gemini')
+ * @param input - Profile name or pre-resolved runtime context
  * @returns true if hook is configured (existing or newly added)
  */
-export function ensureProfileHooks(profileName: string): boolean {
+export function ensureProfileHooks(input: string | ImageAnalysisResolutionContext): boolean {
   try {
+    const context = typeof input === 'string' ? { profileName: input } : input;
+    const profileName = context.profileName;
+
     // Validate profile name to prevent path traversal
     if (!VALID_PROFILE_NAME.test(profileName)) {
       if (process.env.CCS_DEBUG) {
@@ -95,16 +133,8 @@ export function ensureProfileHooks(profileName: string): boolean {
     }
 
     const imageConfig = getImageAnalysisConfig();
-
-    // Only inject for profiles that have a model mapping in provider_models
-    // This allows dynamic extension without hardcoding profile names
-    const configuredProviders = Object.keys(imageConfig.provider_models);
-    if (!configuredProviders.includes(profileName)) {
-      return false;
-    }
-
-    // Skip if image analysis is disabled
-    if (!imageConfig.enabled) {
+    const status = resolveImageAnalysisStatus(context, imageConfig);
+    if (!status.supported || !status.shouldPersistHook) {
       return false;
     }
 
@@ -119,7 +149,7 @@ export function ensureProfileHooks(profileName: string): boolean {
       fs.mkdirSync(ccsDir, { recursive: true, mode: 0o700 });
     }
 
-    const settingsPath = path.join(ccsDir, `${profileName}.settings.json`);
+    const settingsPath = getImageAnalysisProfileSettingsPath(profileName, context.settingsPath);
 
     // Read existing settings or create empty
     let settings: Record<string, unknown> = {};

src/utils/hooks/index.ts

@@ -7,6 +7,13 @@
  */
 
 export { getImageAnalysisHookEnv } from './get-image-analysis-hook-env';
+export {
+  canonicalizeImageAnalysisConfig,
+  resolveImageAnalysisStatus,
+  normalizeImageAnalysisBackendId,
+  type ImageAnalysisResolutionContext,
+  type ImageAnalysisStatus,
+} from './image-analysis-backend-resolver';
 export {
   getImageAnalyzerHookPath,
   getImageAnalyzerHookConfig,