@ouraihub/aether-ui 0.0.0-stage → 0.1.0

package/src/providers/draft.ts

@@ -0,0 +1,329 @@
+// Editable form of a provider and its conversion to save/probe requests (docs/11 §3, §7); key helpers (docs/34 §5).
+import type { KitI18n } from '../i18n'
+import { allowsAuto, dialectFits } from './reasoning'
+import {
+  isKitClientError,
+  type Endpoint,
+  type EndpointKey,
+  type KeyStrategy,
+  type EndpointSave,
+  type Model,
+  type ProbeResult,
+  type ModelSave,
+  type ModelType,
+  type ProbeTarget,
+  type Protocol,
+  type Provider,
+  type ProviderSave,
+} from '../ports'
+
+export interface EndpointDraft {
+  /** Stored endpoint, `null` for a new one. Its `id` must go back on save (docs/11 陷阱 1). */
+  saved: Endpoint | null
+  slug: string
+  baseUrl: string
+  protocol: Protocol
+  keyStrategy: KeyStrategy
+  /** `null` = paint at `baseUrl` (docs/36 §3.4). */
+  imageBaseUrl: string | null
+  /** `null` = edit at `baseUrl` (docs/37 §2). */
+  imageEditBaseUrl: string | null
+  headers: Endpoint['headers']
+  models: Model[]
+}
+
+export interface ProviderDraft {
+  id: string | null
+  name: string
+  enabled: boolean
+  notes: string
+  endpoints: EndpointDraft[]
+}
+
+export function toDraft(provider: Provider): ProviderDraft {
+  return {
+    id: provider.id,
+    name: provider.name,
+    enabled: provider.enabled,
+    notes: provider.notes,
+    endpoints: provider.endpoints.map((saved) => ({
+      saved,
+      slug: saved.slug,
+      baseUrl: saved.baseUrl,
+      protocol: saved.protocol,
+      keyStrategy: saved.keyStrategy,
+      imageBaseUrl: saved.imageBaseUrl,
+      imageEditBaseUrl: saved.imageEditBaseUrl,
+      headers: saved.headers,
+      models: saved.models,
+    })),
+  }
+}
+
+export function newEndpoint(taken: readonly EndpointDraft[]): EndpointDraft {
+  return {
+    saved: null,
+    slug: nextSlug(taken),
+    baseUrl: '',
+    protocol: 'openai-chat',
+    keyStrategy: 'round_robin',
+    imageBaseUrl: null,
+    imageEditBaseUrl: null,
+    headers: {},
+    models: [],
+  }
+}
+
+/** First free `ep-N`; slugs are unique per provider and hidden from users. */
+export function nextSlug(taken: readonly EndpointDraft[]): string {
+  const used = new Set(taken.map((endpoint) => endpoint.slug))
+  let n = taken.length + 1
+  while (used.has(`ep-${n}`)) n++
+  return `ep-${n}`
+}
+
+export const validUrl = (url: string): boolean => /^https?:\/\/\S+$/.test(url.trim())
+
+/** Endpoints are stored even without an address (keys hang on them); only a malformed address stays local. */
+export function savable(draft: ProviderDraft): ProviderDraft {
+  return {
+    ...draft,
+    endpoints: draft.endpoints.filter((e) => e.saved !== null || !e.baseUrl.trim() || validUrl(e.baseUrl)),
+  }
+}
+
+/**
+ * Takes the stored provider after a save without discarding what the user typed meanwhile:
+ * sent endpoints get their stored record (new ones matched by slug); edits stay in the draft.
+ */
+export function adopt(current: ProviderDraft, sent: ProviderDraft, stored: Provider): ProviderDraft {
+  const sentEndpoints = new Map(sent.endpoints.map((endpoint) => [endpoint.slug, endpoint]))
+  return {
+    ...current,
+    id: stored.id,
+    endpoints: current.endpoints.map((endpoint) => {
+      const original = sentEndpoints.get(endpoint.slug)
+      const record =
+        original &&
+        stored.endpoints.find((item) => (original.saved ? item.id === original.saved.id : item.slug === original.slug))
+      return record ? { ...endpoint, saved: record } : endpoint
+    }),
+  }
+}
+
+/** Probe selection preserves every existing user field; only new models take probe defaults. */
+export function mergeModels(
+  current: readonly Model[],
+  probed: ProbeResult['models'],
+  checked: Readonly<Record<string, boolean>>,
+  types: Readonly<Record<string, ModelType>> = {},
+): Model[] {
+  const fetched = new Set(probed.map((model) => model.id))
+  const existing = new Map(current.map((model) => [model.id, model]))
+  const merged = new Map(current.filter((model) => !fetched.has(model.id)).map((model) => [model.id, model]))
+  for (const model of probed) {
+    if (!checked[model.id] || merged.has(model.id)) continue
+    const previous = existing.get(model.id)
+    const base: Model = previous ?? {
+      id: model.id,
+      name: model.name,
+      groupName: model.group,
+      modelType: model.modelType,
+      typeSource: model.typeSource,
+      contextWindow: model.contextWindow,
+      maxOutput: model.maxOutput,
+      reasoning: model.reasoning,
+      nativeWebSearch: model.nativeWebSearch,
+      pricing: model.pricing,
+      canVision: model.canVision,
+      supportsTools: model.supportsTools,
+    }
+    merged.set(model.id, withType(base, types[model.id] ?? base.modelType))
+  }
+  return [...merged.values()]
+}
+
+export function toSave(draft: ProviderDraft): ProviderSave {
+  const endpoints = draft.endpoints.map((e): EndpointSave => {
+    const save: EndpointSave = {
+      slug: e.slug.trim(),
+      baseUrl: e.baseUrl.trim(),
+      protocol: e.protocol,
+      keyStrategy: e.keyStrategy,
+      imageBaseUrl: e.imageBaseUrl?.trim() || null,
+      imageEditBaseUrl: e.imageEditBaseUrl?.trim() || null,
+      headers: e.headers,
+      models: e.models.map((model) => {
+        const save: ModelSave = {
+          ...model,
+          nativeWebSearch: model.modelType === 'chat' && e.protocol !== 'openai-chat' && model.nativeWebSearch,
+        }
+        // Contract §2: omitted reasoning keeps the stored value, so an untouched (possibly inferred) value is not frozen.
+        // Key order matches: edits spread the stored config and append `budgetTokens` last, like serde.
+        const before = e.saved?.models.find((item) => item.id === model.id)
+        const unchanged = before
+          ? JSON.stringify(before.reasoning) === JSON.stringify(model.reasoning)
+          : model.reasoning === null
+        if (unchanged) delete save.reasoning
+        return save
+      }),
+    }
+    if (e.saved) save.id = e.saved.id
+    return save
+  })
+  const save = { name: draft.name.trim(), enabled: draft.enabled, notes: draft.notes, endpoints }
+  return draft.id === null ? save : { id: draft.id, ...save }
+}
+
+/** Model list group: the user's group name, else the id prefix (`gpt-4o` → `gpt`). */
+export const idPrefix = (id: string): string => id.split(/[-/:]/)[0] || ''
+export const groupKey = (model: Model): string => model.groupName ?? idPrefix(model.id)
+
+/** Purpose maps onto existing fields (docs/41 §3.3): edit = image + canVision. */
+export type Purpose = 'chat' | 'image' | 'edit'
+export const purposeOf = (model: Model): Purpose | null =>
+  model.modelType === 'chat' ? 'chat' : model.modelType === 'image' ? (model.canVision ? 'edit' : 'image') : null
+export function withPurpose(model: Model, purpose: Purpose): Model {
+  const typed = withType(model, purpose === 'chat' ? 'chat' : 'image')
+  return purpose === 'chat' ? typed : { ...typed, canVision: purpose === 'edit' }
+}
+/** A user-chosen type; leaving chat drops chat-only settings the backend would reject. */
+export function withType(model: Model, modelType: ModelType): Model {
+  if (modelType === model.modelType) return model
+  const next: Model = { ...model, modelType, typeSource: 'user' }
+  return modelType === 'chat' ? next : { ...next, reasoning: null, nativeWebSearch: false, pricing: null }
+}
+
+export type ModelField = 'name' | 'groupName' | 'contextWindow' | 'maxOutput' | 'reasoning' | 'pricing'
+export interface ModelError {
+  field: ModelField
+  reason: string
+}
+
+/** Front-end mirror of the backend model rules (contract §3); reason codes match `bad_request(field, reason)`. */
+export function validateModel(model: Model, protocol: Protocol): ModelError[] {
+  const errors: ModelError[] = []
+  const add = (field: ModelField, reason: string) => errors.push({ field, reason })
+  for (const field of ['name', 'groupName'] as const)
+    if ([...(model[field]?.trim() ?? '')].length > 80) add(field, 'too_long')
+  const { contextWindow, maxOutput, reasoning, pricing } = model
+  const chat = model.modelType === 'chat'
+  // Non-integers also fail the backend's integer schema; doc §4.2 shows them as the same `invalid`.
+  if (contextWindow !== null && !(Number.isInteger(contextWindow) && contextWindow >= 1))
+    add('contextWindow', 'invalid')
+  if (maxOutput !== null && !(Number.isInteger(maxOutput) && maxOutput >= 1)) add('maxOutput', 'invalid')
+  else if (chat && contextWindow !== null && maxOutput !== null && maxOutput >= contextWindow)
+    add('maxOutput', 'exceeds_context')
+  if (reasoning) {
+    const { efforts, dialect, budgetTokens } = reasoning
+    if (
+      !chat ||
+      !efforts.length ||
+      efforts.includes('default') ||
+      (efforts.includes('auto') && !allowsAuto(dialect)) ||
+      new Set(efforts).size !== efforts.length
+    )
+      add('reasoning', 'invalid_efforts')
+    else if (!dialectFits(dialect, protocol)) add('reasoning', 'protocol_mismatch')
+    else if (dialect === 'anthropic-budget') {
+      if (budgetTokens == null || budgetTokens < 1024 || budgetTokens >= (maxOutput ?? 4096))
+        add('reasoning', 'invalid_budget')
+    } else if (dialect === 'qwen') {
+      if (budgetTokens === 0) add('reasoning', 'invalid_budget')
+    } else if (budgetTokens != null) add('reasoning', 'unexpected_budget')
+  }
+  if (pricing) {
+    const { tiers } = pricing
+    const price = (value: number | null) => value === null || (Number.isFinite(value) && value >= 0 && value <= 1e6)
+    if (
+      !chat ||
+      !tiers.length ||
+      tiers.length > 8 ||
+      tiers[0]?.minInputTokens !== 0 ||
+      tiers.some(
+        (tier, index) =>
+          !Number.isSafeInteger(tier.minInputTokens) ||
+          (index > 0 && tier.minInputTokens <= (tiers[index - 1]?.minInputTokens ?? 0)) ||
+          ![tier.input, tier.output, tier.cacheRead, tier.cacheWrite].every(price),
+      )
+    )
+      add('pricing', 'invalid')
+  }
+  return errors
+}
+
+/** Always a draft target: with endpointId the backend uses the stored keys on an edited, unsaved address. */
+export function probeTarget(e: EndpointDraft, keyId?: string): ProbeTarget {
+  const target: ProbeTarget = { kind: 'draft', baseUrl: e.baseUrl.trim(), protocol: e.protocol }
+  if (e.saved) target.endpointId = e.saved.id
+  if (keyId) target.keyId = keyId
+  return target
+}
+
+const apiBase = (baseUrl: string): string => {
+  const trimmed = baseUrl.trim().replace(/\/+$/, '')
+  return trimmed.endsWith('/v1') ? trimmed : `${trimmed}/v1`
+}
+
+/** Mirrors `aether_providers::api_base` + `/models` for the `→ GET` line before saving. */
+export const probeUrl = (baseUrl: string): string => `${apiBase(baseUrl)}/models`
+
+const CHAT_PATH: Record<Protocol, string> = {
+  'openai-chat': 'chat/completions',
+  'openai-responses': 'responses',
+  'anthropic-messages': 'messages',
+}
+/** Mirrors `aether_chat::protocol` request paths. */
+export const chatUrl = (baseUrl: string, protocol: Protocol): string => `${apiBase(baseUrl)}/${CHAT_PATH[protocol]}`
+
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,100}$/
+const RESERVED_HEADERS: Record<string, true> = {
+  authorization: true,
+  'x-api-key': true,
+  'anthropic-version': true,
+  host: true,
+  'content-type': true,
+  'content-length': true,
+  accept: true,
+  connection: true,
+  'transfer-encoding': true,
+  cookie: true,
+}
+export type HeadersError = { key: 'headers_too_many' | 'headers_invalid' } | { key: 'headers_reserved'; name: string }
+
+/** Front-end mirror of the backend header rules (docs/36 §3.3); blank rows are dropped. */
+export function checkHeaders(
+  rows: readonly { name: string; value: string }[],
+): { headers: Record<string, string> } | { error: HeadersError } {
+  const kept = rows.map((r) => ({ name: r.name.trim(), value: r.value })).filter((r) => r.name || r.value)
+  if (kept.length > 20) return { error: { key: 'headers_too_many' } }
+  const headers: Record<string, string> = {}
+  const seen = new Set<string>()
+  for (const { name, value } of kept) {
+    const lower = name.toLowerCase()
+    if (Object.hasOwn(RESERVED_HEADERS, lower)) return { error: { key: 'headers_reserved', name } }
+    if (!HEADER_NAME.test(name) || seen.has(lower) || value.length > 2048 || /[\r\n]/.test(value))
+      return { error: { key: 'headers_invalid' } }
+    seen.add(lower)
+    headers[name] = value
+  }
+  return { headers }
+}
+
+/** Primary key: the first enabled one, else the first. */
+export const primaryKey = (keys: readonly EndpointKey[]): EndpointKey | null =>
+  keys.find((k) => k.enabled) ?? keys[0] ?? null
+
+export const maskedText = (key: EndpointKey, t: KitI18n['t']): string =>
+  key.readable && key.masked ? key.masked.replace(/\*{4,}/, '****') : t('providers.key_unreadable')
+
+/** Maps key save errors (docs/34 §3.2) to their texts. */
+export function keyError(error: unknown, t: KitI18n['t']): string {
+  if (!isKitClientError(error)) return t('providers.keys_save_failed')
+  const { field, reason } = error.details
+  if (reason === 'duplicate') return t('providers.keys_err_duplicate')
+  if (reason === 'too_many') return t('providers.keys_err_too_many')
+  if (field === 'label' && reason === 'too_long') return t('providers.keys_err_label')
+  if (field === 'apiKey' && reason === 'empty') return t('providers.keys_err_empty')
+  return error.code === 'bad_request' ? t('providers.keys_save_failed') : t(`errors.${error.code}`)
+}

