pi-media-models 0.1.5 → 0.1.7

package/README.md

@@ -9,7 +9,8 @@ This extension seamlessly bridges Pi's reasoning capabilities with top-tier AI m
 
 ## ✨ Features
 
-- **Unified Interface**: One request format (`provider`, `model`, `prompt`, `referenceImages`, etc.) maps automatically to the correct capability across providers.
+- **Live Model Discovery**: Queries configured provider catalogs, performs lightweight access probes where supported, and marks the newest usable model as the default.
+- **Unified Interface**: One request format (`provider`, optional `model`, `prompt`, `referenceImages`, etc.) maps automatically to the correct capability across providers. Omit `model` to use the newest discovered usable model.
 - **Config-First Authentication**: Manage all API keys and credentials directly in a single `media-models.json` configuration file — no cluttered environment variables needed.
 - **Auto-Download**: Output media (images, videos, audio) is automatically downloaded and saved to a local directory (`~/.pi/agent/media/outputs/`) using atomic `.part` renames. LLM context remains pristine and only receives local file paths.
 - **Smart Input Resolution**: Pass local paths (`C:/...` or `/path/...`), file URIs (`file://`), standard URLs (`http(s)://`), or base64 (`data:...`). The router transparently handles multipart uploads, base64 encoding, or CDN pre-uploading (e.g., for `fal.ai`).
@@ -94,14 +95,13 @@ Create or edit `~/.pi/agent/media-models.json`:
     },
     "vertex": {
       "credentialsFile": "/path/to/vertex-service-account.json",
-      "project": "my-gcp-project",
       "location": "us-central1"
     }
   }
 }
 ```
 
-> **Note**: You only need to fill in the providers you plan to use. Unused providers can simply be omitted.
+> **Note**: You only need to fill in the providers you plan to use. Unused providers can simply be omitted. Vertex reads `project_id` from the service-account JSON when `project` is omitted or still set to a placeholder such as `my-gcp-project`; an explicit real project ID remains supported.
 
 ### Custom OpenAI-Compatible Providers
 
@@ -148,13 +148,15 @@ You can connect any third-party or internal OpenAI-compatible media gateway by d
 
 The extension registers exactly 6 unified tools for the reasoning agent:
 
-1. `media_models`: Lists providers, configured models, and supported capabilities.
-2. `image_generate`: Generate images from text, image, or multiple reference inputs.
+1. `media_models`: Discovers credential-visible models, probes access where supported, reports availability, and marks the newest usable model as the default.
+2. `image_generate`: Generate images from text, image, or multiple reference inputs. `model` is optional; omission selects the newest usable discovered model.
 3. `image_edit`: Edit existing images (supports masks and multiple references).
 4. `video_generate`: Generates, edits, or extends videos. Automatically maps inputs (`referenceImages`, `inputVideo`, `duration`, `generateAudio`, etc.) to the provider's exact capability.
 5. `audio_generate`: Generate music or raw audio (separate from TTS).
 6. `speech_generate`: Handle TTS (Text-to-Speech) and STT (Speech-to-Text).
 
+Live catalog discovery is implemented for Google Gemini, Vertex AI Model Garden, OpenAI, xAI, Atlas, and OpenRouter. Providers without a reliable catalog API use their declared fallback candidates; those entries are labeled `source=built-in` and `availability=unknown` rather than being presented as verified.
+
 ## 🔒 Security & Privacy
 
 - **No Key Logging**: API keys and Bearer tokens are redacted (`[REDACTED]`) from all error logs and HTTP outputs before being returned to the LLM.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-media-models",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Provider-neutral multimodal generation tools for Pi Coding Agent",
   "keywords": [

package/skills/pi-media/SKILL.md

@@ -22,7 +22,7 @@ This skill activates the `pi-media-models` extension, which exposes six unified
 
 ### 1. Discover what is configured
 
-When the user has not specified a provider and model, call `media_models` first to see which providers have `configured: true` and which capabilities they support. Never invent model names.
+When the user has not specified a provider, call `media_models` first to see which providers have `configured: true` and which capabilities they support. Never invent model names. If the provider is known but the model is not, omit `model`; the media tool discovers models, probes access where supported, and selects the newest usable model.
 
 ```
 media_models({ capability: "image.text_to_image" })
@@ -30,7 +30,7 @@ media_models({ capability: "image.text_to_image" })
 
 ### 2. Call the right tool
 
-Pick the tool that matches the request, then pass `provider`, `model`, and `prompt` at minimum. Add optional parameters as needed.
+Pick the tool that matches the request, then pass `provider` and `prompt` at minimum. Pass `model` only when a specific model is required; otherwise omit it for automatic discovery and selection. Add optional parameters as needed.
 
 ```
 image_generate({
@@ -68,7 +68,7 @@ All generated media is automatically downloaded to `~/.pi/agent/media/outputs/`.
 | Parameter | Description |
 |---|---|
 | `provider` | Provider id: `openai`, `gemini`, `vertex`, `xai`, `atlas`, `dashscope`, `qwencloud`, `fal`, `openrouter` |
-| `model` | Exact model id as returned by `media_models` |
+| `model` | Optional exact model id as returned by `media_models`; omit to select the newest discovered usable model |
 | `prompt` | Required. Describe the desired output |
 | `aspectRatio` | `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, etc. |
 | `resolution` | `"1024x1024"`, `"720p"`, `"1080p"` |
