dsh-audiogen 0.1.0

package/src/audio-engine.ts

@@ -0,0 +1,377 @@
+/**
+ * Upstream audio proxy engine.
+ *
+ * Normalizes a provider response into base64 audio payloads so the browser
+ * never needs to talk to the upstream directly. Supports a small set of
+ * built-in vendor presets plus a best-effort OpenAI-compatible / generic path.
+ */
+
+import type { AudioMode, GenerateAudioRequest, GeneratedAudio } from './protocol.ts'
+
+/** Resolved channel (key included; never logged). */
+export interface AudioChannel {
+  id: string
+  preset: string
+  name: string
+  apiUrl: string
+  apiKey: string
+  models: Array<{ alias: string; id: string }>
+}
+
+/** An audio generation failure with a user-presentable message. */
+export class AudioGenError extends Error {
+  readonly code: string
+
+  constructor(message: string, code = 'audio-generate-failed') {
+    super(message)
+    this.name = 'AudioGenError'
+    this.code = code
+  }
+}
+
+/** Total budget for one upstream generation call. Audio models can be slow. */
+const UPSTREAM_TIMEOUT_MS = 240_000
+/** Budget for downloading one result audio URL. */
+const AUDIO_FETCH_TIMEOUT_MS = 60_000
+
+function requestSignal(source: AbortSignal | undefined, timeoutMs: number): { signal: AbortSignal; dispose: () => void } {
+  const controller = new AbortController()
+  const abortFromSource = () => { controller.abort(source?.reason) }
+  if (source?.aborted === true) abortFromSource()
+  else source?.addEventListener('abort', abortFromSource, { once: true })
+  const timeout = setTimeout(() => { controller.abort(new DOMException('The operation timed out.', 'TimeoutError')) }, timeoutMs)
+  timeout.unref?.()
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      clearTimeout(timeout)
+      source?.removeEventListener('abort', abortFromSource)
+    },
+  }
+}
+
+/** Detect a few common audio container formats from magic bytes. */
+export function detectAudioMime(data: Uint8Array): string | undefined {
+  if (data.length >= 4 && data[0] === 0x52 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x46) return 'audio/wav'
+  if (data.length >= 3 && data[0] === 0x49 && data[1] === 0x44 && data[2] === 0x33) return 'audio/mpeg'
+  if (data.length >= 4 && data[0] === 0x66 && data[1] === 0x4c && data[2] === 0x61 && data[3] === 0x43) return 'audio/flac'
+  if (data.length >= 4 && data[0] === 0x4f && data[1] === 0x67 && data[2] === 0x67 && data[3] === 0x53) return 'audio/ogg'
+  if (data.length >= 4 && data[0] === 0x00 && data[1] === 0x00 && data[2] === 0x00 && data[3] === 0x18) return 'audio/mp4'
+  if (data.length >= 4 && data[0] === 0x23 && data[1] === 0x21 && data[2] === 0x41 && data[3] === 0x4d) return 'audio/aiff'
+  return undefined
+}
+
+function mimeFromContentType(value: string | null): string | undefined {
+  if (value === null || value === '') return undefined
+  return value.split(';')[0]!.trim().toLowerCase()
+}
+
+function audioMime(data: Uint8Array, contentType: string | null): string {
+  return detectAudioMime(data) ?? mimeFromContentType(contentType) ?? 'audio/mpeg'
+}
+
+function isPreset(channel: AudioChannel, id: string): boolean {
+  return channel.preset === id || channel.apiUrl.toLowerCase().includes(id)
+}
+
+function isOpenAICompatible(channel: AudioChannel, mode: AudioMode): boolean {
+  return isPreset(channel, 'openai')
+    || /(^|\/)(v\d+\/)?audio\/speech$/i.test(channel.apiUrl.trim())
+    || (channel.preset === 'custom' && mode === 'tts')
+}
+
+function isElevenLabs(channel: AudioChannel): boolean {
+  return isPreset(channel, 'elevenlabs') || /elevenlabs/i.test(channel.apiUrl)
+}
+
+function isMiniMax(channel: AudioChannel): boolean {
+  return isPreset(channel, 'minimax') || /minimax/i.test(channel.apiUrl)
+}
+
+function isStability(channel: AudioChannel): boolean {
+  return isPreset(channel, 'stability') || /stability\.ai/i.test(channel.apiUrl)
+}
+
+function endpointBase(url: string): string {
+  return url.trim().replace(/\/+$/, '')
+}
+
+function bytesToBase64(data: Uint8Array): string {
+  return Buffer.from(data).toString('base64')
+}
+
+/** Parse a base64 payload that may carry a data: prefix. */
+function bareBase64(value: string): string {
+  const match = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(value.trim())
+  if (match !== null && match[3] !== undefined) return match[3]
+  return value
+}
+
+function asBase64(value: unknown): string | undefined {
+  if (typeof value === 'string' && value.trim() !== '') return bareBase64(value)
+  return undefined
+}
+
+/** Recursively look for the first likely base64 audio string in a JSON payload. */
+function findBase64Audio(value: unknown): string | undefined {
+  if (typeof value === 'string' && value.length > 100 && !/^https?:\/\//i.test(value.trim())) return value
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = findBase64Audio(item)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+  if (value === null || typeof value !== 'object') return undefined
+  const record = value as Record<string, unknown>
+  for (const key of ['audio', 'b64_json', 'base64', 'data', 'output', 'result', 'value']) {
+    const candidate = record[key]
+    const found = findBase64Audio(candidate)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
+/** Find the first provider-returned audio URL in a JSON payload. */
+function findAudioUrl(value: unknown): string | undefined {
+  if (typeof value === 'string' && /^https?:\/\//i.test(value)) return value
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = findAudioUrl(item)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+  if (value === null || typeof value !== 'object') return undefined
+  const record = value as Record<string, unknown>
+  for (const key of ['url', 'audio_url', 'href', 'link', 'audio', 'data', 'output', 'result', 'value']) {
+    const candidate = record[key]
+    const found = findAudioUrl(candidate)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
+async function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response> {
+  const budget = requestSignal(init.signal as AbortSignal | undefined, timeoutMs)
+  try {
+    return await fetch(url, { ...init, signal: budget.signal })
+  } finally {
+    budget.dispose()
+  }
+}
+
+async function normalizeAudioResponse(
+  response: Response,
+  options: { apiKey: string; fallbackMime?: string },
+): Promise<Array<{ data: Uint8Array; mime: string }>> {
+  if (!response.ok) {
+    let detail = ''
+    try {
+      const text = await response.text()
+      detail = text.slice(0, 500)
+    } catch {
+      // keep empty
+    }
+    throw new AudioGenError(`audio API error (HTTP ${response.status})${detail === '' ? '' : `: ${detail}`}`, 'audio-api-error')
+  }
+
+  const contentType = mimeFromContentType(response.headers.get('content-type')) ?? options.fallbackMime
+  const buffer = new Uint8Array(await response.arrayBuffer())
+  // Some providers return binary audio directly, others JSON with base64/url.
+  const text = new TextDecoder().decode(buffer).trim()
+  if (text.startsWith('{') || text.startsWith('[')) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      throw new AudioGenError('audio endpoint returned an unprocessable response body', 'audio-bad-response')
+    }
+    const base64 = findBase64Audio(parsed)
+    if (base64 !== undefined && base64.length > 0) {
+      let data: Uint8Array
+      try {
+        data = new Uint8Array(Buffer.from(base64, 'base64'))
+      } catch {
+        throw new AudioGenError('audio endpoint returned invalid base64', 'audio-bad-response')
+      }
+      return [{ data, mime: detectAudioMime(data) ?? contentType ?? 'audio/mpeg' }]
+    }
+    const url = findAudioUrl(parsed)
+    if (url !== undefined) {
+      const fetched = await fetchWithTimeout(url, {
+        headers: options.apiKey === '' ? {} : { authorization: `Bearer ${options.apiKey}` },
+        redirect: 'follow',
+      }, AUDIO_FETCH_TIMEOUT_MS)
+      if (!fetched.ok) throw new AudioGenError(`failed to fetch generated audio url: HTTP ${fetched.status}`, 'audio-url-fetch-failed')
+      const data = new Uint8Array(await fetched.arrayBuffer())
+      return [{ data, mime: audioMime(data, fetched.headers.get('content-type')) }]
+    }
+    throw new AudioGenError('audio endpoint returned neither binary nor base64/url audio', 'audio-empty-result')
+  }
+  return [{ data: buffer, mime: audioMime(buffer, response.headers.get('content-type') ?? contentType ?? null) }]
+}
+
+async function openAITTS(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+  const base = endpointBase(channel.apiUrl)
+  const endpoint = /\/audio\/speech(\?|$)/i.test(base) ? base : `${base}/audio/speech`
+  const model = (request.upstream ?? request.model) || 'tts-1'
+  const voice = request.voice ?? 'alloy'
+  const body: Record<string, unknown> = {
+    model,
+    input: request.prompt,
+    voice,
+    response_format: request.format ?? 'mp3',
+    ...(request.speed !== undefined ? { speed: request.speed } : {}),
+  }
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    headers: {
+      authorization: `Bearer ${channel.apiKey.trim()}`,
+      'content-type': 'application/json',
+      accept: 'audio/mpeg, application/json',
+    },
+    body: JSON.stringify(body),
+    signal,
+  }, UPSTREAM_TIMEOUT_MS)
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
+async function elevenLabs(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+  const base = endpointBase(channel.apiUrl)
+  const model = (request.upstream ?? request.model) || 'eleven_multilingual_v2'
+  const voiceId = (request.voice ?? request.model ?? model).trim()
+  const endpoint = `${base}/text-to-speech/${encodeURIComponent(voiceId)}`
+  const body: Record<string, unknown> = {
+    text: request.prompt,
+    model_id: model,
+    voice_settings: {
+      stability: 0.5,
+      similarity_boost: 0.75,
+      style: 0.0,
+      use_speaker_boost: true,
+      ...(request.speed !== undefined ? { speed: request.speed } : {}),
+    },
+  }
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    headers: {
+      'xi-api-key': channel.apiKey.trim(),
+      'content-type': 'application/json',
+      accept: 'audio/mpeg, application/json',
+    },
+    body: JSON.stringify(body),
+    signal,
+  }, UPSTREAM_TIMEOUT_MS)
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
+async function minimax(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+  const base = endpointBase(channel.apiUrl)
+  const endpoint = /\/t2a_v2(\?|$)/i.test(base) ? base : `${base}/t2a_v2`
+  const model = (request.upstream ?? request.model) || 'speech-01-turbo'
+  const voice = request.voice ?? request.model ?? ''
+  const body: Record<string, unknown> = {
+    model,
+    text: request.prompt,
+    stream: false,
+    ...(voice === '' ? {} : { voice_setting: {
+      voice_id: voice,
+      ...(request.speed !== undefined ? { speed: request.speed } : {}),
+      vol: 1,
+      pitch: 0,
+    } }),
+    audio_setting: {
+      format: request.format ?? 'mp3',
+      sample_rate: 32000,
+      bitrate: 128000,
+    },
+  }
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    headers: {
+      authorization: `Bearer ${channel.apiKey.trim()}`,
+      'content-type': 'application/json',
+      accept: 'application/json, audio/mpeg',
+    },
+    body: JSON.stringify(body),
+    signal,
+  }, UPSTREAM_TIMEOUT_MS)
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
+async function stabilityAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+  const base = endpointBase(channel.apiUrl)
+  const endpoint = /\/generation(\?|$)/i.test(base) ? base : `${base}/generation`
+  const model = (request.upstream ?? request.model) || 'stable-audio-2.0'
+  const body: Record<string, unknown> = {
+    model,
+    prompt: request.prompt,
+    ...(request.duration !== undefined ? { duration: request.duration } : {}),
+    ...(request.format !== undefined ? { output_format: request.format } : {}),
+  }
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    headers: {
+      authorization: `Bearer ${channel.apiKey.trim()}`,
+      'content-type': 'application/json',
+      accept: 'application/json, audio/mpeg, audio/wav',
+    },
+    body: JSON.stringify(body),
+    signal,
+  }, UPSTREAM_TIMEOUT_MS)
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
+async function genericAudio(channel: AudioChannel, request: GenerateAudioRequest, signal?: AbortSignal): Promise<Array<{ data: Uint8Array; mime: string }>> {
+  const base = endpointBase(channel.apiUrl)
+  if (request.mode === 'tts' && !/\/generate(\?|$)/i.test(base)) {
+    return openAITTS(channel, request, signal)
+  }
+  const endpoint = /\/generate(\?|$)/i.test(base) ? base : `${base}/generate`
+  const model = (request.upstream ?? request.model) || 'default'
+  const body: Record<string, unknown> = {
+    model,
+    prompt: request.prompt,
+    mode: request.mode,
+    ...(request.voice !== undefined ? { voice: request.voice } : {}),
+    ...(request.duration !== undefined ? { duration: request.duration } : {}),
+    ...(request.format !== undefined ? { output_format: request.format } : {}),
+  }
+  const response = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    redirect: 'error',
+    headers: {
+      authorization: `Bearer ${channel.apiKey.trim()}`,
+      'content-type': 'application/json',
+      accept: 'application/json, audio/mpeg, audio/wav',
+    },
+    body: JSON.stringify(body),
+    signal,
+  }, UPSTREAM_TIMEOUT_MS)
+  return normalizeAudioResponse(response, { apiKey: channel.apiKey, fallbackMime: 'audio/mpeg' })
+}
+
+/**
+ * Generate one or more audio outputs from a configured channel.
+ * @returns normalized generated audio (base64, mime, bytes).
+ */
+export async function generateAudio(
+  channel: AudioChannel,
+  request: GenerateAudioRequest,
+  signal?: AbortSignal,
+): Promise<Array<{ data: Uint8Array; mime: string }>> {
+  if (channel.apiUrl.trim() === '') throw new AudioGenError('channel API URL is not configured', 'audio-no-endpoint')
+  if (channel.apiKey.trim() === '') throw new AudioGenError('channel API key is not configured', 'audio-no-key')
+  if (request.prompt.trim() === '') throw new AudioGenError('audio prompt/text is required', 'audio-empty-prompt')
+
+  if (isElevenLabs(channel)) return elevenLabs(channel, request, signal)
+  if (isMiniMax(channel)) return minimax(channel, request, signal)
+  if (isStability(channel)) return stabilityAudio(channel, request, signal)
+  if (isOpenAICompatible(channel, request.mode)) return openAITTS(channel, request, signal)
+  return genericAudio(channel, request, signal)
+}