package/src/providers/edit-session.ts

@@ -0,0 +1,146 @@
+import { KitClientError, type CallOptions, type ProbeResult, type Provider, type ProvidersPort } from '../ports'
+import { adopt, probeTarget, savable, toSave, type ProviderDraft } from './draft'
+
+export interface ProviderProbeBatch {
+  results: { keyId: string | null; result: ProbeResult }[]
+  usable: ProbeResult | null
+}
+export interface ProviderEditSession {
+  commit(): Promise<void>
+  probe(endpointSlug: string, options?: CallOptions): Promise<ProviderProbeBatch>
+  invalidate(): void
+}
+
+const cancelled = () =>
+  new KitClientError({ code: 'cancelled', message: 'Provider editing session cancelled', details: {} })
+const identityError = () =>
+  new KitClientError({ code: 'internal', message: 'Saved provider identity is missing or ambiguous', details: {} })
+// Copy plain DTO data without losing invalid numeric edits or retaining Svelte proxies.
+function snapshot<T>(value: T): T {
+  if (Array.isArray(value)) return value.map((item) => snapshot(item)) as T
+  if (value !== null && typeof value === 'object')
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, snapshot(item)])) as T
+  return value
+}
+export function createProviderEditSession(
+  port: ProvidersPort,
+  state: {
+    readDraft(): ProviderDraft
+    writeDraft(next: ProviderDraft): void
+    readProviders(): readonly Provider[]
+    onSaved(next: Provider[]): void
+  },
+): ProviderEditSession {
+  let valid = true
+  let saving = false
+  let dirty = false
+  let waiters: { resolve(): void; reject(error: unknown): void }[] = []
+  let activeProbe: { cancel(): void } | null = null
+
+  function settle(error?: unknown) {
+    const pending = waiters
+    waiters = []
+    for (const waiter of pending) {
+      if (error !== undefined) waiter.reject(error)
+      else waiter.resolve()
+    }
+  }
+  async function drain() {
+    try {
+      while (valid && dirty) {
+        dirty = false
+        const sent = snapshot(savable(state.readDraft()))
+        const before = new Set(state.readProviders().map((provider) => provider.id))
+        const next = await port.save(toSave(sent))
+        if (!valid) return
+        const matches = next.filter((provider) =>
+          sent.id === null ? !before.has(provider.id) : provider.id === sent.id,
+        )
+        const stored = matches[0]
+        if (matches.length !== 1 || !stored) throw identityError()
+        for (const endpoint of sent.endpoints) {
+          const records = stored.endpoints.filter((record) =>
+            endpoint.saved ? record.id === endpoint.saved.id : record.slug === endpoint.slug,
+          )
+          if (records.length !== 1) throw identityError()
+        }
+        state.writeDraft(adopt(state.readDraft(), sent, stored))
+        if (!valid) return
+        state.onSaved(next)
+      }
+      if (valid) settle()
+    } catch (error) {
+      if (valid) {
+        dirty = true
+        settle(error)
+      }
+    } finally {
+      saving = false
+    }
+  }
+  function commit(): Promise<void> {
+    if (!valid) return Promise.reject(cancelled())
+    dirty = true
+    const pending = Promise.withResolvers<void>()
+    waiters.push(pending)
+    if (!saving) {
+      saving = true
+      void drain()
+    }
+    return pending.promise
+  }
+  function probe(slug: string, options?: CallOptions): Promise<ProviderProbeBatch> {
+    activeProbe?.cancel()
+    if (!valid || options?.signal?.aborted) return Promise.reject(cancelled())
+    const controller = new AbortController()
+    let stopped = false
+    const cancellation = Promise.withResolvers<never>()
+    const request = {
+      cancel() {
+        if (stopped) return
+        stopped = true
+        controller.abort()
+        cancellation.reject(cancelled())
+      },
+    }
+    activeProbe = request
+    const ensureCurrent = () => {
+      if (!valid || stopped || options?.signal?.aborted) throw cancelled()
+    }
+    options?.signal?.addEventListener('abort', request.cancel, { once: true })
+    const run = async (): Promise<ProviderProbeBatch> => {
+      await commit()
+      ensureCurrent()
+      const endpoint = snapshot(state.readDraft().endpoints.find((item) => item.slug === slug) ?? null)
+      if (!endpoint)
+        throw new KitClientError({ code: 'not_found', message: 'Provider endpoint no longer exists', details: {} })
+      const enabled = endpoint.saved?.keys.filter((key) => key.enabled) ?? []
+      const keyIds = enabled.length >= 2 ? enabled.map((key) => key.id) : [null]
+      const batch: ProviderProbeBatch = { results: [], usable: null }
+      for (const keyId of keyIds) {
+        ensureCurrent()
+        const result = await port.probe(probeTarget(endpoint, keyId ?? undefined), { signal: controller.signal })
+        ensureCurrent()
+        batch.results.push({ keyId, result })
+        if (result.error === null) batch.usable ??= result
+      }
+      return batch
+    }
+    return Promise.race([run(), cancellation.promise]).finally(() => {
+      options?.signal?.removeEventListener('abort', request.cancel)
+      if (activeProbe === request) activeProbe = null
+    })
+  }
+  return {
+    commit,
+    probe,
+    invalidate() {
+      if (!valid) return
+      valid = false
+      dirty = false
+      activeProbe?.cancel()
+      activeProbe = null
+      settle(cancelled())
+    },
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,5 @@
+// ProvidersSettings and ModelSelect (docs/16 §4.1).
+export { default as ModelSelect } from './ModelSelect.svelte'
+export { default as ProvidersSettings } from './ProvidersSettings.svelte'
+export { providersRevision } from './revision.svelte'
+export { REASONING_EFFORTS } from './reasoning'

package/src/providers/reasoning.ts

@@ -0,0 +1,41 @@
+import type { Protocol, ReasoningEffort, ReasoningDialect, ReasoningConfig } from '../ports'
+
+export const REASONING_EFFORTS: ReasoningEffort[] = ['none', 'auto', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+export const REASONING_DIALECTS: ReasoningDialect[] = [
+  'openai',
+  'anthropic-budget',
+  'anthropic-adaptive',
+  'thinking-type',
+  'qwen',
+]
+
+/** Whether `dialect` is written on `protocol` (same rule as the backends). */
+export function dialectFits(dialect: ReasoningDialect, protocol: Protocol): boolean {
+  if (dialect === 'anthropic-budget' || dialect === 'anthropic-adaptive') return protocol === 'anthropic-messages'
+  if (dialect === 'openai') return protocol !== 'anthropic-messages'
+  return protocol === 'openai-chat'
+}
+
+/** `auto` (on, depth left to the provider) exists only for switch-style dialects. */
+export const allowsAuto = (dialect: ReasoningDialect): boolean => dialect === 'thinking-type' || dialect === 'qwen'
+
+export function emptyReasoning(dialect: ReasoningDialect = 'openai'): ReasoningConfig {
+  return {
+    dialect,
+    efforts: allowsAuto(dialect) ? ['none', 'auto'] : ['low', 'medium', 'high'],
+    ...(dialect === 'anthropic-budget' ? { budgetTokens: 1024 } : {}),
+  }
+}
+
+/** The saved choice if allowed, else the nearest allowed effort (ties go higher); `default` without one. */
+export function nearestEffort(chosen: ReasoningEffort, allowed: readonly ReasoningEffort[]): ReasoningEffort {
+  if (chosen === 'default' || allowed.includes(chosen)) return allowed.length ? chosen : 'default'
+  const at = REASONING_EFFORTS.indexOf(chosen)
+  let best: ReasoningEffort = 'default'
+  let bestDistance = Infinity
+  for (const effort of allowed) {
+    const distance = Math.abs(REASONING_EFFORTS.indexOf(effort) - at)
+    if (distance <= bestDistance) [best, bestDistance] = [effort, distance]
+  }
+  return best
+}

package/src/providers/revision.svelte.ts

@@ -0,0 +1,4 @@
+// Bumped after a provider save/remove so open pickers and chat panels reload model capabilities.
+export const providersRevision = $state({ value: 0 })
+/** Model the next `ProvidersSettings` mount opens; set by a chat "open settings" action, cleared once used. */
+export const settingsTarget = $state<{ value: { endpointId: string; modelId: string } | null }>({ value: null })