@@ -97,13 +97,12 @@ All API keys and provider options are configured in `~/.pi/agent/media-models.js
     "openrouter": { "apiKey": "sk-or-..." },
     "vertex": {
       "credentialsFile": "/path/to/service-account.json",
-      "project": "my-gcp-project",
       "location": "us-central1"
     }
   }
 }
 ```
 
-Tell the user to edit `~/.pi/agent/media-models.json` directly to add or update API keys.
+Tell the user to edit `~/.pi/agent/media-models.json` directly to add or update API keys. Vertex automatically reads `project_id` from the service-account JSON when `project` is omitted or still contains the default placeholder.
 
 *(Environment variables such as `FAL_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY` are also checked as a fallback).*

package/src/adapters/atlas.ts

@@ -1,7 +1,7 @@
 import { MediaError } from '../errors.js'
 import { MediaJob, mapJobState } from '../media-job.js'
 import { BaseAdapter, artifactsOrThrow, bearerHeaders, dataUris, makeModel, mergeOptions, requirePrompt } from './base.js'
-import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor } from '../types.js'
+import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor, ModelDiscoveryContext } from '../types.js'
 
 const ATLAS_CAPS: Capability[] = [
   'image.text_to_image', 'image.image_to_image', 'image.edit',
@@ -23,6 +23,18 @@ export class AtlasAdapter extends BaseAdapter {
     ]
   }
 
+  async discoverModels(context: ModelDiscoveryContext): Promise<ModelDescriptor[]> {
+    const key = this.keyFromOptions(context.providerOptions)
+    const payload = await this.http.json<{ data?: Array<{ id?: string; owned_by?: string }> }>(`${this.baseUrl}/models`, {
+      headers: bearerHeaders(key), signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 30_000,
+    })
+    return (payload.data ?? []).flatMap(entry => {
+      if (!entry.id) return []
+      const capabilities = atlasCapabilities(entry.id, this.models())
+      return capabilities.length ? [makeModel(this.id, entry.owned_by ?? 'multi-vendor', entry.id, capabilities)] : []
+    })
+  }
+
   supports(capability: Capability): boolean { return ATLAS_CAPS.includes(capability) }
 
   async execute(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
@@ -141,6 +153,14 @@ export class AtlasAdapter extends BaseAdapter {
   }
 }
 
+function atlasCapabilities(id: string, declared: ModelDescriptor[]): Capability[] {
+  const known = declared.find(model => model.id === id)
+  if (known) return known.capabilities
+  if (/(?:image|dall-e|flux|ideogram)/i.test(id)) return ['image.text_to_image', 'image.image_to_image', 'image.edit']
+  if (/(?:video|veo|seedance|kling|sora)/i.test(id)) return ['video.text_to_video', 'video.image_to_video', 'video.first_last_frame', 'video.reference', 'video.native_audio']
+  return []
+}
+
 function stringId(payload: Record<string, unknown>): string | undefined {
   return typeof payload.task_id === 'string' ? payload.task_id : typeof payload.id === 'string' ? payload.id : undefined
 }

package/src/adapters/base.ts