package/src/audio-presets.ts

@@ -0,0 +1,80 @@
+/**
+ * Built-in audio provider catalog (presets).
+ * Framework-free pure data; served to the settings card through a host route.
+ */
+
+import type { ModelMapping } from './protocol.ts'
+
+/** One built-in provider the settings card can instantiate a channel from. */
+export interface AudioPresetProvider {
+  /** Stable preset id stored on channels created from it ('' = custom). */
+  id: string
+  /** Display name shown in the picker (also the channel's default name). */
+  name: string
+  /** Official base URL prefilled into the channel. */
+  apiUrl: string
+  /** One-line description shown in the picker. */
+  hint: string
+  /** Known model/voice catalog prefilled into the channel. */
+  models: ModelMapping[]
+}
+
+export const AUDIO_PRESETS: AudioPresetProvider[] = [
+  {
+    id: 'openai-tts',
+    name: 'OpenAI · TTS',
+    apiUrl: 'https://api.openai.com/v1',
+    hint: 'OpenAI 官方语音合成接口（/audio/speech）',
+    models: [
+      { alias: 'tts-1', id: 'tts-1' },
+      { alias: 'tts-1-hd', id: 'tts-1-hd' },
+      { alias: 'gpt-4o-mini-tts', id: 'gpt-4o-mini-tts' },
+    ],
+  },
+  {
+    id: 'elevenlabs',
+    name: 'ElevenLabs',
+    apiUrl: 'https://api.elevenlabs.io/v1',
+    hint: 'ElevenLabs TTS；模型列表请填写你的 Voice ID（如 Rachel / Adam 等别名）',
+    models: [
+      { alias: 'Rachel', id: '21m00Tcm4TlvDq8ikWAM' },
+      { alias: 'Adam', id: 'pNInz6obpgDQGcFmaJgB' },
+      { alias: 'Antoni', id: 'ErXwobaYiN019PkySvjV' },
+      { alias: 'Bella', id: 'EXAVITQu4vr4xnSDxMaL' },
+    ],
+  },
+  {
+    id: 'minimax',
+    name: 'MiniMax',
+    apiUrl: 'https://api.minimax.chat/v1',
+    hint: 'MiniMax 语音合成（T2A）；需在 API URL 后按官方要求携带 GroupId 或使用完整接口地址',
+    models: [
+      { alias: 'speech-01-turbo', id: 'speech-01-turbo' },
+      { alias: 'speech-01-hd', id: 'speech-01-hd' },
+      { alias: 'speech-02-turbo', id: 'speech-02-turbo' },
+      { alias: 'speech-02-hd', id: 'speech-02-hd' },
+    ],
+  },
+  {
+    id: 'stability-audio',
+    name: 'Stability AI · 音频',
+    apiUrl: 'https://api.stability.ai/v2beta/audio',
+    hint: 'Stability AI 音乐/音效生成（stable-audio 系列）',
+    models: [
+      { alias: 'stable-audio-2.0', id: 'stable-audio-2.0' },
+      { alias: 'stable-audio-1.0', id: 'stable-audio-1.0' },
+    ],
+  },
+  {
+    id: 'custom',
+    name: '自定义渠道',
+    apiUrl: '',
+    hint: '任意兼容接口；支持 OpenAI 兼容 TTS，或返回音频字节 / JSON 的通用 POST',
+    models: [],
+  },
+]
+
+/** Look up one built-in provider by id. */
+export function audioPresetById(id: string): AudioPresetProvider | undefined {
+  return AUDIO_PRESETS.find(preset => preset.id === id)
+}

