pi-media-models 0.1.0

package/src/input.ts

@@ -0,0 +1,104 @@
+import { readFile } from 'node:fs/promises'
+import { basename, extname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { MediaError } from './errors.js'
+import { HttpClient } from './http.js'
+import type { ResolvedInput } from './types.js'
+
+const MIME_BY_EXTENSION: Record<string, string> = {
+  '.aac': 'audio/aac', '.flac': 'audio/flac', '.gif': 'image/gif', '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg', '.m4a': 'audio/mp4', '.mkv': 'video/x-matroska', '.mov': 'video/quicktime',
+  '.mp3': 'audio/mpeg', '.mp4': 'video/mp4', '.mpeg': 'video/mpeg', '.oga': 'audio/ogg',
+  '.ogg': 'audio/ogg', '.png': 'image/png', '.wav': 'audio/wav', '.webm': 'video/webm',
+  '.webp': 'image/webp',
+}
+
+export function mimeFromName(name: string, fallback = 'application/octet-stream'): string {
+  const clean = name.split(/[?#]/, 1)[0] ?? name
+  return MIME_BY_EXTENSION[extname(clean).toLowerCase()] ?? fallback
+}
+
+function extensionForMime(mime: string): string {
+  return Object.entries(MIME_BY_EXTENSION).find(([, value]) => value === mime)?.[0] ?? '.bin'
+}
+
+function decodeDataUri(input: string): { bytes: Uint8Array; mimeType: string } {
+  const match = /^data:([^;,]+)?((?:;[^,]*)*?),(.*)$/s.exec(input)
+  if (!match) throw new MediaError('INPUT', 'Invalid data URI')
+  const mimeType = match[1] || 'application/octet-stream'
+  const metadata = match[2] ?? ''
+  const payload = match[3] ?? ''
+  try {
+    return {
+      mimeType,
+      bytes: metadata.includes(';base64')
+        ? Buffer.from(payload, 'base64')
+        : Buffer.from(decodeURIComponent(payload), 'utf8'),
+    }
+  } catch (error) {
+    throw new MediaError('INPUT', 'Invalid data URI payload', { cause: error })
+  }
+}
+
+export class InputResolver {
+  constructor(private readonly http: HttpClient, private readonly cwd = process.cwd()) {}
+
+  async resolve(input: string): Promise<ResolvedInput> {
+    const value = input.startsWith('@') ? input.slice(1) : input
+    if (/^https?:\/\//i.test(value)) {
+      const parsed = new URL(value)
+      const fileName = basename(parsed.pathname) || 'remote.bin'
+      return { original: input, kind: 'url', url: value, mimeType: mimeFromName(fileName), fileName }
+    }
+    if (value.startsWith('data:')) {
+      const decoded = decodeDataUri(value)
+      return {
+        original: input,
+        kind: 'data',
+        bytes: decoded.bytes,
+        mimeType: decoded.mimeType,
+        fileName: `inline${extensionForMime(decoded.mimeType)}`,
+      }
+    }
+
+    const path = value.startsWith('file://') ? fileURLToPath(value) : resolve(this.cwd, value)
+    try {
+      const bytes = await readFile(path)
+      return {
+        original: input,
+        kind: 'file',
+        bytes,
+        mimeType: mimeFromName(path),
+        fileName: basename(path),
+      }
+    } catch (error) {
+      throw new MediaError('INPUT', `Cannot read media input: ${path}`, { cause: error })
+    }
+  }
+
+  async bytes(input: ResolvedInput, signal?: AbortSignal): Promise<Uint8Array> {
+    if (input.bytes) return input.bytes
+    if (!input.url) throw new MediaError('INPUT', `Input has no readable data: ${input.original}`)
+    const response = await this.http.request(input.url, { signal, timeoutMs: 60_000, retries: 1 })
+    return new Uint8Array(await response.arrayBuffer())
+  }
+
+  async asDataUri(source: string, signal?: AbortSignal): Promise<string> {
+    const input = await this.resolve(source)
+    if (input.kind === 'url') return input.url ?? source
+    const bytes = await this.bytes(input, signal)
+    return `data:${input.mimeType};base64,${Buffer.from(bytes).toString('base64')}`
+  }
+
+  async asInlineData(source: string, signal?: AbortSignal): Promise<{ mimeType: string; data: string }> {
+    const input = await this.resolve(source)
+    const bytes = await this.bytes(input, signal)
+    return { mimeType: input.mimeType, data: Buffer.from(bytes).toString('base64') }
+  }
+
+  async asBlob(source: string, signal?: AbortSignal): Promise<{ blob: Blob; fileName: string; mimeType: string }> {
+    const input = await this.resolve(source)
+    const bytes = await this.bytes(input, signal)
+    return { blob: new Blob([Uint8Array.from(bytes)], { type: input.mimeType }), fileName: input.fileName, mimeType: input.mimeType }
+  }
+}

package/src/media-job.ts

@@ -0,0 +1,89 @@
+import { MediaError } from './errors.js'
+import type { JobStatus, MediaJobOptions } from './types.js'
+
+function wait(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const done = () => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }
+    const timer = setTimeout(done, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      reject(new DOMException('Aborted', 'AbortError'))
+    }
+    if (signal.aborted) return onAbort()
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+export class MediaJob<T> {
+  constructor(private readonly options: MediaJobOptions<T>) {}
+
+  async wait(): Promise<T> {
+    const {
+      timeoutMs = 20 * 60_000,
+      minDelayMs = 1_000,
+      maxDelayMs = 10_000,
+      provider,
+    } = this.options
+    const timeoutController = new AbortController()
+    const timer = setTimeout(() => timeoutController.abort(new DOMException('Job timed out', 'TimeoutError')), timeoutMs)
+    const signal = this.options.signal
+      ? AbortSignal.any([this.options.signal, timeoutController.signal])
+      : timeoutController.signal
+    let delay = minDelayMs
+
+    try {
+      while (true) {
+        const status = await this.options.poll(signal)
+        this.options.onProgress?.(status)
+        if (status.state === 'succeeded') {
+          if (status.result === undefined) throw new MediaError('PROVIDER', `${provider} job completed without a result`, { provider })
+          return status.result
+        }
+        if (status.state === 'failed' || status.state === 'cancelled') {
+          throw new MediaError('PROVIDER', status.message ?? `${provider} job ${status.state}`, { provider })
+        }
+        const sleepFor = status.retryAfterMs ?? delay
+        await wait(sleepFor, signal)
+        delay = Math.min(maxDelayMs, Math.round(delay * 1.7))
+      }
+    } catch (error) {
+      if (this.options.signal?.aborted) {
+        await this.cancelBestEffort()
+        throw new MediaError('ABORTED', `${provider} job ${this.options.id} aborted`, { provider, cause: error })
+      }
+      if (timeoutController.signal.aborted) {
+        await this.cancelBestEffort()
+        throw new MediaError('TIMEOUT', `${provider} job ${this.options.id} timed out after ${timeoutMs}ms`, { provider, cause: error })
+      }
+      throw error
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  private async cancelBestEffort(): Promise<void> {
+    if (!this.options.cancel) return
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), 5_000)
+    try {
+      await this.options.cancel(controller.signal)
+    } catch {
+      // Cancellation is advisory; preserve the original abort/timeout error.
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+}
+
+export function mapJobState(raw: unknown): JobStatus<never>['state'] {
+  const value = String(raw ?? '').toLowerCase().replace(/[\s-]+/g, '_')
+  if (['completed', 'complete', 'succeeded', 'success', 'done', 'ready'].includes(value)) return 'succeeded'
+  if (['failed', 'failure', 'error'].includes(value)) return 'failed'
+  if (['cancelled', 'canceled'].includes(value)) return 'cancelled'
+  if (['queued', 'pending', 'submitted', 'created'].includes(value)) return 'queued'
+  return 'running'
+}

package/src/router.ts

@@ -0,0 +1,95 @@
+import { ArtifactDownloader } from './artifacts.js'
+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 { AtlasAdapter } from './adapters/atlas.js'
+import { CustomOpenAICompatibleAdapter } from './adapters/custom.js'
+import { DashScopeAdapter } from './adapters/dashscope.js'
+import { FalAdapter } from './adapters/fal.js'
+import { GoogleMediaAdapter } from './adapters/google.js'
+import { OpenAIAdapter } from './adapters/openai.js'
+import { OpenRouterAdapter } from './adapters/openrouter.js'
+import { XAIAdapter } from './adapters/xai.js'
+
+export interface RouterOptions {
+  cwd: string
+  config: MediaConfig
+  env?: NodeJS.ProcessEnv
+  fetch?: FetchLike
+}
+
+export class CapabilityRouter {
+  private readonly adapters = new Map<string, ProviderAdapter>()
+  private readonly downloader: ArtifactDownloader
+  private readonly env: NodeJS.ProcessEnv
+  private readonly providerDefaults: Record<string, Record<string, unknown>>
+
+  constructor(options: RouterOptions) {
+    const http = new HttpClient(options.fetch)
+    const input = new InputResolver(http, options.cwd)
+    const dependencies = { http, input, ...(options.env ? { env: options.env } : {}) }
+    this.env = options.env ?? process.env
+    this.providerDefaults = options.config.providerOptions ?? {}
+    const builtins: ProviderAdapter[] = [
+      new OpenRouterAdapter(dependencies),
+      new FalAdapter(dependencies),
+      new DashScopeAdapter('dashscope', 'https://dashscope.aliyuncs.com', dependencies),
+      new DashScopeAdapter('qwencloud', 'https://dashscope-intl.aliyuncs.com', dependencies),
+      new OpenAIAdapter(dependencies),
+      new GoogleMediaAdapter('gemini', dependencies),
+      new GoogleMediaAdapter('vertex', dependencies),
+      new XAIAdapter(dependencies),
+      new AtlasAdapter(dependencies),
+      ...options.config.customProviders.map(provider => new CustomOpenAICompatibleAdapter(provider, dependencies)),
+    ]
+    for (const adapter of builtins) this.adapters.set(adapter.id, adapter)
+    this.downloader = new ArtifactDownloader(http, options.config.outputDir)
+  }
+
+  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
+    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()]
+    return adapters.flatMap(adapter => adapter.models()
+      .filter(model => !capability || model.capabilities.includes(capability))
+      .map(model => ({ ...model, configured: this.isConfigured(adapter) })))
+  }
+
+  providers(): Array<{ id: string; name: string; configured: boolean; envKey?: string }> {
+    return [...this.adapters.values()].map(adapter => ({
+      id: adapter.id,
+      name: adapter.displayName,
+      configured: this.isConfigured(adapter),
+      ...(adapter.envKey ? { envKey: adapter.envKey } : {}),
+    }))
+  }
+
+  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}`)
+    const providerOptions = { ...(this.providerDefaults[request.provider] ?? {}), ...(request.providerOptions ?? {}) }
+    const resolvedRequest: MediaRequest = { ...request, providerOptions }
+    try {
+      const result = await adapter.execute(resolvedRequest, context)
+      const artifacts = await this.downloader.downloadAll(result.artifacts, context.signal)
+      return {
+        provider: result.provider,
+        model: result.model,
+        capability: result.capability,
+        artifacts,
+        warnings: result.warnings ?? [],
+        ...(result.jobId ? { jobId: result.jobId } : {}),
+        ...(result.text ? { text: result.text } : {}),
+      }
+    } catch (error) {
+      throw asMediaError(error, adapter.id)
+    }
+  }
+}

package/src/tools.ts

@@ -0,0 +1,205 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+import { loadMediaConfig } from './config.js'
+import { MediaError } from './errors.js'
+import { CapabilityRouter } from './router.js'
+import type { Capability, JsonObject, MediaRequest, NormalizedResult } from './types.js'
+
+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' }),
+}
+const providerOptions = Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: 'Provider-native options. These override normalized mappings; never include API keys.' }))
+const commonOutput = {
+  resolution: Type.Optional(Type.String()),
+  aspectRatio: Type.Optional(Type.String()),
+  seed: Type.Optional(Type.Integer()),
+  providerOptions,
+}
+
+async function routerFor(ctx: ExtensionContext): Promise<CapabilityRouter> {
+  const config = await loadMediaConfig(ctx.cwd, ctx.isProjectTrusted())
+  return new CapabilityRouter({ cwd: ctx.cwd, config })
+}
+
+function progress(onUpdate: ((result: { content: Array<{ type: 'text'; text: string }>; details?: unknown }) => void) | undefined, message: string): void {
+  onUpdate?.({ content: [{ type: 'text', text: message }] })
+}
+
+function concise(result: NormalizedResult): string {
+  const lines = [`${result.provider}/${result.model} · ${result.capability}`]
+  if (result.artifacts.length) lines.push(...result.artifacts.map(artifact => `Saved ${artifact.kind}: ${artifact.path}`))
+  if (result.text) lines.push(result.text)
+  if (result.jobId) lines.push(`Job: ${result.jobId}`)
+  if (result.warnings.length) lines.push(`Warnings: ${result.warnings.join('; ')}`)
+  return lines.join('\n')
+}
+
+async function executeRequest(request: MediaRequest, 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, {
+    ...(signal ? { signal } : {}),
+    onProgress: message => progress(onUpdate as never, message),
+  })
+  return { content: [{ type: 'text' as const, text: concise(result) }], details: result }
+}
+
+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',
+    parameters: Type.Object({
+      provider: Type.Optional(Type.String()),
+      capability: Type.Optional(Type.String()),
+    }),
+    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)
+      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.'
+      return { content: [{ type: 'text', text }], details: { providers, models } }
+    },
+  })
+
+  pi.registerTool({
+    name: 'image_generate',
+    label: 'Generate Image',
+    description: 'Generate an image from text or reference image(s). Inputs accept local paths, file://, http(s) URLs, and data URIs. Results are downloaded automatically.',
+    promptSnippet: 'Generate images through the provider-neutral media router',
+    parameters: Type.Object({
+      ...providerModel,
+      prompt: Type.String(),
+      inputImage: Type.Optional(Type.String()),
+      referenceImages: Type.Optional(Type.Array(Type.String())),
+      count: Type.Optional(Type.Integer({ minimum: 1, maximum: 16 })),
+      ...commonOutput,
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const references = params.referenceImages ?? []
+      const capability: Capability = references.length + (params.inputImage ? 1 : 0) > 1
+        ? 'image.multi_reference'
+        : params.inputImage || references.length ? 'image.image_to_image' : 'image.text_to_image'
+      return executeRequest({ ...params, capability, providerOptions: params.providerOptions as JsonObject | undefined }, signal, onUpdate, ctx)
+    },
+  })
+
+  pi.registerTool({
+    name: 'image_edit',
+    label: 'Edit Image',
+    description: 'Edit one or more images with an optional mask. Inputs accept local paths, file://, http(s) URLs, and data URIs. Results are downloaded automatically.',
+    promptSnippet: 'Edit images through the provider-neutral media router',
+    parameters: Type.Object({
+      ...providerModel,
+      prompt: Type.String(),
+      inputImage: Type.String(),
+      referenceImages: Type.Optional(Type.Array(Type.String())),
+      mask: Type.Optional(Type.String()),
+      count: Type.Optional(Type.Integer({ minimum: 1, maximum: 16 })),
+      ...commonOutput,
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const capability: Capability = params.referenceImages?.length ? 'image.multi_reference' : 'image.edit'
+      return executeRequest({ ...params, capability, providerOptions: params.providerOptions as JsonObject | undefined }, signal, onUpdate, ctx)
+    },
+  })
+
+  pi.registerTool({
+    name: 'video_generate',
+    label: 'Generate Video',
+    description: 'Unified video generation/edit/extension tool. Automatically maps text, first/end frames, references, and input video to the provider capability; downloads temporary results immediately.',
+    promptSnippet: 'Generate, edit, or extend video through the provider-neutral media router',
+    parameters: Type.Object({
+      ...providerModel,
+      prompt: Type.String(),
+      inputImage: Type.Optional(Type.String()),
+      endImage: Type.Optional(Type.String()),
+      referenceImages: Type.Optional(Type.Array(Type.String())),
+      referenceVideos: Type.Optional(Type.Array(Type.String())),
+      referenceAudios: Type.Optional(Type.Array(Type.String())),
+      inputVideo: Type.Optional(Type.String()),
+      duration: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+      resolution: Type.Optional(Type.String()),
+      aspectRatio: Type.Optional(Type.String()),
+      seed: Type.Optional(Type.Integer()),
+      generateAudio: Type.Optional(Type.Boolean()),
+      operation: Type.Optional(Type.String({ description: 'generate, reference, edit, or extend; omitted for automatic mapping' })),
+      providerOptions,
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const capability = videoCapability(params)
+      return executeRequest({ ...params, capability, providerOptions: params.providerOptions as JsonObject | undefined }, signal, onUpdate, ctx)
+    },
+  })
+
+  pi.registerTool({
+    name: 'audio_generate',
+    label: 'Generate Audio',
+    description: 'Generate music or model-native audio from a prompt. This is separate from TTS and downloads the result automatically.',
+    promptSnippet: 'Generate music or audio through the provider-neutral media router',
+    parameters: Type.Object({
+      ...providerModel,
+      prompt: Type.String(),
+      text: Type.Optional(Type.String({ description: 'Optional lyrics or secondary text input' })),
+      inputAudio: Type.Optional(Type.String()),
+      duration: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+      seed: Type.Optional(Type.Integer()),
+      providerOptions,
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      return executeRequest({ ...params, capability: 'audio.generate', providerOptions: params.providerOptions as JsonObject | undefined }, signal, onUpdate, ctx)
+    },
+  })
+
+  pi.registerTool({
+    name: 'speech_generate',
+    label: 'Speech',
+    description: 'Run provider-supported TTS or STT. Use operation="tts" with text, or operation="stt" with inputAudio. Generated audio is downloaded; STT returns concise text.',
+    promptSnippet: 'Synthesize speech or transcribe audio through the provider-neutral media router',
+    parameters: Type.Object({
+      ...providerModel,
+      operation: Type.String({ description: 'tts or stt' }),
+      text: Type.Optional(Type.String()),
+      inputAudio: Type.Optional(Type.String()),
+      prompt: Type.Optional(Type.String()),
+      voice: Type.Optional(Type.String()),
+      language: Type.Optional(Type.String()),
+      responseFormat: Type.Optional(Type.String()),
+      providerOptions,
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const operation = params.operation.toLowerCase()
+      if (!['tts', 'stt', 'transcribe'].includes(operation)) throw new MediaError('INPUT', 'speech_generate operation must be tts or stt')
+      const capability: Capability = operation === 'tts' ? 'speech.tts' : 'speech.stt'
+      if (capability === 'speech.tts' && !params.text && !params.prompt) throw new MediaError('INPUT', 'TTS requires text')
+      if (capability === 'speech.stt' && !params.inputAudio) throw new MediaError('INPUT', 'STT requires inputAudio')
+      return executeRequest({ ...params, capability, providerOptions: params.providerOptions as JsonObject | undefined }, signal, onUpdate, ctx)
+    },
+  })
+}
+
+function videoCapability(params: {
+  operation?: string
+  inputImage?: string
+  endImage?: string
+  inputVideo?: string
+  referenceImages?: string[]
+  referenceVideos?: string[]
+  referenceAudios?: string[]
+}): Capability {
+  const operation = params.operation?.toLowerCase()
+  if (operation === 'edit') return 'video.edit'
+  if (operation === 'extend') return 'video.extend'
+  if (operation === 'reference') return 'video.reference'
+  if (operation && operation !== 'generate') throw new MediaError('INPUT', 'video_generate operation must be generate, reference, edit, or extend')
+  if (params.inputVideo) return 'video.edit'
+  if (params.referenceImages?.length || params.referenceVideos?.length || params.referenceAudios?.length) return 'video.reference'
+  if (params.endImage) return 'video.first_last_frame'
+  if (params.inputImage) return 'video.image_to_video'
+  return 'video.text_to_video'
+}

package/src/types.ts

@@ -0,0 +1,146 @@
+export const CAPABILITIES = [
+  'image.text_to_image',
+  'image.image_to_image',
+  'image.edit',
+  'image.multi_reference',
+  'video.text_to_video',
+  'video.image_to_video',
+  'video.first_last_frame',
+  'video.reference',
+  'video.edit',
+  'video.extend',
+  'video.native_audio',
+  'audio.generate',
+  'speech.tts',
+  'speech.stt',
+] as const
+
+export type Capability = (typeof CAPABILITIES)[number]
+export type ProviderId =
+  | 'openrouter'
+  | 'fal'
+  | 'dashscope'
+  | 'qwencloud'
+  | 'openai'
+  | 'gemini'
+  | 'vertex'
+  | 'xai'
+  | 'atlas'
+  | string
+
+export type MediaKind = 'image' | 'video' | 'audio' | 'text'
+export type InputSource = string
+export type JsonObject = Record<string, unknown>
+
+export interface MediaRequest {
+  capability: Capability
+  provider: ProviderId
+  model: string
+  prompt?: string
+  inputImage?: InputSource
+  endImage?: InputSource
+  referenceImages?: InputSource[]
+  referenceVideos?: InputSource[]
+  referenceAudios?: InputSource[]
+  inputVideo?: InputSource
+  inputAudio?: InputSource
+  mask?: InputSource
+  duration?: number
+  resolution?: string
+  aspectRatio?: string
+  seed?: number
+  count?: number
+  generateAudio?: boolean
+  operation?: string
+  text?: string
+  voice?: string
+  language?: string
+  responseFormat?: string
+  providerOptions?: JsonObject
+}
+
+export interface ResolvedInput {
+  original: string
+  kind: 'url' | 'data' | 'file'
+  mimeType: string
+  fileName: string
+  bytes?: Uint8Array
+  url?: string
+}
+
+export interface RemoteArtifact {
+  kind: MediaKind
+  url?: string
+  base64?: string
+  mimeType?: string
+  fileName?: string
+  headers?: Record<string, string>
+}
+
+export interface NormalizedArtifact {
+  kind: MediaKind
+  path: string
+  mimeType?: string
+  bytes?: number
+}
+
+export interface AdapterResult {
+  provider: string
+  model: string
+  capability: Capability
+  jobId?: string
+  artifacts: RemoteArtifact[]
+  text?: string
+  warnings?: string[]
+}
+
+export interface NormalizedResult {
+  provider: string
+  model: string
+  capability: Capability
+  jobId?: string
+  artifacts: NormalizedArtifact[]
+  text?: string
+  warnings: string[]
+}
+
+export interface JobStatus<T> {
+  state: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled'
+  result?: T
+  message?: string
+  retryAfterMs?: number
+}
+
+export interface MediaJobOptions<T> {
+  id: string
+  provider: string
+  poll: (signal: AbortSignal) => Promise<JobStatus<T>>
+  cancel?: (signal: AbortSignal) => Promise<void>
+  timeoutMs?: number
+  minDelayMs?: number
+  maxDelayMs?: number
+  signal?: AbortSignal
+  onProgress?: (status: JobStatus<T>) => void
+}
+
+export interface ModelDescriptor {
+  provider: string
+  vendor: string
+  id: string
+  capabilities: Capability[]
+  notes?: string
+}
+
+export interface AdapterContext {
+  signal?: AbortSignal
+  onProgress?: (message: string) => void
+}
+
+export interface ProviderAdapter {
+  readonly id: string
+  readonly displayName: string
+  readonly envKey?: string
+  models(): ModelDescriptor[]
+  supports(capability: Capability, model: string): boolean
+  execute(request: MediaRequest, context: AdapterContext): Promise<AdapterResult>
+}