@@ -29,8 +29,12 @@ export abstract class BaseAdapter implements ProviderAdapter {
   abstract execute(request: MediaRequest, context: AdapterContext): Promise<AdapterResult>
 
   protected key(request: MediaRequest): string {
-    const configKey = request.providerOptions?.apiKey;
-    const value = (typeof configKey === "string" ? configKey : undefined) ?? (this.envKey ? this.env[this.envKey] : undefined)
+    return this.keyFromOptions(request.providerOptions)
+  }
+
+  protected keyFromOptions(options?: JsonObject): string {
+    const configKey = options?.apiKey
+    const value = (typeof configKey === 'string' && configKey.trim() ? configKey.trim() : undefined) ?? (this.envKey ? this.env[this.envKey] : undefined)
     if (!value) throw new MediaError('AUTH', `${this.envKey ?? `${this.id} API key`} is not set in environment or config`, { provider: this.id })
     return value
   }

package/src/adapters/google.ts

@@ -3,7 +3,8 @@ import { fileURLToPath } from 'node:url'
 import { MediaError } from '../errors.js'
 import { MediaJob } from '../media-job.js'
 import { BaseAdapter, artifactsOrThrow, makeModel } from './base.js'
-import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor } from '../types.js'
+import { expandHomePath } from '../config.js'
+import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor, ModelDiscoveryContext } from '../types.js'
 import type { AdapterDependencies } from './base.js'
 
 const GOOGLE_CAPS: Capability[] = [
@@ -26,13 +27,42 @@ export class GoogleMediaAdapter extends BaseAdapter {
     return [
       makeModel(this.id, 'google', 'gemini-2.5-flash-image', ['image.text_to_image', 'image.image_to_image', 'image.edit', 'image.multi_reference']),
       makeModel(this.id, 'google', 'imagen-4.0-generate-001', ['image.text_to_image']),
-      makeModel(this.id, 'google', 'veo-3.1-generate-preview', ['video.text_to_video', 'video.image_to_video', 'video.first_last_frame', 'video.reference', 'video.extend', 'video.native_audio']),
-      makeModel(this.id, 'google', 'gemini-2.5-flash-preview-tts', ['speech.tts']),
+      makeModel(this.id, 'google', 'veo-3.1-generate-001', ['video.text_to_video', 'video.image_to_video', 'video.first_last_frame', 'video.reference', 'video.extend', 'video.native_audio']),
+      makeModel(this.id, 'google', 'gemini-2.5-flash-tts', ['speech.tts']),
       makeModel(this.id, 'google', 'gemini-2.5-flash', ['speech.stt']),
-      makeModel(this.id, 'google', 'lyria-3.5', ['audio.generate']),
+      makeModel(this.id, 'google', 'lyria-002', ['audio.generate']),
     ]
   }
 
+  async discoverModels(context: ModelDiscoveryContext): Promise<ModelDescriptor[]> {
+    return this.id === 'gemini' ? this.discoverGeminiModels(context) : this.discoverVertexModels(context)
+  }
+
+  async probeModel(model: ModelDescriptor, _capability: Capability, context: ModelDiscoveryContext): Promise<boolean | undefined> {
+    if (/^gemini-/i.test(model.id)) {
+      const { url, headers } = await this.requestForModel(model.id, context.providerOptions, 'countTokens')
+      await this.http.json<Record<string, unknown>>(url, {
+        method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ contents: [{ role: 'user', parts: [{ text: 'availability check' }] }] }),
+        signal: context.signal, provider: this.id, secrets: this.discoverySecrets(context.providerOptions), timeoutMs: 30_000, retries: 0,
+      })
+      return true
+    }
+    if (this.id !== 'vertex' || !/^imagen-/i.test(model.id)) return undefined
+    const { url, headers } = await this.requestForModel(model.id, context.providerOptions, 'predict')
+    try {
+      await this.http.json<Record<string, unknown>>(url, {
+        method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ instances: [] }),
+        signal: context.signal, provider: this.id, timeoutMs: 30_000, retries: 0,
+      })
+      return true
+    } catch (error) {
+      if (error instanceof MediaError && error.status === 400) return true
+      if (error instanceof MediaError && (error.status === 403 || error.status === 404)) return false
+      throw error
+    }
+  }
+
   supports(capability: Capability): boolean { return GOOGLE_CAPS.includes(capability) }
 
   async execute(request: MediaRequest, context: AdapterContext): Promise<AdapterResult> {
@@ -155,31 +185,98 @@ export class GoogleMediaAdapter extends BaseAdapter {
       : { bytesBase64Encoded: inline.data, mimeType: inline.mimeType }
   }
 
+  private async discoverGeminiModels(context: ModelDiscoveryContext): Promise<ModelDescriptor[]> {
+    const key = this.keyFromOptions(context.providerOptions)
+    const models: ModelDescriptor[] = []
+    let pageToken: string | undefined
+    do {
+      const url = new URL('https://generativelanguage.googleapis.com/v1beta/models')
+      url.searchParams.set('pageSize', '1000')
+      if (pageToken) url.searchParams.set('pageToken', pageToken)
+      const payload = await this.http.json<{ models?: Array<{ name?: string; supportedGenerationMethods?: string[] }>; nextPageToken?: string }>(url.toString(), {
+        headers: { 'x-goog-api-key': key }, signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 30_000,
+      })
+      for (const entry of payload.models ?? []) {
+        const id = entry.name?.replace(/^models\//, '')
+        if (!id) continue
+        const capabilities = googleCapabilities(id, this.models())
+        if (capabilities.length) models.push({ ...makeModel(this.id, 'google', id, capabilities), availability: 'available' })
+      }
+      pageToken = payload.nextPageToken
+    } while (pageToken)
+    return uniqueModels(models)
+  }
+
+  private async discoverVertexModels(context: ModelDiscoveryContext): Promise<ModelDescriptor[]> {
+    const { auth, location } = await this.vertexSettings(context.providerOptions)
+    const models: ModelDescriptor[] = []
+    let pageToken: string | undefined
+    do {
+      const url = new URL(`https://${location}-aiplatform.googleapis.com/v1beta1/publishers/google/models`)
+      url.searchParams.set('pageSize', '100')
+      url.searchParams.set('listAllVersions', 'true')
+      if (pageToken) url.searchParams.set('pageToken', pageToken)
+      const authHeaders = await auth.getRequestHeaders(url.toString())
+      const headers: Record<string, string> = {}
+      for (const [key, value] of authHeaders.entries()) headers[key] = value
+      const payload = await this.http.json<{ publisherModels?: Array<{ name?: string; launchStage?: string }>; nextPageToken?: string }>(url.toString(), {
+        headers, signal: context.signal, provider: this.id, timeoutMs: 30_000,
+      })
+      for (const entry of payload.publisherModels ?? []) {
+        const id = entry.name?.split('/').pop()
+        if (!id) continue
+        const capabilities = googleCapabilities(id, this.models())
+        if (capabilities.length) models.push({
+          ...makeModel(this.id, 'google', id, capabilities, entry.launchStage ? `Vertex Model Garden: ${entry.launchStage}` : undefined),
+          availability: 'unknown',
+        })
+      }
+      pageToken = payload.nextPageToken
+    } while (pageToken)
+    return uniqueModels(models)
+  }
+
   private async modelRequest(request: MediaRequest, method: string): Promise<{ url: string; headers: Record<string, string>; operationsBase: string }> {
+    return this.requestForModel(request.model, request.providerOptions, method)
+  }
+
+  private async requestForModel(model: string, options: JsonObject | undefined, method: string): Promise<{ url: string; headers: Record<string, string>; operationsBase: string }> {
     if (this.id === 'gemini') {
-      const key = this.key(request)
+      const key = this.keyFromOptions(options)
       const base = 'https://generativelanguage.googleapis.com/v1beta'
-      return { url: `${base}/models/${encodeURIComponent(request.model)}:${method}`, headers: { 'x-goog-api-key': key }, operationsBase: base }
+      return { url: `${base}/models/${encodeURIComponent(model)}:${method}`, headers: { 'x-goog-api-key': key }, operationsBase: base }
     }
-    const options = request.providerOptions;
-    const configuredFile = typeof options?.credentialsFile === "string" ? options.credentialsFile : undefined
+    const { auth, project, location } = await this.vertexSettings(options)
+    const base = `https://${location}-aiplatform.googleapis.com/v1`
+    const resource = `projects/${encodeURIComponent(project)}/locations/${encodeURIComponent(location)}/publishers/google/models/${encodeURIComponent(model)}`
+    const url = `${base}/${resource}:${method}`
+    const authHeaders = await auth.getRequestHeaders(url)
+    const headers: Record<string, string> = {}
+    for (const [key, value] of authHeaders.entries()) headers[key] = value
+    return { url, headers, operationsBase: base }
+  }
+
+  private async vertexSettings(options?: JsonObject): Promise<{ auth: GoogleAuth; project: string; location: string }> {
+    const configuredFile = typeof options?.credentialsFile === 'string' ? options.credentialsFile : undefined
     const rawKeyFilename = configuredFile ?? this.env.VERTEX_CREDENTIALS_FILE ?? this.env.GOOGLE_APPLICATION_CREDENTIALS
-    const keyFilename = rawKeyFilename?.startsWith('file://') ? fileURLToPath(rawKeyFilename) : rawKeyFilename
+    const expandedKeyFile = expandHomePath(rawKeyFilename)
+    const keyFilename = expandedKeyFile?.startsWith('file://') ? fileURLToPath(expandedKeyFile) : expandedKeyFile
     const auth = new GoogleAuth({
       scopes: ['https://www.googleapis.com/auth/cloud-platform'],
       ...(keyFilename ? { keyFilename } : {}),
     })
-    const configuredProject = typeof options?.project === 'string' ? options.project : undefined
+    const configuredProject = typeof options?.project === 'string' && !isProjectPlaceholder(options.project) ? options.project : undefined
     const project = configuredProject ?? this.env.GOOGLE_CLOUD_PROJECT ?? this.env.GCLOUD_PROJECT ?? await auth.getProjectId()
     const configuredLocation = typeof options?.location === 'string' ? options.location : undefined
     const location = configuredLocation ?? this.env.GOOGLE_CLOUD_LOCATION ?? 'us-central1'
     if (!project) throw new MediaError('CONFIG', 'Vertex AI requires a project id from providerOptions.vertex.project, environment, ADC, or the credentials JSON', { provider: this.id })
-    const base = `https://${location}-aiplatform.googleapis.com/v1`
-    const resource = `projects/${encodeURIComponent(project)}/locations/${encodeURIComponent(location)}/publishers/google/models/${encodeURIComponent(request.model)}`
-    const authHeaders = await auth.getRequestHeaders(`${base}/${resource}:${method}`)
-    const headers: Record<string, string> = {}
-    for (const [key, value] of authHeaders.entries()) headers[key] = value
-    return { url: `${base}/${resource}:${method}`, headers, operationsBase: base }
+    return { auth, project, location }
+  }
+
+  private discoverySecrets(options?: JsonObject): string[] {
+    const configKey = typeof options?.apiKey === 'string' ? options.apiKey : undefined
+    const envKey = this.envKey && this.env[this.envKey] ? this.env[this.envKey] as string : undefined
+    return [configKey, envKey].filter((val): val is string => Boolean(val))
   }
 
   private secrets(request: MediaRequest): string[] {
@@ -189,6 +286,29 @@ export class GoogleMediaAdapter extends BaseAdapter {
   }
 }
 
+function googleCapabilities(id: string, declared: ModelDescriptor[]): Capability[] {
+  const known = declared.find(model => model.id === id)
+  if (known) return known.capabilities
+  if (/^imagen-|^gemini-.*image(?:-|$)/i.test(id)) {
+    return /^imagen-/i.test(id)
+      ? ['image.text_to_image']
+      : ['image.text_to_image', 'image.image_to_image', 'image.edit', 'image.multi_reference']
+  }
+  if (/^veo-/i.test(id)) return ['video.text_to_video', 'video.image_to_video', 'video.first_last_frame', 'video.reference', 'video.extend', 'video.native_audio']
+  if (/^lyria-/i.test(id)) return ['audio.generate']
+  if (/tts/i.test(id)) return ['speech.tts']
+  if (/transcribe/i.test(id)) return ['speech.stt']
+  return []
+}
+
+function uniqueModels(models: ModelDescriptor[]): ModelDescriptor[] {
+  return [...new Map(models.map(model => [model.id, model])).values()]
+}
+
+function isProjectPlaceholder(value: string): boolean {
+  return /^(?:my-gcp-project|your[-_ ]?(?:gcp[-_ ])?project(?:[-_ ]?id)?|<.*>)$/i.test(value.trim())
+}
+
 function findText(payload: unknown): string | undefined {
   if (!payload || typeof payload !== 'object') return undefined
   const candidates = (payload as { candidates?: Array<{ content?: { parts?: Array<{ text?: string }> } }> }).candidates

package/src/adapters/openai.ts

@@ -1,5 +1,5 @@
 import { BaseAdapter, artifactsOrThrow, bearerHeaders, makeModel, mergeOptions, requirePrompt } from './base.js'
-import type { AdapterContext, AdapterResult, Capability, MediaRequest, ModelDescriptor } from '../types.js'
+import type { AdapterContext, AdapterResult, Capability, MediaRequest, ModelDescriptor, ModelDiscoveryContext } from '../types.js'
 
 const IMAGE_CAPS: Capability[] = ['image.text_to_image', 'image.image_to_image', 'image.edit', 'image.multi_reference']
 const SPEECH_CAPS: Capability[] = ['speech.tts', 'speech.stt']
@@ -21,6 +21,18 @@ export class OpenAIAdapter extends BaseAdapter {
     ]
   }
 
+  async discoverModels(context: ModelDiscoveryContext): Promise<ModelDescriptor[]> {
+    const key = this.keyFromOptions(context.providerOptions)
+    const payload = await this.http.json<{ data?: Array<{ id?: string }> }>(`${this.baseUrl}/models`, {
+      headers: bearerHeaders(key), signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 30_000,
+    })
+    return (payload.data ?? []).flatMap(entry => {
+      if (!entry.id) return []
+      const capabilities = [...IMAGE_CAPS, ...SPEECH_CAPS].filter(capability => this.supports(capability, entry.id as string))
+      return capabilities.length ? [makeModel(this.id, 'openai', entry.id, capabilities)] : []
+    })
+  }
+
   supports(capability: Capability, model: string): boolean {
     if (capability.startsWith('video.') || capability === 'audio.generate') return false
     if (capability.startsWith('image.')) return /(?:gpt-image|dall-e)/i.test(model)

package/src/adapters/openrouter.ts

@@ -1,7 +1,7 @@
 import { MediaError } from '../errors.js'
 import { MediaJob, mapJobState } from '../media-job.js'
 import { BaseAdapter, artifactsOrThrow, bearerHeaders, dataUris, makeModel, mergeOptions, requirePrompt } from './base.js'
-import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor, RemoteArtifact } from '../types.js'
+import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor, ModelDiscoveryContext, RemoteArtifact } from '../types.js'
 
 const IMAGE_CAPS: Capability[] = ['image.text_to_image', 'image.image_to_image', 'image.edit', 'image.multi_reference']
 const VIDEO_CAPS: Capability[] = ['video.text_to_video', 'video.image_to_video', 'video.reference', 'video.native_audio']
@@ -20,6 +20,23 @@ export class OpenRouterAdapter extends BaseAdapter {
     ]
   }
 