package/src/audio-store.ts

@@ -0,0 +1,131 @@
+/**
+ * Host-side persistence for generated audio and generation history.
+ * Files live under ~/.dsh/dsh-audiogen/audio/; history is one JSON document.
+ */
+
+import { mkdir, readFile, writeFile, readdir, unlink } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import path from 'node:path'
+import os from 'node:os'
+import type { HistoryEntry, HistoryEntryInput } from './protocol.ts'
+import { HISTORY_MAX } from './protocol.ts'
+
+function dshHome(): string {
+  return process.env.DSH_HOME ?? path.join(os.homedir(), '.dsh')
+}
+
+export const AUDIO_DATA_DIR = path.join(dshHome(), 'dsh-audiogen', 'audio')
+const HISTORY_FILE = path.join(dshHome(), 'dsh-audiogen', 'history.json')
+
+async function ensureDir(): Promise<void> {
+  await mkdir(AUDIO_DATA_DIR, { recursive: true })
+}
+
+function safeName(id: string): string {
+  return id.replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+/** Persist one generated audio file. Returns its metadata and public id. */
+export async function saveAudioFile(data: Uint8Array, mime: string, name?: string): Promise<{
+  id: string
+  file: string
+  mime: string
+  bytes: number
+  name?: string
+}> {
+  await ensureDir()
+  const id = randomUUID()
+  const extension = mime.split('/')[1]?.replace('mpeg', 'mp3') ?? 'bin'
+  const file = `${id}.${extension}`
+  await writeFile(path.join(AUDIO_DATA_DIR, file), data)
+  return {
+    id,
+    file,
+    mime,
+    bytes: data.byteLength,
+    ...(name === undefined ? {} : { name }),
+  }
+}
+
+/** Read a persisted audio file by its id/file name. */
+export async function readAudioFile(file: string): Promise<{ data: Buffer; mime: string; bytes: number } | undefined> {
+  const safe = safeName(file)
+  const full = path.join(AUDIO_DATA_DIR, safe)
+  if (!full.startsWith(AUDIO_DATA_DIR)) return undefined
+  try {
+    const data = await readFile(full)
+    return { data, mime: mimeFromFile(safe), bytes: data.byteLength }
+  } catch {
+    return undefined
+  }
+}
+
+function mimeFromFile(file: string): string {
+  const ext = path.extname(file).toLowerCase()
+  switch (ext) {
+    case '.wav': return 'audio/wav'
+    case '.mp3': return 'audio/mpeg'
+    case '.flac': return 'audio/flac'
+    case '.ogg': return 'audio/ogg'
+    case '.m4a': return 'audio/mp4'
+    case '.aac': return 'audio/aac'
+    case '.aiff': return 'audio/aiff'
+    default: return 'application/octet-stream'
+  }
+}
+
+async function readHistory(): Promise<HistoryEntry[]> {
+  try {
+    const text = await readFile(HISTORY_FILE, 'utf8')
+    const parsed = JSON.parse(text) as unknown
+    return Array.isArray(parsed) ? parsed as HistoryEntry[] : []
+  } catch {
+    return []
+  }
+}
+
+async function writeHistory(entries: HistoryEntry[]): Promise<void> {
+  await mkdir(path.dirname(HISTORY_FILE), { recursive: true })
+  await writeFile(HISTORY_FILE, JSON.stringify(entries, null, 2))
+}
+
+/** Append one history entry and enforce the cap. */
+export async function appendHistory(entry: HistoryEntryInput): Promise<HistoryEntry[]> {
+  const list = await readHistory()
+  const next: HistoryEntry[] = [{
+    id: entry.id,
+    createdAt: entry.createdAt,
+    mode: entry.mode,
+    model: entry.model,
+    prompt: entry.prompt,
+    ...(entry.voice === undefined ? {} : { voice: entry.voice }),
+    ...(entry.speed === undefined ? {} : { speed: entry.speed }),
+    ...(entry.duration === undefined ? {} : { duration: entry.duration }),
+    ...(entry.format === undefined ? {} : { format: entry.format }),
+    audio: entry.audio.map(audio => ({
+      url: audio.url,
+      mime: audio.mime,
+      ...(audio.duration === undefined ? {} : { duration: audio.duration }),
+    })),
+    ...(entry.channelId === undefined ? {} : { channelId: entry.channelId }),
+    ...(entry.channel === undefined ? {} : { channel: entry.channel }),
+  }, ...list].slice(0, HISTORY_MAX)
+  await writeHistory(next)
+  return next
+}
+
+export async function listHistory(): Promise<HistoryEntry[]> {
+  return readHistory()
+}
+
+export async function removeHistory(id: string): Promise<HistoryEntry[]> {
+  const list = await readHistory()
+  const next = list.filter(entry => entry.id !== id)
+  await writeHistory(next)
+  return next
+}
+
+export async function clearHistory(): Promise<HistoryEntry[]> {
+  await writeHistory([])
+  return []
+}