+  async discoverModels(context: ModelDiscoveryContext): Promise<ModelDescriptor[]> {
+    const key = this.keyFromOptions(context.providerOptions)
+    const payload = await this.http.json<{ data?: Array<{ id?: string; architecture?: { output_modalities?: string[] } }> }>(`${this.baseUrl}/models`, {
+      headers: bearerHeaders(key), signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 30_000,
+    })
+    return (payload.data ?? []).flatMap(entry => {
+      if (!entry.id) return []
+      const outputs = entry.architecture?.output_modalities ?? []
+      const capabilities: Capability[] = [
+        ...(outputs.includes('image') || /(?:image|flux|dall-e|ideogram)/i.test(entry.id) ? IMAGE_CAPS : []),
+        ...(outputs.includes('video') || /(?:video|veo|seedance|kling|sora)/i.test(entry.id) ? VIDEO_CAPS : []),
+        ...(outputs.includes('audio') && /tts|speech/i.test(entry.id) ? ['speech.tts' as const] : []),
+      ]
+      return capabilities.length ? [makeModel(this.id, entry.id.split('/')[0] ?? 'multi-vendor', entry.id, [...new Set(capabilities)])] : []
+    })
+  }
+
   supports(capability: Capability): boolean {
     return IMAGE_CAPS.includes(capability) || VIDEO_CAPS.includes(capability) || capability === 'speech.tts'
   }

package/src/adapters/xai.ts

@@ -1,7 +1,7 @@
 import { MediaError } from '../errors.js'
 import { MediaJob, mapJobState } from '../media-job.js'
 import { BaseAdapter, artifactsOrThrow, bearerHeaders, dataUris, makeModel, mergeOptions, requirePrompt } from './base.js'
-import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor } from '../types.js'
+import type { AdapterContext, AdapterResult, Capability, JobStatus, JsonObject, MediaRequest, ModelDescriptor, ModelDiscoveryContext } from '../types.js'
 
 const IMAGE_CAPS: Capability[] = ['image.text_to_image', 'image.image_to_image', 'image.edit', 'image.multi_reference']
 const VIDEO_CAPS: Capability[] = ['video.text_to_video', 'video.image_to_video', 'video.reference', 'video.edit', 'video.extend', 'video.native_audio']
@@ -20,6 +20,18 @@ export class XAIAdapter extends BaseAdapter {
     ]
   }
 
+  async discoverModels(context: ModelDiscoveryContext): Promise<ModelDescriptor[]> {
+    const key = this.keyFromOptions(context.providerOptions)
+    const payload = await this.http.json<{ data?: Array<{ id?: string }> }>(`${this.baseUrl}/models`, {
+      headers: bearerHeaders(key), signal: context.signal, provider: this.id, secrets: [key], timeoutMs: 30_000,
+    })
+    return (payload.data ?? []).flatMap(entry => {
+      if (!entry.id) return []
+      const capabilities = [...IMAGE_CAPS, ...VIDEO_CAPS].filter(capability => this.supports(capability, entry.id as string))
+      return capabilities.length ? [makeModel(this.id, 'xai', entry.id, capabilities)] : []
+    })
+  }
+
   supports(capability: Capability, model: string): boolean {
     if (capability.startsWith('image.')) return /image/i.test(model)
     if (capability.startsWith('video.')) {

package/src/config.ts

@@ -1,9 +1,19 @@
 import { readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { CAPABILITIES, type Capability, type JsonObject } from './types.js'
 import { MediaError } from './errors.js'
 
+export function expandHomePath(rawPath: string | undefined): string | undefined {
+  if (!rawPath) return undefined
+  if (rawPath === '~') return homedir()
+  if (rawPath.startsWith('~/') || rawPath.startsWith('~\\')) {
+    return join(homedir(), rawPath.slice(2))
+  }
+  return rawPath
+}
+
 export interface CustomAsyncConfig {
   idPath: string
   statusPath: string
@@ -61,15 +71,42 @@ export async function loadMediaConfig(cwd: string, allowProjectConfig: boolean):
   const globalPath = join(homedir(), '.pi', 'agent', 'media-models.json')
   const global = await parseFile(globalPath) ?? EMPTY_CONFIG
   const project = allowProjectConfig ? await parseFile(join(cwd, '.pi', 'media-models.json')) : undefined
+  const rawOutputDir = project?.outputDir ?? global.outputDir
+  const expandedOutputDir = expandHomePath(rawOutputDir)
+  const outputDir = expandedOutputDir ? resolve(cwd, expandedOutputDir) : undefined
+  const providerOptions = { ...(global.providerOptions ?? {}), ...(project?.providerOptions ?? {}) }
+  if (providerOptions.vertex) providerOptions.vertex = await resolveVertexProjectOptions(providerOptions.vertex)
   const merged: MediaConfig = {
-    outputDir: project?.outputDir ?? global.outputDir,
+    outputDir,
     customProviders: project?.customProviders ?? global.customProviders ?? [],
-    providerOptions: { ...(global.providerOptions ?? {}), ...(project?.providerOptions ?? {}) },
+    providerOptions,
   }
   validateCustomProviders(merged.customProviders)
   return merged
 }
 
+export async function resolveVertexProjectOptions(options: JsonObject): Promise<JsonObject> {
+  const configuredProject = typeof options.project === 'string' ? options.project.trim() : ''
+  if (configuredProject && !isProjectPlaceholder(configuredProject)) return options
+  if (typeof options.credentialsFile !== 'string' || !options.credentialsFile.trim()) return options
+  const expanded = expandHomePath(options.credentialsFile)
+  const credentialsFile = expanded?.startsWith('file://') ? fileURLToPath(expanded) : expanded
+  if (!credentialsFile) return options
+  try {
+    const credentials = JSON.parse(await readFile(credentialsFile, 'utf8')) as { project_id?: unknown }
+    return typeof credentials.project_id === 'string' && credentials.project_id.trim()
+      ? { ...options, project: credentials.project_id.trim() }
+      : options
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return options
+    throw new MediaError('CONFIG', `Invalid Vertex credentials ${credentialsFile}: ${error instanceof Error ? error.message : String(error)}`, { cause: error })
+  }
+}
+
+function isProjectPlaceholder(value: string): boolean {
+  return /^(?:my-gcp-project|your[-_ ]?(?:gcp[-_ ])?project(?:[-_ ]?id)?|<.*>)$/i.test(value)
+}
+
 function validateCustomProviders(providers: CustomProviderConfig[]): void {
   const ids = new Set<string>()
   for (const provider of providers) {

package/src/router.ts

@@ -3,7 +3,7 @@ import type { MediaConfig } from './config.js'
 import { asMediaError, MediaError } from './errors.js'
 import { HttpClient, type FetchLike } from './http.js'
 import { InputResolver } from './input.js'
-import type { AdapterContext, Capability, MediaRequest, ModelDescriptor, NormalizedResult, ProviderAdapter } from './types.js'
+import type { AdapterContext, Capability, MediaRequest, ModelDescriptor, ModelDiscoveryContext, NormalizedResult, ProviderAdapter } from './types.js'
 import { AtlasAdapter } from './adapters/atlas.js'
 import { CustomOpenAICompatibleAdapter } from './adapters/custom.js'
 import { DashScopeAdapter } from './adapters/dashscope.js'
@@ -49,17 +49,87 @@ export class CapabilityRouter {
   }
 
   private isConfigured(adapter: ProviderAdapter): boolean {
-    if (!adapter.envKey) return true
-    if (this.env[adapter.envKey]) return true
-    if (this.providerDefaults[adapter.id]?.apiKey) return true
+    if (adapter.id === 'vertex') {
+      const vertexOpts = this.providerDefaults['vertex']
+      if (typeof vertexOpts?.credentialsFile === 'string' && vertexOpts.credentialsFile.trim()) return true
+      if (this.env.GOOGLE_APPLICATION_CREDENTIALS || this.env.VERTEX_CREDENTIALS_FILE) return true
+      return false
+    }
+    const configKey = this.providerDefaults[adapter.id]?.apiKey
+    if (typeof configKey === 'string' && configKey.trim()) return true
+    if (adapter.envKey && this.env[adapter.envKey]) return true
     return false
   }
 
   list(provider?: string, capability?: Capability): Array<ModelDescriptor & { configured: boolean }> {
-    const adapters = provider ? [this.adapters.get(provider)].filter((item): item is ProviderAdapter => Boolean(item)) : [...this.adapters.values()]
+    const adapters = this.selectedAdapters(provider)
     return adapters.flatMap(adapter => adapter.models()
       .filter(model => !capability || model.capabilities.includes(capability))
-      .map(model => ({ ...model, configured: this.isConfigured(adapter) })))
+      .map(model => ({ ...model, configured: this.isConfigured(adapter), availability: 'unknown' as const, source: 'built-in' as const })))
+  }
+
+  async discover(provider?: string, capability?: Capability, context: AdapterContext & { probe?: boolean } = {}): Promise<Array<ModelDescriptor & { configured: boolean }>> {
+    const groups = await Promise.all(this.selectedAdapters(provider).map(async adapter => {
+      const configured = this.isConfigured(adapter)
+      const discoveryContext: ModelDiscoveryContext = {
+        ...(context.signal ? { signal: context.signal } : {}),
+        providerOptions: this.providerDefaults[adapter.id] ?? {},
+      }
+      let models: ModelDescriptor[]
+      if (!configured || !adapter.discoverModels) {
+        models = adapter.models().map(model => ({ ...model, availability: 'unknown', source: 'built-in' }))
+      } else {
+        try {
+          models = (await adapter.discoverModels(discoveryContext)).map(model => ({
+            ...model,
+            availability: model.availability ?? 'available',
+            source: 'discovered',
+          }))
+        } catch (error) {
+          const normalized = asMediaError(error, adapter.id)
+          const message = normalized.status ? `HTTP ${normalized.status}` : normalized.message.split('\n', 1)[0]
+          models = adapter.models().map(model => ({
+            ...model,
+            availability: 'unknown',
+            source: 'built-in',
+            notes: [model.notes, `Discovery failed: ${message}`].filter(Boolean).join('; '),
+          }))
+        }
+      }
+      models = models.filter(model => !capability || model.capabilities.includes(capability))
+      if (configured && context.probe !== false && adapter.probeModel) {
+        models = await Promise.all(models.map(async model => {
+          try {
+            const probeCapability = capability ?? model.capabilities[0]
+            const available = probeCapability ? await adapter.probeModel?.(model, probeCapability, discoveryContext) : undefined
+            return available === undefined ? model : { ...model, availability: available ? 'available' as const : 'unavailable' as const }
+          } catch (error) {
+            const normalized = asMediaError(error, adapter.id)
+            const unavailable = normalized.status === 400 || normalized.status === 403 || normalized.status === 404
+            const probeMessage = unavailable
+              ? `Probe failed: HTTP ${normalized.status} (model unavailable to the configured project/location)`
+              : `Probe failed: ${normalized.message.split('\n', 1)[0]}`
+            return {
+              ...model,
+              availability: unavailable ? 'unavailable' as const : 'unknown' as const,
+              notes: [model.notes, probeMessage].filter(Boolean).join('; '),
+            }
+          }
+        }))
+      }
+      const sorted = models.sort(compareModels)
+      const defaultIndex = sorted.findIndex(model => model.availability !== 'unavailable' && !isPlaceholderModel(model.id))
+      return sorted.map((model, index) => ({ ...model, configured, ...(index === defaultIndex ? { isDefault: true } : {}) }))
+    }))
+    return groups.flat()
+  }
+
+  async defaultModel(provider: string, capability: Capability, context: AdapterContext = {}): Promise<string> {
+    if (!this.adapters.has(provider)) throw new MediaError('CONFIG', `Unknown media provider: ${provider}`)
+    const models = await this.discover(provider, capability, { ...context, probe: true })
+    const selected = models.find(model => model.isDefault)
+    if (!selected) throw new MediaError('CONFIG', `No usable ${capability} model was discovered for ${provider}; specify a model explicitly`, { provider })
+    return selected.id
   }
 
   providers(): Array<{ id: string; name: string; configured: boolean; envKey?: string }> {
@@ -71,6 +141,10 @@ export class CapabilityRouter {
     }))
   }
 
+  private selectedAdapters(provider?: string): ProviderAdapter[] {
+    return provider ? [this.adapters.get(provider)].filter((item): item is ProviderAdapter => Boolean(item)) : [...this.adapters.values()]
+  }
+
   async execute(request: MediaRequest, context: AdapterContext = {}): Promise<NormalizedResult> {
     const adapter = this.adapters.get(request.provider)
     if (!adapter) throw new MediaError('CONFIG', `Unknown media provider: ${request.provider}`)
@@ -93,3 +167,34 @@ export class CapabilityRouter {
     }
   }
 }
+
+function compareModels(left: ModelDescriptor, right: ModelDescriptor): number {
+  const availability = { available: 2, unknown: 1, unavailable: 0 }
+  const availabilityDifference = availability[right.availability ?? 'unknown'] - availability[left.availability ?? 'unknown']
+  if (availabilityDifference) return availabilityDifference
+  if (left.source === 'built-in' && right.source === 'built-in') return 0
+  const familyDifference = modelFamilyPriority(right.id) - modelFamilyPriority(left.id)
+  if (familyDifference) return familyDifference
+  const leftVersion = modelVersion(left.id)
+  const rightVersion = modelVersion(right.id)
+  for (let index = 0; index < Math.max(leftVersion.length, rightVersion.length); index += 1) {
+    const difference = (rightVersion[index] ?? 0) - (leftVersion[index] ?? 0)
+    if (difference) return difference
+  }
+  const previewDifference = Number(/(?:preview|experimental)/i.test(left.id)) - Number(/(?:preview|experimental)/i.test(right.id))
+  return previewDifference || right.id.localeCompare(left.id)
+}
+
+function modelFamilyPriority(id: string): number {
+  if (/gpt-image/i.test(id)) return 2
+  if (/dall-e/i.test(id)) return 1
+  return 0
+}
+
+function modelVersion(id: string): number[] {
+  return [...id.matchAll(/\d+/g)].map(match => Number(match[0]))
+}
+
+function isPlaceholderModel(id: string): boolean {
+  return /^<.*>$/.test(id.trim())
+}

package/src/tools.ts

@@ -7,7 +7,7 @@ import type { Capability, JsonObject, MediaRequest, NormalizedResult } from './t
 
 const providerModel = {
   provider: Type.String({ description: 'Provider id: openrouter, fal, dashscope, qwencloud, openai, gemini, vertex, xai, atlas, or an explicitly configured custom provider' }),
-  model: Type.String({ description: 'Exact provider model id or fal endpoint slug' }),
+  model: Type.Optional(Type.String({ description: 'Exact provider model id or fal endpoint slug. Omit to auto-select the newest discovered usable model.' })),
 }
 const providerOptions = Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: 'Provider-native options. These override normalized mappings; never include API keys.' }))
 const commonOutput = {
@@ -35,10 +35,15 @@ function concise(result: NormalizedResult): string {
   return lines.join('\n')
 }
 
-async function executeRequest(request: MediaRequest, signal: AbortSignal | undefined, onUpdate: Parameters<Parameters<ExtensionAPI['registerTool']>[0]['execute']>[3], ctx: ExtensionContext) {
+type ToolMediaRequest = Omit<MediaRequest, 'model'> & { model?: string }
+
+async function executeRequest(request: ToolMediaRequest, signal: AbortSignal | undefined, onUpdate: Parameters<Parameters<ExtensionAPI['registerTool']>[0]['execute']>[3], ctx: ExtensionContext) {
   const router = await routerFor(ctx)
-  progress(onUpdate as never, `Starting ${request.capability} with ${request.provider}/${request.model}…`)
-  const result = await router.execute(request, {
+  if (!request.model) progress(onUpdate as never, `Discovering the newest usable ${request.capability} model for ${request.provider}…`)
+  const model = request.model?.trim() || await router.defaultModel(request.provider, request.capability, signal ? { signal } : {})
+  const resolvedRequest: MediaRequest = { ...request, model }
+  progress(onUpdate as never, `Starting ${request.capability} with ${request.provider}/${model}…`)
+  const result = await router.execute(resolvedRequest, {
     ...(signal ? { signal } : {}),
     onProgress: message => progress(onUpdate as never, message),
   })
@@ -49,20 +54,22 @@ export function registerMediaTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: 'media_models',
     label: 'Media Models',
-    description: 'List media providers and explicitly known/configured model capabilities. Does not infer custom capabilities from GET /models.',
-    promptSnippet: 'List available media providers/models/capabilities before choosing a model',
+    description: 'Discover models visible to configured provider credentials, optionally probe capability access, and mark the newest usable model as default. Falls back to built-in candidates when a provider has no discovery API.',
+    promptSnippet: 'Discover available media providers/models/capabilities before choosing a model',
     parameters: Type.Object({
       provider: Type.Optional(Type.String()),
       capability: Type.Optional(Type.String()),
+      probe: Type.Optional(Type.Boolean({ description: 'Run lightweight capability probes when supported. Defaults to true.' })),
     }),
-    async execute(_id, params, _signal, _onUpdate, ctx) {
+    async execute(_id, params, signal, onUpdate, ctx) {
       const router = await routerFor(ctx)
       const capability = params.capability as Capability | undefined
-      const models = router.list(params.provider, capability)
+      progress(onUpdate as never, 'Discovering models from configured providers…')
+      const models = await router.discover(params.provider, capability, { ...(signal ? { signal } : {}), probe: params.probe !== false })
       const providers = router.providers()
       const text = models.length
-        ? models.map(model => `${model.provider}/${model.id} [vendor=${model.vendor}; configured=${model.configured}] ${model.capabilities.join(', ')}`).join('\n')
-        : 'No matching declared media models.'
+        ? models.map(model => `${model.provider}/${model.id} [${model.availability}; source=${model.source}; configured=${model.configured}${model.isDefault ? '; default=newest' : ''}] ${model.capabilities.join(', ')}${model.notes ? ` · ${model.notes}` : ''}`).join('\n')
+        : 'No matching media models were discovered.'
       return { content: [{ type: 'text', text }], details: { providers, models } }
     },
   })

package/src/types.ts

@@ -123,12 +123,18 @@ export interface MediaJobOptions<T> {
   onProgress?: (status: JobStatus<T>) => void
 }
 
+export type ModelAvailability = 'available' | 'unavailable' | 'unknown'
+export type ModelSource = 'discovered' | 'built-in'
+
 export interface ModelDescriptor {
   provider: string
   vendor: string
   id: string
   capabilities: Capability[]
   notes?: string
+  availability?: ModelAvailability
+  source?: ModelSource
+  isDefault?: boolean
 }
 
 export interface AdapterContext {
@@ -136,11 +142,17 @@ export interface AdapterContext {
   onProgress?: (message: string) => void
 }
 
+export interface ModelDiscoveryContext extends AdapterContext {
+  providerOptions?: JsonObject
+}
+
 export interface ProviderAdapter {
   readonly id: string
   readonly displayName: string
   readonly envKey?: string
   models(): ModelDescriptor[]
+  discoverModels?(context: ModelDiscoveryContext): Promise<ModelDescriptor[]>
+  probeModel?(model: ModelDescriptor, capability: Capability, context: ModelDiscoveryContext): Promise<boolean | undefined>
   supports(capability: Capability, model: string): boolean
   execute(request: MediaRequest, context: AdapterContext): Promise<AdapterResult>
 }