Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

129 KB
Raw Blame
import type { ModelDefinition } from "../models/ModelRegistry";
import type { ReasoningConfig } from "../services/BaseReasoningService";
import type { PermissionGuideState, PermissionGuideAction } from "./permissionGuide";
import type { TinfoilCatalogModel } from "../models/tinfoilModels";
import type { UsageResponse } from "../lib/usageStore";
import type { DictationTone, ToneAppCategory } from "../config/toneStyle";
import type { OrgPolicy } from "./policy";
import type { TechnicalErrorDetailsData } from "../components/ui/useToast";
import type { ProviderSettingsTarget } from "../utils/describeProviderError";
import type { RemovedTranscriptSegment } from "../utils/diarizationCompletion";
import type {
  ManagedEnterpriseConfig,
  ManagedEnterpriseRequestContext,
} from "./enterpriseIdentity";
import type {
  CalendarAvailabilityRequest,
  CalendarAvailabilityResult,
  CalendarEvent,
  LinkableCalendarEvent,
  MicrosoftCalendarAccount,
} from "./calendar";
import type {
  ConnectorActionRecord,
  ConnectorCancelConnectResult,
  ConnectorCancelReason,
  ConnectorCommitResult,
  ConnectorConnectProgress,
  ConnectorConnectResult,
  ConnectorDirectResult,
  ConnectorDisconnectResult,
  ConnectorEdits,
  ConnectorPrepareResult,
  ConnectorQueryResult,
  ConnectorStatus,
  ContactMatch,
  NoteAttendee,
  NoteAttendeesRequest,
} from "./connectors";

export type LocalTranscriptionProvider = "whisper" | "nvidia" | "cohere";

export interface MainWindowInputRegion {
  viewportWidth: number;
  viewportHeight: number;
  x: number;
  y: number;
  width: number;
  height: number;
}

export type ChineseScriptPreference = "simplified" | "traditional" | "as-transcribed";

export type InferenceMode = "openwhispr" | "providers" | "local" | "self-hosted" | "enterprise";

/** Each LLM scope's resolved mode and model, from which the main process decides the shared llama-server. */
export interface LocalServerPrefs {
  useCleanupModel: boolean;
  cleanupMode: InferenceMode;
  cleanupModel: string;
  useDictationAgent: boolean;
  dictationAgentMode: InferenceMode;
  dictationAgentModel: string;
  noteFormattingMode: InferenceMode;
  noteFormattingModel: string;
  chatAgentMode: InferenceMode;
  chatAgentModel: string;
  useDictationTranslation: boolean;
  translationMode: InferenceMode;
  translationModel: string;
}

export type SelfHostedType = "openai-compatible" | "lan";

export type TranscriptionStatus = "completed" | "failed" | "pending" | "discarded";

export interface PolicyFailureMetadata {
  error?: string;
  code?: string;
  status?: number;
  minAppVersion?: string;
  details?: unknown;
}

export interface NoteRecordingProviderModel {
  id: string;
  name: string;
  default?: boolean;
}

export interface NoteRecordingProvider {
  id: string;
  name: string;
  models: NoteRecordingProviderModel[];
}

// Session options every dictation streaming channel takes — the shared
// dictation-realtime-* set and the per-provider ones. `provider` is
// what fetchRealtimeToken's allowlist keys on — the renderer must always send
// it (built by dictationStreamingRouting.buildStreamingSessionOptions); the
// main process defaults a missing value to "openai-realtime" for pre-1.8.4
// renderers (#1624).
export interface DictationRealtimeSessionOptions {
  pipelineOptions?: {
    agentName?: string;
    customDictionary?: string[];
    customPrompt?: string;
    tone?: DictationTone;
    appCategory?: ToneAppCategory;
    language?: string;
    locale?: string;
  };
  provider: string;
  baseUrl?: string;
  model?: string;
  mode?: "byok" | "openwhispr";
  language?: string;
  sampleRate?: number;
  keyterms?: string[];
  environment?: string;
  tenant?: string;
  preview?: boolean;
}

export interface DictationLanguageMetadata {
  language: string | null;
  languageConfidence: number | null;
  // Sum of detector scores for Orukeet's 25 languages, not a calibrated probability.
  languageSupportedScore?: number;
  languageAudioSeconds?: number;
}

export type NoteRecordingConfigFailure = { success: false } & PolicyFailureMetadata;

export type NoteRecordingConfigResult =
  { success: true; providers: NoteRecordingProvider[] } | NoteRecordingConfigFailure;

export type TranscriptionErrorCode =
  | "TIMEOUT"
  | "NETWORK"
  | "SERVER_ERROR"
  | "OFFLINE"
  | "AUTH_EXPIRED"
  | "AUTH_REQUIRED"
  | "LIMIT_REACHED"
  | "PROVIDER_RATE_LIMITED"
  | "API_KEY_MISSING"
  | "INVALID_KEY"
  | "MODEL_NOT_AVAILABLE"
  | "CUSTOM_ENDPOINT_INVALID"
  | "PROVIDER_AUTH_FAILED"
  | "PROVIDER_ACCESS_DENIED"
  | "PROVIDER_QUOTA_EXHAUSTED"
  | "PROVIDER_MODEL_NOT_FOUND"
  | "PROVIDER_PAYLOAD_TOO_LARGE"
  | "PROVIDER_BAD_REQUEST"
  | "PROVIDER_UNAVAILABLE"
  | "PROVIDER_TIMEOUT"
  | "PROVIDER_UNREACHABLE"
  | "PROVIDER_NO_RESPONSE"
  | "PROVIDER_ERROR"
  | "CRASH_RECOVERY"
  | null;

export type MeetingPromptVariant = "detected" | "starting" | "underway";

export interface MeetingNotificationData {
  detectionId: string;
  source: string;
  key: string;
  event: { summary?: string | null } | null;
  variant: MeetingPromptVariant;
  joinUrl: string | null;
}

export interface MeetingFolderRef {
  folderId: number;
  spaceId: number;
}
export interface MeetingExistingNote {
  noteId: number;
  spaceId: number;
  folderId: number | null;
  spaceName: string;
  folderName: string | null;
  shared: boolean;
}
export interface MeetingDestinationContext {
  folders: FolderItem[];
  spaces: SpaceItem[];
  defaultDestination: MeetingFolderRef | null;
  selectedDestination: MeetingFolderRef | null;
  recentDestinations: MeetingFolderRef[];
  existingNote: MeetingExistingNote | null;
}

export interface MeetingSurfaceState {
  revision: number;
  mode: "closed" | "list" | "form";
  contentHeight: number;
  regions: { x: number; y: number; width: number; height: number }[];
  focus: "request" | "release" | "keep";
}

export type MeetingError =
  | "STALE_NOTIFICATION"
  | "INVALID_REQUEST"
  | "FOLDERS_UNAVAILABLE"
  | "FOLDER_UNAVAILABLE"
  | "SPACE_UNAVAILABLE"
  | "FOLDER_NAME_REQUIRED"
  | "FOLDER_NAME_TAKEN"
  | "CREATE_FAILED"
  | "LINKED_NOTE_CHANGED"
  | "NOTE_UNAVAILABLE"
  | "START_FAILED";

export type MeetingResult<T> =
  | { success: true; value: T }
  | { success: false; code: MeetingError; context?: MeetingDestinationContext };

/** Why auto-end concluded the meeting is over. */
export type MeetingAutoEndReason = "mic-released" | "silence" | "process-exit";

export interface MeetingAutoEndRequest {
  sessionId: string;
  reason?: MeetingAutoEndReason;
}

/** Fields a main-process handler resolves with in place of a rejected Error. */
export interface IpcErrorFields {
  error: string;
  code?: string;
  messageKey?: string;
  messageParams?: Record<string, string | number>;
  settingsTarget?: string;
  technicalDetails?: TechnicalErrorDetailsData;
  status?: number;
  surface?: "transcription" | "llm";
}

/**
 * Proxied-transcription IPC results. `ipcMain.handle` drops custom error props on
 * rejection, so these handlers resolve with a serialized error instead of throwing.
 */
export type ProxyTranscriptionResult =
  { text: string; model?: string; error?: undefined } | (IpcErrorFields & { text?: undefined });

export interface AuthTokenState {
  token: string | null;
  generation: number;
}

export interface AuthTokenMutationResult extends AuthTokenState {
  success: boolean;
  code?: string;
}

/** The validated account scope the main process holds, as seen by any window. */
export interface ActiveAccountScope {
  accountId: string;
  authGeneration: number;
}

export interface TranscriptionItem {
  id: number;
  text: string;
  raw_text: string | null;
  timestamp: string;
  created_at: string;
  has_audio: number;
  audio_duration_ms: number | null;
  provider: string | null;
  model: string | null;
  status: TranscriptionStatus;
  error_message: string | null;
  error_code: TranscriptionErrorCode;
  route_kind?: string | null;
  client_transcription_id: string;
  cloud_id: string | null;
  sync_status: "synced" | "pending" | "error";
  deleted_at: string | null;
}

export type AnalyticsMode = "local" | "openwhispr_cloud" | "byok" | "self_hosted" | "unknown";

export interface AnalyticsEventInput {
  eventId: string;
  wordCount: number;
  occurredAt: string;
  localDate: string;
  spokenDurationMs?: number | null;
  mode: AnalyticsMode;
  provider?: string | null;
  model?: string | null;
}

export interface PendingAnalyticsEvent {
  event_id: string;
  occurred_at: string;
  local_date: string;
  word_count: number;
  spoken_duration_ms: number | null;
  mode: AnalyticsMode;
  provider: string | null;
  model: string | null;
  counter_version: number;
}

export interface PendingAnalyticsClear {
  cleared_through: string;
}

export interface AnalyticsSyncContext {
  accountId: string;
  authGeneration: number;
}

export interface AnalyticsDailyBucket {
  date: string;
  words: number;
  dictations: number;
  spokenDurationMs: number;
}

export interface AnalyticsSummary {
  totalWords: number;
  totalDictations: number;
  totalSpokenDurationMs: number;
  averageWpm: number | null;
  currentStreakDays: number;
  longestStreakDays: number;
  wpmCoveragePercent: number;
  daily: AnalyticsDailyBucket[];
  historyBackfillRetryRequired?: boolean;
}

export type LeaderboardMetric =
  "total_words" | "words_per_minute" | "current_daily_streak" | "desktop_words" | "mobile_words";

export type LeaderboardRange = "week" | "all";

export interface AnalyticsParticipation {
  configured: boolean;
  enabled: boolean;
  updatedAt: string | null;
}

export interface LeaderboardMember {
  userId: string;
  name: string | null;
  // Withheld (null) on a domain board, where a shared mail suffix is the only
  // thing the listed people have in common.
  email: string | null;
  image: string | null;
  totalWords: number;
  desktopWords: number;
  mobileWords: number;
  averageWpm: number | null;
  currentStreakDays: number;
  rank: number;
}

export type LeaderboardAccessState =
  "ready" | "invite" | "accept_invite" | "request_join" | "create";

export interface LeaderboardAccessScope {
  key: string;
  kind: "workspace" | "domain";
  id: string;
  name: string;
  memberCount: number;
  state: "ready" | "invite";
  role: WorkspaceRole | null;
}

export interface LeaderboardAccess {
  state: LeaderboardAccessState;
  scopes: LeaderboardAccessScope[];
  domain: string | null;
  colleagueCount: number;
  invitation: {
    workspaceId: string;
    workspaceName: string;
    inviterName: string | null;
  } | null;
  joinableWorkspace: {
    id: string;
    name: string;
    memberCount: number;
    requestState: "none" | "pending";
  } | null;
}

export interface Leaderboard {
  scope: {
    key: string;
    kind: "workspace" | "domain";
    id: string;
    name: string;
  };
  viewerUserId: string | null;
  metric: LeaderboardMetric;
  range: LeaderboardRange;
  weekStart: string | null;
  availableWeekStarts: string[];
  leaders: LeaderboardMember[];
  members: LeaderboardMember[];
  totalMembers: number;
  viewerRank: number | null;
  page: number;
  pageSize: number;
  generatedAt: string;
  refreshAfterSeconds: number;
}

export interface NoteItem {
  id: number;
  title: string;
  content: string;
  enhanced_content: string | null;
  enhancement_prompt: string | null;
  /** The client_id of the template that produced enhanced_content. */
  enhancement_template_id: string | null;
  enhanced_at_content_hash: string | null;
  note_type: "personal" | "meeting" | "upload";
  source_file: string | null;
  audio_duration_seconds: number | null;
  folder_id: number | null;
  space_id: number;
  transcript: string | null;
  calendar_event_id: string | null;
  participants: string | null;
  diarization_enabled: number | null;
  expected_speaker_count: number | null;
  cloud_id: string | null;
  is_shared: number;
  share_token: string | null;
  // The note's owner (CloudNote.user_id) — who created it, not who last
  // edited it. Only populated from the cloud; NULL on local-only rows and on
  // team notes mirrored before ownership shipped (the UI fails closed on
  // those until the owner backfill fills them).
  owner_user_id?: string | null;
  created_by_user_id?: string | null;
  // Last cloud editor; only populated on cloud pull (local edits don't set it).
  updated_by_user_id?: string | null;
  // Server updated_at this device last acked (push response or pull); echoed
  // as base_updated_at on the next PATCH. Null = pre-guard row, pushes LWW.
  cloud_updated_at?: string | null;
  cloud_revision?: number | null;
  cloud_create_rejected?: number;
  cloud_create_pending?: string | null;
  content_sync_operation?: "set" | "clear" | null;
  enhanced_content_sync_operation?: "set" | "clear" | null;
  // Local-only counters distinguish later edits/Undo from an in-flight snapshot.
  content_edit_generation?: number;
  enhanced_content_edit_generation?: number;
  created_at: string;
  updated_at: string;
  client_note_id: string;
  sync_status: "synced" | "pending" | "error";
  deleted_at: string | null;
  // Computed by getNoteByClientId while a parent folder DELETE awaits its
  // server result. Held notes stay hidden and must not be pulled/queued alone.
  folder_delete_pending?: number;
  // 1 while a cloud-backed row that left a team space still owes its scope
  // retraction push (D6); cleared when the row settles.
  left_team?: number;
}

// Immutable view of every local field that affects a note push. The main
// process compares this atomically when the cloud response returns, so an
// in-flight create/PATCH cannot settle a newer edit or a purged identity.
export type NotePushSnapshot = Pick<
  NoteItem,
  | "client_note_id"
  | "title"
  | "content"
  | "enhanced_content"
  | "enhancement_prompt"
  | "enhancement_template_id"
  | "enhanced_at_content_hash"
  | "note_type"
  | "source_file"
  | "audio_duration_seconds"
  | "folder_id"
  | "space_id"
  | "transcript"
  | "calendar_event_id"
  | "participants"
  | "diarization_enabled"
  | "expected_speaker_count"
  | "created_at"
  | "updated_at"
  | "sync_status"
  | "deleted_at"
  | "cloud_updated_at"
  | "cloud_revision"
  | "content_sync_operation"
  | "enhanced_content_sync_operation"
  | "content_edit_generation"
  | "enhanced_content_edit_generation"
  | "left_team"
>;

export type NoteCreateSnapshot = NotePushSnapshot;
export type NoteUpdateSnapshot = NotePushSnapshot;

export interface NoteCreateAckResult {
  success: boolean;
  outcome:
    | "synced"
    | "pending"
    | "already-linked"
    | "orphaned"
    | "unresolved"
    | "awaiting-cloud"
    | "conflict";
  note?: NoteItem;
}

export interface NoteCreateAckWriteOptions {
  settleIfUnchanged?: boolean;
  cloudRevision?: number | null;
  // The server refused the create without writing it (write_applied: false).
  writeRejected?: boolean;
  cloudNote?: NoteCloudText;
  requiresReconciliation?: boolean;
  reconcilePending?: boolean;
  localFolderId?: number | null;
  localSpaceId?: number;
}

// A cloud note row's text fields, as a pull or a write response carries them.
export interface NoteCloudText {
  content?: string | null;
  enhanced_content?: string | null;
  enhancement_prompt?: string | null;
  enhanced_at_content_hash?: string | null;
  enhancement_template_id?: string | null;
  content_state?: "set" | "clear" | null;
  enhanced_content_state?: "set" | "clear" | null;
}

export interface NoteCloudBaseOptions {
  // The user chose Keep on the conflict banner.
  keepLocal?: boolean;
  // The conflicting cloud copy Keep merges against: fields this device never
  // edited take its values.
  cloudNote?: NoteCloudText;
}

export interface NoteUpdateAckResult {
  success: boolean;
  outcome: "synced" | "pending" | "identity-changed";
  changes: number;
  // Present when the ack took the server's copy of a text field.
  note?: NoteItem;
}

export type ShareVisibility = "private" | "link" | "domain" | "invited";

export type NotePermission = "owner" | "editor" | "viewer";

export type NoteAccessPrincipalType = "user" | "email" | "team" | "folder" | "workspace";

export interface NoteAccessPrincipal {
  type: NoteAccessPrincipalType;
  id: string | null;
  email: string | null;
  name: string | null;
  image: string | null;
  member_count: number | null;
}

export interface NoteAccessGrant {
  id: string;
  principal: NoteAccessPrincipal;
  permission: Exclude<NotePermission, "owner">;
  source: "direct" | "team" | "folder" | "workspace";
  inherited: boolean;
  pending: boolean;
  created_at: string;
  updated_at: string;
}

export interface NoteAccessState {
  owner: NoteAccessPrincipal;
  grants: NoteAccessGrant[];
  my_permission: NotePermission;
  can_manage_access: boolean;
  can_manage_inherited_access: boolean;
}

export interface ShareSettings {
  visibility: ShareVisibility;
  token_prefix: string | null;
  domain_allowlist: string[];
  updated_by_user_id: string | null;
  updated_at: string | null;
}

export interface NoteShareInvitation {
  id: string;
  email: string;
  invited_by_user_id: string;
  accepted_at: string | null;
  revoked_at: string | null;
  last_emailed_at: string | null;
  created_at: string;
}

export interface FolderItem {
  id: number;
  name: string;
  is_default: number;
  sort_order: number;
  space_id: number;
  created_at: string;
  updated_at: string;
  client_folder_id: string;
  cloud_id: string | null;
  sync_status: "synced" | "pending" | "error";
  deleted_at: string | null;
  // 1 while a cloud-backed row that left a team space still owes its scope
  // retraction push (D6); cleared when the row settles.
  left_team?: number;
}

export type FolderPushSnapshot = Pick<
  FolderItem,
  | "client_folder_id"
  | "name"
  | "is_default"
  | "sort_order"
  | "space_id"
  | "created_at"
  | "updated_at"
  | "sync_status"
  | "deleted_at"
  | "left_team"
>;

export interface FolderAckResult {
  success: boolean;
  outcome: "synced" | "pending" | "already-linked" | "identity-changed" | "unresolved";
  changes: number;
}

/** A team assigned to a space, as mirrored from GET /api/me/spaces. */
export interface SpaceTeamRef {
  id: string;
  name: string;
  // Explicit team membership role, if any (workspace admins may have none).
  my_role?: "admin" | "member" | null;
  // Per-assignment cap on what the team conveys (space_teams.access): its
  // team admins are space admins only when this is 'admin'. Absent on
  // mirrors written before the API shipped it; those rows are 'admin'.
  access?: "admin" | "member";
}

export interface SpaceItem {
  id: number;
  client_space_id: string;
  cloud_space_id: string | null;
  // Retained only for unambiguous adoption of pre-spaces team rows.
  cloud_team_id?: string | null;
  workspace_id: string | null;
  kind: "private" | "team";
  name: string;
  emoji: string | null;
  sort_order: number;
  // Server-computed effective role: direct grant or best role across assigned
  // teams (ws owner/admin ⇒ admin).
  my_role: "admin" | "member" | null;
  // Direct space_members grant, null when access comes only via teams or the
  // workspace role. Absent on mirrors written before the API shipped it.
  my_direct_role?: TeamRole | null;
  // Server-computed deduped union of direct members and assigned team rosters.
  member_count: number | null;
  teams: SpaceTeamRef[];
  sync_status: "synced" | "pending" | "error";
  deleted_at: string | null;
  created_at: string;
  updated_at: string;
}

export interface DictionaryEntryItem {
  id: number;
  word: string;
  source: "manual" | "learned";
  created_at: string;
  updated_at: string;
  client_dict_id: string;
  cloud_id: string | null;
  sync_status: "synced" | "pending" | "error";
  deleted_at: string | null;
}

export interface SnippetEntryItem {
  id: number;
  trigger: string;
  replacement: string;
  created_at: string;
  updated_at: string;
  client_snippet_id: string;
  cloud_id: string | null;
  sync_status: "synced" | "pending" | "error";
  deleted_at: string | null;
}

export type WorkspaceRole = "owner" | "admin" | "member";

export interface Workspace {
  id: string;
  name: string;
  slug: string;
  created_by_user_id: string;
  stripe_customer_id: string | null;
  stripe_subscription_id: string | null;
  plan: string;
  status: string;
  trial_ends_at: string | null;
  current_period_end: string | null;
  cancel_at_period_end: boolean;
  seats: number;
  // Optional: absent from API responses that predate unified billing.
  seats_used?: number;
  created_at: string;
  updated_at: string;
  role: WorkspaceRole;
  is_billable?: boolean;
  billing_manager?: string | null;
}

export interface WorkspaceMember {
  user_id: string;
  role: WorkspaceRole;
  is_billable?: boolean;
  joined_at: string;
  email: string;
  name: string | null;
  image: string | null;
}

export type TeamRole = "admin" | "member";

export interface Team {
  id: string;
  workspace_id: string;
  name: string;
  slug: string;
  description: string | null;
  emoji?: string | null;
  created_at: string;
  updated_at: string;
  member_count?: number;
}

export interface TeamMember {
  user_id: string;
  role: TeamRole;
  joined_at: string;
  email: string;
  name: string | null;
  image: string | null;
}

export interface WorkspaceInvitation {
  id: string;
  email: string;
  workspace_role: WorkspaceRole;
  team_ids: string[];
  invited_by_user_id: string;
  expires_at: string;
  created_at: string;
  accepted_at: string | null;
  revoked_at: string | null;
}

export interface JoinableMember {
  name: string | null;
  email: string;
  image: string | null;
}

/**
 * A workspace the signed-in user can act on, from GET /api/me/joinable.
 * `source` is why they can see it, `mode` is what the button does: a direct
 * invitation joins, while a company-domain match only earns the right to ask
 * an admin. Enterprise SSO and SCIM provision through the SSO callback.
 */
export interface JoinableWorkspace {
  source: "invitation" | "domain";
  mode: "join" | "request";
  request_state: "none" | "pending";
  invitation_id: string | null;
  workspace_id: string;
  workspace_name: string;
  workspace_slug: string;
  role: WorkspaceRole;
  member_count: number;
  members: JoinableMember[];
  inviter_name: string | null;
  inviter_email: string | null;
}

export interface WorkspaceJoinRequest {
  id: string;
  user_id: string;
  name: string | null;
  email: string;
  image: string | null;
  created_at: string;
}

export interface InvitationPreview {
  id: string;
  email: string;
  workspace_role: WorkspaceRole;
  team_ids: string[];
  /** Live spaces the invite grants directly; absent from APIs that predate space grants. */
  space_names?: string[];
  expires_at: string;
  workspace_id: string;
  workspace_name: string;
  workspace_slug: string;
  inviter_name: string | null;
  inviter_email: string | null;
}

export interface WorkspaceApiKey {
  id: string;
  name: string;
  key_prefix: string;
  scopes: string[];
  last_used_at: string | null;
  expires_at: string | null;
  created_at: string;
  created_by_user_id: string | null;
  description: string | null;
}

export interface NewWorkspaceApiKey extends WorkspaceApiKey {
  key: string;
}

export interface TemplateSection {
  heading: string;
  instruction: string;
}

/** A template writes the AI summary; an action edits it or answers in the note chat. */
export type ActionKind = "template" | "action";
export type ActionOutput = "summary" | "chat";

export interface ActionItem {
  id: number;
  /** Stable across devices: a built-in's translation key, otherwise a UUID. */
  client_id: string;
  kind: ActionKind;
  name: string;
  description: string;
  /** A template's context, or an action's instructions. */
  prompt: string;
  sections: TemplateSection[] | null;
  output: ActionOutput | null;
  icon: string;
  is_builtin: number;
  sort_order: number;
  translation_key: string | null;
  created_at: string;
  updated_at: string;
}

export interface GpuDevice {
  index: number;
  uuid: string;
  name: string;
  vramMb: number;
}

export interface GpuInfo {
  hasNvidiaGpu: boolean;
  gpuName?: string;
  driverVersion?: string;
  vramMb?: number;
  computeCap?: number;
  /** Whether the card meets the shipped CUDA build's minimum compute capability. */
  cudaSupported?: boolean;
}

export interface CudaWhisperStatus {
  downloaded: boolean;
  downloading: boolean;
  path: string | null;
  gpuInfo: GpuInfo;
  /** CUDA fell back to CPU on this machine and stays off until retried. */
  gpuFailed?: boolean;
  /** The whisper-server error line saved with that failure; null when none was readable. */
  gpuFailReason?: string | null;
  /** The pack the GPU card describes: the one every whisper start picks, else
   * an installed pack that failed (#1736). At most one pack reports true. */
  inUse?: boolean;
  /** An older release installed the pack and this version can't use it. */
  needsUpdate?: boolean;
  /** The bundled whisper-server is itself a GPU build and runs on the GPU, so no pack is offered. */
  bundledGpu?: boolean;
}

export interface VulkanWhisperStatus {
  downloaded: boolean;
  downloading: boolean;
  vulkan: VulkanGpuResult;
  hasNvidiaGpu: boolean;
  /** Vulkan fell back to CPU on this machine and stays off until retried. */
  gpuFailed?: boolean;
  /** The whisper-server error line saved with that failure; null when none was readable. */
  gpuFailReason?: string | null;
  /** The pack the GPU card describes: the one every whisper start picks, else
   * an installed pack that failed (#1736). At most one pack reports true. */
  inUse?: boolean;
  /** An older release installed the pack and this version can't use it. */
  needsUpdate?: boolean;
  /** The bundled whisper-server is itself a GPU build and runs on the GPU, so no pack is offered. */
  bundledGpu?: boolean;
}

export interface WhisperServerStatus {
  available: boolean;
  running: boolean;
  port: number | null;
  hostname: string;
  isRemote: boolean;
  modelPath: string | null;
  modelName: string | null;
  gpuBackend: "cuda" | "vulkan" | null;
  /** True only when the running server is actually using a local GPU backend. */
  gpuAccelerated: boolean;
}

export interface WhisperCheckResult {
  installed: boolean;
  working: boolean;
  error?: string;
}

export interface WhisperModelResult {
  success: boolean;
  model: string;
  downloaded: boolean;
  size_mb?: number;
  error?: string;
  code?: string;
  isDownloading?: boolean;
  isInstalling?: boolean;
  downloadProgress?: number;
  downloadedBytes?: number;
  totalBytes?: number;
}

export interface WhisperModelDeleteResult {
  success: boolean;
  model: string;
  deleted: boolean;
  freed_mb?: number;
  error?: string;
}

export interface WhisperModelsListResult {
  success: boolean;
  models: WhisperModelResult[];
  cache_dir: string;
}

export interface FFmpegAvailabilityResult {
  available: boolean;
  path?: string;
  error?: string;
}

export interface AudioDiagnosticsResult {
  platform: string;
  arch: string;
  resourcesPath: string | null;
  isPackaged: boolean;
  ffmpeg: { available: boolean; path: string | null; error: string | null };
  whisperBinary: { available: boolean; path: string | null; error: string | null };
  whisperServer: { available: boolean; path: string | null };
  modelsDir: string;
  models: string[];
}

export type SystemAudioMode = "native" | "loopback" | "portal" | "unsupported";
export type SystemAudioStrategy =
  "native" | "loopback" | "pipewire-loopback" | "wasapi-loopback" | "unsupported";

export interface MeetingSystemAudioInterruption {
  systemAudioStrategy: SystemAudioStrategy;
  reason: "no_audio_delivered" | "device_invalidated" | "gone_quiet" | "loopback_takeover_failed";
  recovering: boolean;
}

export interface SystemAudioAccessResult {
  granted: boolean;
  status: "granted" | "denied" | "not-determined" | "restricted" | "unknown" | "unsupported";
  mode: SystemAudioMode;
  supportsPersistentGrant?: boolean;
  supportsPersistentPortalGrant?: boolean;
  supportsNativeCapture?: boolean;
  supportsOnboardingGrant?: boolean;
  requiresRuntimeSharePrompt?: boolean;
  strategy?: SystemAudioStrategy;
  restoreTokenAvailable?: boolean;
  portalVersion?: number | null;
  error?: string;
}

export interface ScreenRecordingAccessResult {
  granted: boolean;
  status: "granted" | "denied" | "not-determined" | "restricted" | "unknown" | "unsupported";
  supported: boolean;
  /** macOS only: granted mid-session, so capture stays broken until the app relaunches. */
  needsRelaunch?: boolean;
}

export type CloudReasonPurpose = "cleanup" | "assistant" | "translation" | "noteFormatting";

// Orukeet's audio language estimate, reported for the backend's per-user gate.
export interface OrukeetLanguageRoutingTelemetry {
  version: 1;
  mode: "shadow" | "supported-0.30" | "supported-0.10";
  auto: boolean;
  eligible: boolean;
  analyzedSeconds: number | null;
  topLanguage: string | null;
  topScore: number | null;
  supportedScore: number | null;
  legacyFallback: boolean;
  top05Fallback: boolean;
  candidate030: boolean | null;
  candidate010: boolean | null;
  selectedFallback: boolean;
  fallbackAvailable: boolean;
}
export interface OrukeetCleanupTelemetry {
  status: "complete" | "fallback" | "skipped";
  model?: "gemma-4-12b";
  processingMs?: number;
  queueMs?: number;
  firstTextMs?: number;
  inputTokens?: number;
  outputTokens?: number;
}
export interface OrukeetTelemetry {
  orukeetLanguageRouting?: OrukeetLanguageRoutingTelemetry;
  orukeetCleanup?: OrukeetCleanupTelemetry;
}

export interface SttDetectedLanguageFields {
  sttDetectedLanguage?: string;
  sttDetectedLanguageConfidence?: number;
  sttDetectedLanguageAudioSeconds?: number;
  sttDetectedLanguageStatus?: "detected" | "unknown";
}

export interface ScreenContextImage {
  mediaType: string;
  /** Base64 image bytes, no data-URL prefix. */
  data: string;
}

export interface UpdateCheckResult {
  updateAvailable: boolean;
  version?: string;
  releaseDate?: string;
  files?: any[];
  releaseNotes?: string;
  message?: string;
}

export interface UpdateStatusResult {
  updateAvailable: boolean;
  updateDownloaded: boolean;
  isDevelopment: boolean;
  isSupported: boolean;
}

export interface UpdateInfoResult {
  version?: string;
  releaseDate?: string;
  releaseNotes?: string | null;
  files?: any[];
}

export interface UpdateResult {
  success: boolean;
  message: string;
}

export interface AppVersionResult {
  version: string;
}

export interface WhisperDownloadProgressData {
  type: "progress" | "installing" | "complete" | "error";
  model: string;
  percentage?: number;
  downloaded_bytes?: number;
  total_bytes?: number;
  error?: string;
  code?: string;
  result?: any;
  sequence?: number;
}

export interface LocalModelDownloadStatus {
  modelType: "whisper" | "parakeet" | "llm";
  modelId: string;
  phase: "downloading" | "installing";
  progress: number;
  downloadedBytes: number;
  totalBytes: number;
  sequence: number;
}

export interface ParakeetCheckResult {
  installed: boolean;
  working: boolean;
  supported?: boolean;
  path?: string;
  code?: string;
  message?: string;
  minimumMacOSVersion?: string;
}

export interface ParakeetModelResult {
  success: boolean;
  model: string;
  downloaded: boolean;
  path?: string;
  size_bytes?: number;
  size_mb?: number;
  error?: string;
  code?: string;
  isDownloading?: boolean;
  isInstalling?: boolean;
  downloadProgress?: number;
  downloadedBytes?: number;
  totalBytes?: number;
}

export interface ParakeetModelDeleteResult {
  success: boolean;
  model: string;
  deleted: boolean;
  freed_bytes?: number;
  freed_mb?: number;
  error?: string;
}

export interface ParakeetModelsListResult {
  success: boolean;
  models: ParakeetModelResult[];
  cache_dir: string;
}

export interface ParakeetDownloadProgressData {
  type: "progress" | "installing" | "complete" | "error";
  model: string;
  percentage?: number;
  downloaded_bytes?: number;
  total_bytes?: number;
  error?: string;
  code?: string;
  sequence?: number;
}

export interface ParakeetTranscriptionResult {
  success: boolean;
  text?: string;
  message?: string;
  error?: string;
}

export interface ParakeetDiagnosticsResult {
  platform: string;
  arch: string;
  resourcesPath: string | null;
  isPackaged: boolean;
  sherpaOnnx: { available: boolean; path: string | null };
  modelsDir: string;
  models: string[];
}

export interface PasteToolsResult {
  platform: "darwin" | "win32" | "linux";
  available: boolean;
  method: string | null;
  requiresPermission: boolean;
  isWayland?: boolean;
  xwaylandAvailable?: boolean;
  terminalAware?: boolean;
  hasNativeBinary?: boolean;
  hasUinput?: boolean;
  hasWtype?: boolean;
  isWlroots?: boolean;
  isCosmic?: boolean;
  wlCopyMissing?: boolean;
  tools?: string[];
  recommendedInstall?: string;
}

export type GpuBackend = "vulkan" | "cpu" | "metal" | null;

export interface LlamaServerStatus {
  available: boolean;
  running: boolean;
  port: number | null;
  modelPath: string | null;
  modelName: string | null;
  backend: GpuBackend;
  gpuAccelerated: boolean;
}

export interface VulkanGpuResult {
  available: boolean;
  deviceName?: string;
  reason?: string;
  error?: string;
}

export interface LlamaVulkanStatus {
  supported: boolean;
  downloaded: boolean;
  downloading?: boolean;
  error?: string;
}

export interface LlamaVulkanDownloadProgress {
  downloaded: number;
  total: number;
  percentage: number;
}

export interface LocalLLMModelStatus extends ModelDefinition {
  providerId?: string;
  providerName?: string;
  isDownloaded: boolean;
  isDownloading: boolean;
  downloadProgress: number;
  downloadedSize: number;
  totalSize: number;
  path: string | null;
}

export type LocalLLMDownloadProgressEvent =
  | {
      type?: "progress";
      modelId: string;
      progress: number;
      downloadedSize: number;
      totalSize: number;
      sequence?: number;
    }
  | {
      type: "complete";
      modelId: string;
      progress: 100;
      downloadedSize?: number;
      totalSize?: number;
      sequence?: number;
    }
  | {
      type: "error";
      modelId: string;
      error: string;
      code?: string;
      details?: unknown;
      sequence?: number;
    };

export interface ConversationPreview {
  id: number;
  title: string;
  created_at: string;
  updated_at: string;
  archived_at?: string | null;
  cloud_id?: string | null;
  client_conversation_id?: string;
  sync_status?: "synced" | "pending" | "error";
  deleted_at?: string | null;
  // Computed for sync lookups while the parent folder delete is unresolved.
  folder_delete_pending?: number;
  message_count: number;
  last_message?: string | null;
  last_message_role?: "user" | "assistant" | "system" | null;
}

export interface ConversationCreateSnapshot {
  client_conversation_id?: string | null;
  title: string;
  updated_at: string;
  message_count: number;
}

export interface ConversationCreateAckResult {
  success: boolean;
  outcome: "synced" | "changed" | "already-linked" | "delete-pending" | "orphaned" | "unresolved";
  cloud_id?: string | null;
}

export type OnboardingDemoKind = "dictation" | "assistant";
/**
 * "partial" streams the transcript, "processing" carries the final transcript,
 * "replying" streams the assistant demo's reply, and "level" mirrors the
 * microphone level while listening.
 */
export type OnboardingDemoStatus =
  "listening" | "level" | "processing" | "partial" | "replying" | "success" | "error";
export interface OnboardingDemoEvent {
  demoId: string;
  kind: OnboardingDemoKind;
  status: OnboardingDemoStatus;
  text?: string;
  message?: string;
  /** Tool the assistant is running while it replies (a tool registry name). */
  tool?: string;
  /** Microphone input level, 0..1, on "level" events. */
  level?: number;
}

export interface ReferralItem {
  id: string;
  email: string;
  name: string | null;
  status: "pending" | "completed" | "rewarded";
  created_at: string;
  first_payment_at: string | null;
}

declare global {
  interface Window {
    electronAPI: {
      // Basic window operations
      setOnboardingWindowMode?: (mode: "compact" | "expanded" | "restore") => Promise<boolean>;
      setOnboardingActive?: (active: boolean) => Promise<boolean>;
      openPermissionGuide?: (state: PermissionGuideState) => Promise<boolean>;
      closePermissionGuide?: () => Promise<boolean>;
      getPermissionGuideState?: () => Promise<PermissionGuideState | null>;
      permissionGuideAction?: (action: PermissionGuideAction) => void;
      startPermissionGuideDrag?: (
        target: Pick<PermissionGuideState, "sessionId" | "permission">
      ) => void;
      onPermissionGuideState?: (callback: (state: PermissionGuideState) => void) => () => void;
      onPermissionGuideAction?: (callback: (action: PermissionGuideAction) => void) => () => void;
      verifySystemAudioAccess?: () => Promise<SystemAudioAccessResult>;
      beginOnboardingDemo?: (session: { id: string; kind: OnboardingDemoKind }) => Promise<boolean>;
      endOnboardingDemo?: (id: string) => Promise<boolean>;
      stopOnboardingDemo?: (id: string) => Promise<boolean>;
      publishOnboardingDemoEvent?: (event: Omit<OnboardingDemoEvent, "demoId">) => Promise<boolean>;
      onOnboardingDemoEvent?: (callback: (event: OnboardingDemoEvent) => void) => () => void;
      testProviderConnection?: (config: {
        scope: "transcription" | "reasoning";
        provider: string;
        apiKey?: string;
        baseUrl?: string;
        model?: string;
        clientId?: string;
        clientSecret?: string;
        environment?: string;
        tenant?: string;
      }) => Promise<{
        success: boolean;
        error?: string;
        errorCode?: string;
        status?: number;
        /** The provider gave no verdict (busy, down, unreachable); the setup may be used. */
        unverified?: boolean;
      }>;
      pasteText: (
        text: string,
        options?: {
          fromStreaming?: boolean;
          restoreClipboard?: boolean;
          allowClipboardFallback?: boolean;
        }
      ) => Promise<
        | {
            success: true;
            pasted: boolean;
            reason?: "modifiers-held" | "wl-copy-missing" | "wl-copy-failed";
          }
        | {
            success: false;
            pasted: false;
            code: "ACCESSIBILITY_PERMISSION_REQUIRED";
            clipboardCopied: true;
          }
      >;
      captureSelectedText?: (options?: { probeEditable?: boolean }) => Promise<
        | {
            status: "selected";
            sessionId: string;
            text: string;
            characterCount: number;
          }
        | {
            status: "editable";
            sessionId: string;
            /** True when the captured app keeps markdown (spec Appendix A); false means plain text. */
            acceptsMarkdown: boolean;
          }
        | {
            status: "none" | "unavailable" | "target_changed" | "too_large";
            code?: string;
            characterCount?: number;
            maxCharacters?: number;
          }
      >;
      replaceSelectedText?: (
        sessionId: string,
        text: string,
        options?: { restoreClipboard?: boolean; allowClipboardFallback?: boolean }
      ) => Promise<{
        success: boolean;
        code?:
          | "invalid_replacement"
          | "session_expired"
          | "target_changed"
          | "selection_unavailable"
          | "selection_changed"
          | "paste_failed"
          | "modifiers_held"
          | "wl_copy_missing"
          | "wl_copy_failed"
          | "selection_manager_unavailable";
        error?: string;
      }>;
      pasteAtCapturedTarget?: (
        sessionId: string,
        text: string,
        options?: { restoreClipboard?: boolean; allowClipboardFallback?: boolean }
      ) => Promise<{
        success: boolean;
        code?:
          | "invalid_replacement"
          | "session_expired"
          | "target_changed"
          | "paste_failed"
          | "modifiers_held"
          | "wl_copy_missing"
          | "wl_copy_failed"
          | "selection_manager_unavailable";
        error?: string;
      }>;
      hideWindow: () => Promise<void>;
      showDictationPanel: () => Promise<void>;
      openSettingsSection?: (section: ProviderSettingsTarget) => Promise<{ success: boolean }>;
      captureDictationTarget?: () => Promise<{ success: boolean; pid: number | null }>;
      captureDictationAppCategory?: () => Promise<ToneAppCategory>;
      onToggleDictation: (callback: () => void) => () => void;
      onToggleVoiceAgent?: (callback: () => void) => () => void;
      onToggleTranslation?: (callback: () => void) => () => void;
      onOpenAssistantPanel?: (callback: () => void) => () => void;
      onStartDictation?: (callback: () => void) => () => void;
      onStopDictation?: (callback: () => void) => () => void;
      onPrepareDictation?: (
        callback: (options?: { inputKind?: "dictation" | "assistant" | "translation" }) => void
      ) => () => void;
      onCancelDictationPreparation?: (callback: () => void) => () => void;
      onCancelDictation?: (callback: () => void) => () => void;
      onDictationForceStopped?: (
        callback: (payload?: { reason?: "timeout" | "reset" | "manual" }) => void
      ) => () => void;
      micWarmHoldChanged?: (active: boolean) => void;
      dictationLifecycleStateChanged: (
        state: "idle" | "preparing" | "recording" | "processing",
        inputKind?: "dictation" | "assistant" | "translation"
      ) => void;
      dictationAudioLevelChanged?: (level: number) => void;
      toggleAgentPanelDictation?: () => Promise<{ success: boolean }>;
      cancelAgentPanelDictation?: () => Promise<{ success: boolean }>;
      getAgentDictationPillState?: () => Promise<{
        lifecycle: "idle" | "preparing" | "recording" | "processing";
        interactive: boolean;
        horizontalDirection: "left" | "right";
      }>;
      resizeAgentDictationPillToContent?: (surfaceHeight: number | null) => Promise<{
        success: boolean;
        changed?: boolean;
        bounds?: { x: number; y: number; width: number; height: number };
        message?: string;
      }>;
      setAgentDictationPillInteractivity?: (interactive: boolean) => Promise<{ success: boolean }>;
      onAgentDictationPillStateChanged?: (
        callback: (state: {
          lifecycle: "idle" | "preparing" | "recording" | "processing";
          interactive: boolean;
          horizontalDirection: "left" | "right";
        }) => void
      ) => () => void;
      onAgentDictationPillAudioLevelChanged?: (callback: (level: number) => void) => () => void;
      showAgentDictationFinalTranscript?: (text: string) => void;
      onAgentDictationPillFinalTranscript?: (callback: (text: string) => void) => () => void;

      // STT config
      getSttConfig?: () => Promise<
        | ({
            success: boolean;
            dictation?: { mode: string };
            notes?: { mode: string };
            streamingProvider?: string;
            orukeetPipeline?: "gemma12";
            orukeetLanguageRouting?: "off" | "shadow" | "supported-0.30" | "supported-0.10";
          } & PolicyFailureMetadata)
        | null
      >;

      // Org policy (see src/types/policy.ts)
      getWorkspacePolicy?: (
        accountId?: string,
        expectedAuthGeneration?: number
      ) => Promise<{
        success: boolean;
        status?: "network" | "cached" | "current" | "unsupported" | "restricted" | "error";
        revision?: number;
        accountId?: string | null;
        authGeneration?: number | null;
        managed?: boolean;
        policy?: OrgPolicy | null;
        policyUpdatedAt?: string | null;
        endpointSupported?: boolean;
        code?: string;
        error?: string;
        enforcementRequired?: boolean;
      }>;
      onWorkspacePolicyChanged?: (
        callback: (
          snapshot:
            | {
                success: true;
                status: "network" | "cached" | "current" | "unsupported";
                revision: number;
                accountId: string | null;
                authGeneration: number;
                managed: boolean;
                policy: OrgPolicy | null;
                policyUpdatedAt: string | null;
                endpointSupported: boolean;
              }
            | {
                success: false;
                status: "error";
                revision: number;
                accountId: string | null;
                authGeneration: number;
                code: "POLICY_UNRESOLVABLE";
                error: string;
              }
        ) => void
      ) => () => void;

      getNoteRecordingConfig?: () => Promise<NoteRecordingConfigResult | null>;

      // Database operations
      saveTranscription: (
        text: string,
        rawText?: string | null,
        options?: {
          status?: TranscriptionStatus;
          errorMessage?: string | null;
          errorCode?: TranscriptionErrorCode;
          clientTranscriptionId?: string;
          analyticsOccurredAt?: string;
        }
      ) => Promise<{ id: number; success: boolean; transcription?: TranscriptionItem }>;
      getTranscriptions: (
        limit?: number,
        options?: { includeDiscarded?: boolean }
      ) => Promise<TranscriptionItem[]>;
      recordAnalyticsEvent: (
        input: AnalyticsEventInput
      ) => Promise<{ success: boolean; eventId?: string; ignored?: boolean }>;
      getAnalyticsSummary: () => Promise<AnalyticsSummary>;
      getPendingAnalyticsEvents: (
        limit?: number,
        context?: AnalyticsSyncContext
      ) => Promise<PendingAnalyticsEvent[]>;
      markAnalyticsEventsSynced: (
        eventIds: string[],
        context?: AnalyticsSyncContext
      ) => Promise<{ success: boolean; updated: number }>;
      getPendingAnalyticsDeletes: (
        limit?: number,
        context?: AnalyticsSyncContext
      ) => Promise<Array<{ event_id: string }>>;
      hardDeleteAnalyticsEvents: (
        eventIds: string[],
        context?: AnalyticsSyncContext
      ) => Promise<{ success: boolean; deleted: number }>;
      getPendingAnalyticsClear: (
        context?: AnalyticsSyncContext
      ) => Promise<PendingAnalyticsClear | null>;
      completeAnalyticsClear: (
        clearedThrough: string,
        context?: AnalyticsSyncContext
      ) => Promise<{ success: boolean; deleted: number }>;
      countUnclaimedAnalyticsEvents: (context?: AnalyticsSyncContext) => Promise<number>;
      countAnalyticsEventsAwaitingUpload: (context?: AnalyticsSyncContext) => Promise<number>;
      claimAnonymousAnalyticsEvents: (
        accountId: string,
        expectedAuthGeneration: number
      ) => Promise<{ success: boolean; claimed: number; code?: string }>;
      clearTranscriptions: () => Promise<{ cleared: number; success: boolean }>;
      deleteTranscription: (id: number) => Promise<{ success: boolean }>;
      getTranscriptionById: (id: number) => Promise<TranscriptionItem | null>;

      // Audio retention operations
      saveTranscriptionAudio: (
        id: number,
        audioBuffer: ArrayBuffer,
        metadata?: { durationMs?: number; provider?: string; model?: string }
      ) => Promise<{ success: boolean; path?: string }>;
      mergeAudioSegments: (
        segments: Array<{ buffer: ArrayBuffer; mimeType: string }>
      ) => Promise<
        | { success: true; buffer: ArrayBuffer; mimeType: "audio/webm" }
        | { success: false; error: string }
      >;
      getAudioPath: (id: number) => Promise<string | null>;
      showAudioInFolder: (id: number) => Promise<{ success: boolean }>;
      getAudioBuffer: (id: number) => Promise<ArrayBuffer | null>;
      deleteTranscriptionAudio: (id: number) => Promise<{ success: boolean }>;
      getAudioStorageUsage: () => Promise<{ fileCount: number; totalBytes: number }>;
      deleteAllAudio: () => Promise<{ deleted: number }>;
      syncRetentionSettings?: (settings: {
        audioRetentionDays: number;
        transcriptRetentionDays: number;
        dataRetentionEnabled: boolean;
        localHistoryPolicyResolved: boolean;
      }) => void;
      retryTranscription: (
        id: number,
        settings?: {
          useLocalWhisper: boolean;
          localTranscriptionProvider: string;
          cloudTranscriptionMode: string;
          cloudTranscriptionProvider: string;
          cloudTranscriptionModel: string;
          cloudTranscriptionBaseUrl?: string;
          cortiEnvironment?: string;
          cortiTenant?: string;
          parakeetModel: string;
          cohereModel: string;
          whisperModel: string;
          preferredLanguage?: string;
          transcriptionMode?: InferenceMode;
          remoteTranscriptionType?: SelfHostedType;
          remoteTranscriptionUrl?: string;
          remoteTranscriptionModel?: string;
          managed?: {
            kind: "managed";
            provider: "azure";
            deployment: string;
            context: ManagedEnterpriseRequestContext;
          };
        }
      ) => Promise<{
        success: boolean;
        transcription?: TranscriptionItem;
        warning?: string;
        error?: string;
        code?: string;
        messageKey?: string;
      }>;
      updateTranscriptionText: (
        id: number,
        text: string,
        rawText: string
      ) => Promise<{ success: boolean; transcription?: TranscriptionItem; error?: string }>;

      // Dictionary operations
      getDictionary: () => Promise<string[]>;
      /** Replaces the whole dictionary — omitted words are deleted. Prefer applyDictionaryChanges. */
      setDictionary: (words: string[]) => Promise<{ success: boolean }>;
      applyDictionaryChanges?: (changes: {
        add?: string[];
        remove?: string[];
      }) => Promise<{ success: boolean; added: number; removed: number }>;
      onDictionaryUpdated?: (callback: (words: string[]) => void) => () => void;
      getSnippets?: () => Promise<Array<{ trigger: string; replacement: string }>>;
      setSnippets?: (
        snippets: Array<{ trigger: string; replacement: string }>
      ) => Promise<{ success: boolean }>;
      onSnippetsUpdated?: (
        callback: (snippets: Array<{ trigger: string; replacement: string }>) => void
      ) => () => void;
      setAutoLearnEnabled?: (enabled: boolean) => void;
      onCorrectionsLearned?: (callback: (words: string[]) => void) => () => void;
      undoLearnedCorrections?: (words: string[]) => Promise<{ success: boolean }>;

      // Note operations
      saveNote: (
        title: string,
        content: string,
        noteType?: string,
        sourceFile?: string | null,
        audioDuration?: number | null,
        folderId?: number | null,
        spaceId?: number | null,
        transcript?: string | null
      ) => Promise<{ success: boolean; note?: NoteItem }>;
      getNote: (id: number) => Promise<NoteItem | null>;
      getNotes: (
        noteType?: string | null,
        limit?: number,
        folderId?: number | null,
        spaceId?: number | null
      ) => Promise<NoteItem[]>;
      getSpaceNotes: (spaceId: number, limit?: number) => Promise<NoteItem[]>;
      updateNote: (
        id: number,
        updates: {
          clear_fields?: Array<"content" | "enhanced_content">;
          title?: string;
          content?: string;
          enhanced_content?: string | null;
          enhancement_prompt?: string | null;
          enhancement_template_id?: string | null;
          enhanced_at_content_hash?: string | null;
          folder_id?: number | null;
          space_id?: number;
          transcript?: string | null;
          calendar_event_id?: string | null;
          participants?: string | null;
          diarization_enabled?: number | null;
          expected_speaker_count?: number | null;
          client_note_id?: string;
          cloud_id?: string | null;
          cloud_updated_at?: string | null;
          owner_user_id?: string | null;
          updated_by_user_id?: string | null;
          left_team?: number;
        },
        options?: { undoable: true; expected: NoteItem; turn?: string }
      ) => Promise<{ success: boolean; note?: NoteItem; error?: string }>;
      getNoteUndos: () => Promise<Array<{ token: string; noteId: number; title: string }>>;
      claimNoteUndo: (token: string) => Promise<boolean>;
      undoNoteUpdate: (
        token: string
      ) => Promise<{ success: boolean; note?: NoteItem; error?: string }>;
      discardNoteUndo: (id: number, token?: string) => Promise<void>;
      deleteNote: (id: number) => Promise<{ success: boolean }>;
      exportNote: (
        noteId: number,
        format: "txt" | "md"
      ) => Promise<{ success: boolean; error?: string }>;
      exportTranscript: (
        noteId: number,
        format: "txt" | "srt" | "json" | "md"
      ) => Promise<{ success: boolean; error?: string }>;
      exportDictionary: (words: string[]) => Promise<{ success: boolean; error?: string }>;
      searchNotes: (
        query: string,
        limit?: number,
        spaceId?: number | null,
        folderId?: number | null
      ) => Promise<NoteItem[]>;
      semanticSearchNotes: (
        query: string,
        limit?: number,
        spaceId?: number | null,
        folderId?: number | null
      ) => Promise<NoteItem[]>;
      updateNoteCloudId: (id: number, cloudId: string) => Promise<NoteItem>;
      updateNoteShareState: (
        id: number,
        state: { is_shared: number; share_token?: string | null }
      ) => Promise<NoteItem>;

      // Folder operations
      getFolders: (spaceId?: number | null) => Promise<FolderItem[]>;
      createFolder: (
        name: string,
        spaceId?: number | null
      ) => Promise<{ success: boolean; folder?: FolderItem; error?: string }>;
      deleteFolder: (id: number) => Promise<{ success: boolean; error?: string }>;
      renameFolder: (
        id: number,
        name: string
      ) => Promise<{ success: boolean; folder?: FolderItem; error?: string }>;
      moveFolderToSpace: (
        id: number,
        spaceId: number
      ) => Promise<{ success: boolean; folder?: FolderItem; notes?: NoteItem[]; error?: string }>;
      getFolderNoteCounts: () => Promise<
        Array<{ space_id: number; folder_id: number | null; count: number }>
      >;

      // Space operations
      getSpaces?: () => Promise<SpaceItem[]>;
      setActiveAccountScope?: (
        accountId: string | null,
        expectedAuthGeneration?: number
      ) => Promise<{ success: boolean; code?: string; error?: string }>;
      closeActivationStream?: () => Promise<void>;
      beginActivationCapture?: () => Promise<string | null>;
      stopActivationCapture?: (id: string) => Promise<void>;
      finishActivationCapture?: (id: string, words: number) => Promise<void>;
      cancelActivationCapture?: (id: string) => Promise<void>;
      getActiveAccountScope?: () => Promise<ActiveAccountScope | null>;
      onActiveAccountScopeChanged?: (
        callback: (scope: ActiveAccountScope | null) => void
      ) => () => void;
      deleteAccountData?: (
        accountId: string,
        expectedAuthGeneration: number,
        options?: { erasingDevice?: boolean }
      ) => Promise<{
        success: boolean;
        code?: string;
        error?: string;
        deletedNoteIds?: number[];
        deletedFolderIds?: number[];
      }>;
      updateSpace?: (
        id: number,
        updates: { name?: string; emoji?: string | null }
      ) => Promise<{ success: boolean; space?: SpaceItem; error?: string }>;
      purgeSpace?: (
        id: number,
        options?: {
          mode?: "preserve-dirty" | "destructive";
          expectedAuthGeneration?: number;
        }
      ) => Promise<{
        success: boolean;
        code?: string;
        error?: string;
        noteIds?: number[];
        folderNames?: string[];
        spaceId?: number;
        relocatedNotes?: NoteItem[];
        relocatedCount?: number;
        relocatedTitles?: string[];
        preservedForOtherAccounts?: boolean;
      }>;
      upsertSpaceFromCloud?: (space: Record<string, unknown>) => Promise<SpaceItem>;
      setSpaceSyncStatus?: (
        id: number,
        status: SpaceItem["sync_status"]
      ) => Promise<{ success: boolean; space?: SpaceItem | null }>;
      onSpacePurged?: (callback: (payload: { spaceId: number }) => void) => () => void;
      onSpaceSynced?: (callback: (space: SpaceItem) => void) => () => void;

      // Note files (markdown mirror)
      noteFilesSetEnabled?: (
        enabled: boolean,
        customPath?: string,
        options?: { skipRebuild?: boolean }
      ) => Promise<{ success: boolean; error?: string }>;
      noteFilesSetPath?: (path: string) => Promise<{ success: boolean; error?: string }>;
      noteFilesRebuild?: () => Promise<{ success: boolean; error?: string }>;
      noteFilesGetDefaultPath?: () => Promise<string>;
      noteFilesPickFolder?: () => Promise<{ canceled: boolean; path?: string }>;
      granolaImportPickAndPreview?: () => Promise<{
        canceled: boolean;
        success?: boolean;
        error?: string;
        fileName?: string;
        total?: number;
        newCount?: number;
        duplicateCount?: number;
        sampleTitles?: string[];
        rowIssueCount?: number;
      }>;
      granolaImportRun?: () => Promise<{
        success: boolean;
        error?: string;
        imported?: number;
        skipped?: number;
        errors?: Array<{ clientNoteId: string; error: string }>;
      }>;
      showNoteFile?: (noteId: number) => Promise<{ success: boolean }>;
      showFolderInExplorer?: (folderName: string) => Promise<{ success: boolean }>;

      // Action operations
      getActions: () => Promise<ActionItem[]>;
      getAction: (id: number) => Promise<ActionItem | null>;
      createAction: (
        name: string,
        description: string,
        prompt: string,
        icon?: string,
        fields?: { kind?: ActionKind; sections?: TemplateSection[]; output?: ActionOutput }
      ) => Promise<{ success: boolean; action?: ActionItem; error?: string }>;
      updateAction: (
        id: number,
        updates: {
          name?: string;
          description?: string;
          prompt?: string;
          icon?: string;
          sort_order?: number;
          sections?: TemplateSection[];
          output?: ActionOutput;
        }
      ) => Promise<{ success: boolean; action?: ActionItem; error?: string }>;
      deleteAction: (id: number) => Promise<{ success: boolean; id?: number; error?: string }>;
      onActionCreated?: (callback: (action: ActionItem) => void) => () => void;
      onActionUpdated?: (callback: (action: ActionItem) => void) => () => void;
      onActionDeleted?: (callback: (payload: { id: number }) => void) => () => void;

      // Audio file operations
      saveTempAudio: (buffer: ArrayBuffer) => Promise<{ success: boolean; path: string }>;
      deleteTempAudio: (tempPath: string) => Promise<{ success: boolean; error?: string }>;
      selectAudioFile: (options?: { multiple?: boolean }) => Promise<{
        canceled: boolean;
        filePath?: string;
        filePaths?: string[];
      }>;
      getFileSize?: (filePath: string) => Promise<number>;
      transcribeAudioFile: (
        filePath: string,
        options?: {
          provider?: LocalTranscriptionProvider;
          model?: string;
          language?: string;
          requestId?: string;
          [key: string]: unknown;
        }
      ) => Promise<{ success: boolean; text?: string; error?: string; code?: string }>;
      getPathForFile: (file: File) => string;

      // URL audio download
      downloadUrlAudio: (
        url: string,
        downloadId?: string
      ) => Promise<
        | {
            success: true;
            tempPath: string;
            title: string;
            durationSeconds: number | null;
            sizeBytes: number;
          }
        | { success: false; error: string; code?: string }
      >;
      cancelUrlDownload: (downloadId?: string) => Promise<{ success: boolean }>;
      deleteTempFile: (filePath: string) => Promise<{ success: boolean; error?: string }>;
      onUrlDownloadProgress?: (
        callback: (data: {
          stage: "resolving" | "downloading" | "ready";
          percent: number;
          title?: string;
          downloadId?: string;
        }) => void
      ) => () => void;

      // Note event listeners
      onNoteAdded?: (callback: (note: NoteItem) => void) => () => void;
      onNoteUpdated?: (callback: (note: NoteItem) => void) => () => void;
      onNoteDeleted?: (callback: (payload: { id: number }) => void) => () => void;
      onNoteSynced?: (callback: (note: NoteItem) => void) => () => void;
      onFolderSynced?: (callback: (folder: FolderItem) => void) => () => void;
      onFolderDeleted?: (callback: (payload: { id: number }) => void) => () => void;

      // Cross-window sync events
      emitSyncEvent?: (name: string, payload?: unknown) => Promise<{ success: boolean }>;
      onSyncEvent?: (callback: (event: { name: string; payload?: unknown }) => void) => () => void;

      // Database event listeners
      onTranscriptionAdded?: (callback: (item: TranscriptionItem) => void) => () => void;
      onTranscriptionUpdated?: (callback: (item: TranscriptionItem) => void) => () => void;
      onTranscriptionDeleted?: (callback: (payload: { id: number }) => void) => () => void;
      onTranscriptionsCleared?: (callback: (payload: { cleared: number }) => void) => () => void;
      onAnalyticsChanged?: (callback: () => void) => () => void;

      // API key management
      getOpenAIKey: () => Promise<string>;
      saveOpenAIKey: (key: string) => Promise<{ success: boolean }>;
      getAnthropicKey: () => Promise<string | null>;
      saveAnthropicKey: (key: string) => Promise<void>;
      getUiLanguage: () => Promise<string>;
      saveUiLanguage: (language: string) => Promise<{ success: boolean; language: string }>;
      setUiLanguage: (language: string) => Promise<{ success: boolean; language: string }>;
      saveAllKeysToEnv: () => Promise<{ success: boolean; path: string }>;
      syncStartupPreferences: (
        prefs: LocalServerPrefs & {
          useLocalWhisper: boolean;
          localTranscriptionProvider: LocalTranscriptionProvider;
          model?: string;
          language?: string;
          keepLocalModelLoaded: boolean;
          policySettled: boolean;
        }
      ) => Promise<void>;

      // Clipboard operations
      checkAccessibilityPermission: (silent?: boolean) => Promise<boolean>;
      promptAccessibilityPermission: () => Promise<boolean>;
      readClipboard: () => Promise<string>;
      writeClipboard: (text: string) => Promise<{ success: boolean; xwaylandOnly?: boolean }>;
      copyLeaderboardImage: (dataUrl: string) => Promise<{ success: boolean; error?: string }>;
      saveLeaderboardImage: (
        dataUrl: string,
        suggestedName: string
      ) => Promise<{ success: boolean; canceled?: boolean; error?: string }>;
      checkPasteTools: () => Promise<PasteToolsResult>;

      // Audio

      // Whisper operations (whisper.cpp)
      transcribeLocalWhisper: (audioBlob: Blob | ArrayBuffer, options?: any) => Promise<any>;
      checkWhisperInstallation: () => Promise<WhisperCheckResult>;
      downloadWhisperModel: (modelName: string) => Promise<WhisperModelResult>;
      onWhisperDownloadProgress: (
        callback: (event: any, data: WhisperDownloadProgressData) => void
      ) => () => void;
      checkModelStatus: (modelName: string) => Promise<WhisperModelResult>;
      listWhisperModels: () => Promise<WhisperModelsListResult>;
      deleteWhisperModel: (modelName: string) => Promise<WhisperModelDeleteResult>;
      deleteAllWhisperModels: () => Promise<{
        success: boolean;
        deleted_count?: number;
        freed_bytes?: number;
        freed_mb?: number;
        error?: string;
      }>;
      cancelWhisperDownload: () => Promise<{
        success: boolean;
        message?: string;
        error?: string;
      }>;

      // Whisper server lifecycle
      whisperServerStatus: () => Promise<WhisperServerStatus>;
      whisperGpuRetry: () => Promise<{ success: boolean; willRestart: boolean }>;

      // CUDA GPU acceleration
      listGpus?: () => Promise<GpuDevice[]>;
      setGpuDeviceIndex?: (
        purpose: "transcription" | "intelligence",
        uuid: string
      ) => Promise<{ success: boolean }>;
      getGpuDeviceIndex?: (purpose: "transcription" | "intelligence") => Promise<string>;
      detectGpu: () => Promise<GpuInfo>;
      getCudaWhisperStatus: () => Promise<CudaWhisperStatus>;
      downloadCudaWhisperBinary: () => Promise<{
        success: boolean;
        willRestart?: boolean;
        error?: string;
      }>;
      cancelCudaWhisperDownload: () => Promise<{ success: boolean }>;
      deleteCudaWhisperBinary: () => Promise<{ success: boolean }>;
      onCudaDownloadProgress: (
        callback: (data: {
          downloadedBytes: number;
          totalBytes: number;
          percentage: number;
        }) => void
      ) => () => void;
      onCudaFallbackNotification: (callback: () => void) => () => void;

      // Vulkan GPU acceleration (whisper on AMD/Intel GPUs)
      getVulkanWhisperStatus: () => Promise<VulkanWhisperStatus>;
      downloadVulkanWhisperBinary: () => Promise<{
        success: boolean;
        willRestart?: boolean;
        error?: string;
      }>;
      cancelVulkanWhisperDownload: () => Promise<{ success: boolean }>;
      deleteVulkanWhisperBinary: () => Promise<{ success: boolean; deletedCount?: number }>;
      onVulkanWhisperDownloadProgress: (
        callback: (data: {
          downloadedBytes: number;
          totalBytes: number;
          percentage: number;
        }) => void
      ) => () => void;
      onGpuFallbackNotification: (callback: () => void) => () => void;
      onWhisperGpuStatusChanged: (callback: () => void) => () => void;

      // One-time "GPU pack needs re-downloading" notice, taken by the window that shows it
      takeGpuPackMigrationNotice: () => Promise<{ packs: string[] } | null>;
      onGpuPackMigrationNoticeReady: (callback: () => void) => () => void;

      // Parakeet operations (NVIDIA via sherpa-onnx)
      transcribeLocalParakeet: (
        audioBlob: ArrayBuffer,
        options?: { model?: string; language?: string }
      ) => Promise<ParakeetTranscriptionResult>;
      checkParakeetInstallation: () => Promise<ParakeetCheckResult>;
      downloadParakeetModel: (modelName: string) => Promise<ParakeetModelResult>;
      onParakeetDownloadProgress: (
        callback: (event: any, data: ParakeetDownloadProgressData) => void
      ) => () => void;
      checkParakeetModelStatus: (modelName: string) => Promise<ParakeetModelResult>;
      listParakeetModels: () => Promise<ParakeetModelsListResult>;
      deleteParakeetModel: (modelName: string) => Promise<ParakeetModelDeleteResult>;
      deleteAllParakeetModels: () => Promise<{
        success: boolean;
        deleted_count?: number;
        freed_bytes?: number;
        freed_mb?: number;
        error?: string;
      }>;
      cancelParakeetDownload: () => Promise<
        {
          success: boolean;
          message?: string;
        } & PolicyFailureMetadata
      >;
      getParakeetDiagnostics: () => Promise<ParakeetDiagnosticsResult>;

      // Local AI model management
      modelGetAll: () => Promise<LocalLLMModelStatus[]>;
      modelGetActiveDownloads: () => Promise<LocalModelDownloadStatus[]>;
      modelCheck: (modelId: string) => Promise<boolean>;
      modelDownload: (modelId: string) => Promise<{
        success: boolean;
        path?: string;
        error?: string;
        code?: string;
        details?: string;
      }>;
      modelDelete: (modelId: string) => Promise<{
        success: boolean;
        error?: string;
        code?: string;
        details?: string;
      }>;
      modelDeleteAll: () => Promise<{
        success: boolean;
        error?: string;
        code?: string;
        details?: string;
      }>;
      modelCheckRuntime: () => Promise<{
        available: boolean;
        error?: string;
        code?: string;
        details?: string;
      }>;
      modelCancelDownload: (modelId: string) => Promise<{ success: boolean; error?: string }>;
      onModelDownloadProgress: (
        callback: (event: any, data: LocalLLMDownloadProgressEvent) => void
      ) => () => void;

      // Local reasoning
      processLocalReasoning: (
        text: string,
        modelId: string,
        agentName: string | null,
        config: ReasoningConfig
      ) => Promise<{
        success: boolean;
        text?: string;
        error?: string;
        code?: string;
        details?: Record<string, unknown>;
      }>;
      checkLocalReasoningAvailable: () => Promise<boolean>;
      /** The largest context this machine can give a bundled model; drives chunked note generation. */
      getLocalContextBudget: (modelId: string) => Promise<{
        success: boolean;
        maxContextTokens?: number;
        modelName?: string;
        error?: string;
      }>;
      /** Aborts the local request tagged with this `requestId`, if it is still in flight. */
      cancelLocalReasoning: (requestId: string) => Promise<void>;

      // Anthropic reasoning
      processAnthropicReasoning: (
        text: string,
        modelId: string,
        agentName: string | null,
        config: any
      ) => Promise<{ success: boolean; text?: string } & Partial<IpcErrorFields>>;

      // Enterprise reasoning (Bedrock, Azure, Vertex)
      processEnterpriseReasoning: (
        text: string,
        modelId: string,
        agentName: string | null,
        config: any
      ) => Promise<{
        success: boolean;
        text?: string;
        error?: string;
        messageKey?: string;
        messageParams?: Record<string, string | number>;
        action?: string;
        actionKey?: string;
        copyCommand?: string;
        retryable?: boolean;
        technicalDetails?: {
          status?: number;
          exceptionType?: string;
          requestId?: string;
          underlyingError?: string;
        };
      }>;
      cancelEnterpriseReasoning?: () => void;
      enterpriseStreamStart?: (payload: {
        streamId: string;
        provider: string;
        modelId: string;
        config: Record<string, unknown>;
        options: Record<string, unknown>;
      }) => Promise<{ success: boolean; error?: string }>;
      enterpriseStreamCancel?: (streamId: string) => Promise<void>;
      onEnterpriseStreamPart?: (
        callback: (payload: {
          streamId: string;
          part?: unknown;
          done?: boolean;
          error?: string;
        }) => void
      ) => () => void;
      listBedrockModels?: (config: Record<string, unknown>) => Promise<{
        success: boolean;
        models?: Array<{ value: string; label: string; vendor: string }>;
        error?: string;
      }>;

      // llama.cpp management
      llamaCppCheck: () => Promise<{ isInstalled: boolean; version?: string }>;
      llamaCppInstall: () => Promise<{ success: boolean; error?: string }>;
      llamaCppUninstall: () => Promise<{ success: boolean; error?: string }>;

      // llama-server
      llamaServerStart: (
        modelId: string
      ) => Promise<{ success: boolean; port?: number; error?: string }>;
      llamaServerStatus: () => Promise<LlamaServerStatus>;
      llamaGpuReset: () => Promise<{ success: boolean; error?: string }>;
      detectVulkanGpu?: () => Promise<VulkanGpuResult>;
      getLlamaVulkanStatus?: () => Promise<LlamaVulkanStatus>;
      downloadLlamaVulkanBinary?: () => Promise<{
        success: boolean;
        cancelled?: boolean;
        error?: string;
      }>;
      cancelLlamaVulkanDownload?: () => Promise<{ success: boolean }>;
      deleteLlamaVulkanBinary?: () => Promise<{
        success: boolean;
        deletedCount?: number;
        error?: string;
      }>;
      onLlamaVulkanDownloadProgress?: (
        callback: (data: LlamaVulkanDownloadProgress) => void
      ) => () => void;

      // Window control operations
      windowMinimize: () => Promise<void>;
      windowMaximize: () => Promise<void>;
      windowClose: () => Promise<void>;
      windowIsMaximized: () => Promise<boolean>;
      snapToMeetingMode: () => Promise<void>;
      restoreFromMeetingMode: () => Promise<void>;
      getPlatform: () => string;
      startWindowDrag: () => Promise<void>;
      stopWindowDrag: () => Promise<void>;
      startControlPanelDrag: () => Promise<void>;
      stopControlPanelDrag: () => Promise<void>;
      setMainWindowInteractivity: (interactive: boolean) => Promise<void>;
      setMainWindowInputRegion: (region: MainWindowInputRegion | null) => Promise<boolean>;
      onMainWindowVisibilityChanged: (callback: (visible: boolean) => void) => () => void;
      setNotificationInteractivity: (interactive: boolean) => Promise<void>;
      resizeMainWindow: (
        sizeKey:
          | "BASE"
          | "RECORDING"
          | "DICTATION_ERROR"
          | "DICTATION_ERROR_WITH_TRANSCRIPT"
          | "WITH_MENU"
          | "WITH_TOAST"
          | "EXPANDED"
          | "ASSISTANT"
      ) => Promise<{
        success: boolean;
        bounds?: Electron.Rectangle;
        message?: string;
        changed?: boolean;
      }>;
      resizeAssistantWindowToContent: (surfaceHeight: number) => Promise<{
        success: boolean;
        bounds?: Electron.Rectangle;
        message?: string;
        changed?: boolean;
      }>;
      resizeDictationErrorWindowToContent: (
        surfaceHeight: number
      ) => Promise<{ success: boolean; bounds?: Electron.Rectangle; message?: string }>;
      setAssistantPanelOpen: (open: boolean) => Promise<{ success: boolean }>;
      setAssistantPanelBusy: (busy: boolean) => Promise<{ success: boolean }>;

      // App management
      cleanupApp: () => Promise<{ success: boolean; message: string; errors?: string[] }>;
      relaunchApp: () => Promise<void>;

      // Update operations
      checkForUpdates: () => Promise<UpdateCheckResult>;
      downloadUpdate: () => Promise<UpdateResult>;
      installUpdate: () => Promise<UpdateResult>;
      getAppVersion: () => Promise<AppVersionResult>;
      getPostMigrationState: () => Promise<{ justMigrated: boolean }>;
      getOAuthProtocolRegistered: () => Promise<boolean>;
      getOAuthProtocol: () => Promise<string>;
      markBundleMigrated: () => Promise<void>;
      markBundleMigrationDismissed: () => Promise<void>;
      getUpdateStatus: () => Promise<UpdateStatusResult>;
      getUpdateInfo: () => Promise<UpdateInfoResult | null>;
      setAutoUpdatesEnabled: (enabled: boolean) => Promise<{ success: boolean }>;

      // Update event listeners
      onUpdateAvailable: (callback: (event: any, info: any) => void) => () => void;
      onUpdateNotAvailable: (callback: (event: any, info: any) => void) => () => void;
      onUpdateDownloaded: (callback: (event: any, info: any) => void) => () => void;
      onUpdateDownloadProgress: (callback: (event: any, progressObj: any) => void) => () => void;
      onUpdateError: (callback: (event: any, error: any) => void) => () => void;

      openExternal: (url: string) => Promise<{ success: boolean; error?: string }>;

      // Hotkey management
      updateHotkey: (key: string) => Promise<{ success: boolean; message: string }>;
      setHotkeyListeningMode?: (enabled: boolean) => Promise<{ success: boolean }>;
      getHotkeyModeInfo?: (hotkey?: string) => Promise<{
        isUsingGnome: boolean;
        isUsingHyprland: boolean;
        isUsingKDE: boolean;
        isUsingNativeShortcut: boolean;
        supportsPushToTalk: boolean;
        pushToTalkUnavailableReason: string | null;
        linuxInputAccessDenied?: boolean;
      }>;
      getHyprlandConfigStatus?: () => Promise<{ canWrite: boolean; path: string } | null>;

      // Wayland paste diagnostics
      getYdotoolStatus?: () => Promise<{
        isLinux: boolean;
        isWayland: boolean;
        hasYdotool: boolean;
        hasYdotoold: boolean;
        hasWtype: boolean;
        hasWlCopy: boolean;
        daemonRunning: boolean;
        hasService: boolean;
        hasUinput: boolean;
        hasUdevRule: boolean;
        hasGroup: boolean;
        isNixOS: boolean;
        isKde: boolean;
        isWlroots: boolean;
        isCosmic: boolean;
        requiresWlCopy: boolean;
      }>;

      // Globe key listener for hotkey capture (macOS only)
      onGlobeKeyPressed?: (callback: () => void) => () => void;
      onGlobeKeyReleased?: (callback: () => void) => () => void;

      // Hotkey registration events
      onHotkeyFallbackUsed?: (
        callback: (data: { original: string; fallback: string }) => void
      ) => () => void;
      onHotkeyRegistrationFailed?: (
        callback: (data: { hotkey: string; error: string; suggestions: string[] }) => void
      ) => () => void;
      onApiKeyUpdated?: (callback: (storeKey: string) => void) => () => void;
      onSettingUpdated?: (callback: (data: { key: string; value: unknown }) => void) => () => void;
      onDictationKeyActive?: (callback: (key: string) => void) => () => void;
      onLinuxPttPermissionDenied?: (callback: () => void) => () => void;

      // Settings shortcut (Cmd+, / Ctrl+,)
      onShowSettings?: (callback: () => void) => () => void;
      getPendingSettingsSection?: () => Promise<string | null>;

      // Accessibility permission events (macOS)
      markMacAccessibilityFeaturesReady?: (expectedAccountScope?: ActiveAccountScope) => void;
      onAccessibilityMissing?: (callback: () => void) => () => void;
      checkAccessibilityTrusted?: () => Promise<boolean>;

      // Gemini API key management
      getGeminiKey: () => Promise<string | null>;
      saveGeminiKey: (key: string) => Promise<void>;
      proxyGeminiTranscription?: (data: {
        audioBuffer: ArrayBuffer;
        model?: string;
        language?: string;
        keyterms?: string[];
      }) => Promise<ProxyTranscriptionResult>;

      // Groq API key management
      getGroqKey: () => Promise<string | null>;
      saveGroqKey: (key: string) => Promise<void>;
      getOpenrouterKey: () => Promise<string | null>;
      saveOpenrouterKey: (key: string) => Promise<void>;

      // xAI API key management
      getXaiKey?: () => Promise<string | null>;
      saveXaiKey?: (key: string) => Promise<void>;
      proxyXaiTranscription?: (data: {
        audioBuffer: ArrayBuffer;
        language?: string;
        keyterms?: string[];
      }) => Promise<ProxyTranscriptionResult>;

      // Mistral API key management
      getMistralKey: () => Promise<string | null>;
      saveMistralKey: (key: string) => Promise<void>;
      proxyMistralTranscription: (data: {
        audioBuffer: ArrayBuffer;
        model?: string;
        language?: string;
        contextBias?: string[];
      }) => Promise<ProxyTranscriptionResult>;

      // Corti credential management
      getCortiClientId?: () => Promise<string | null>;
      saveCortiClientId?: (key: string) => Promise<void>;
      getCortiClientSecret?: () => Promise<string | null>;
      saveCortiClientSecret?: (key: string) => Promise<void>;
      getCortiKey?: () => Promise<string | null>;
      saveCortiKey?: (key: string) => Promise<void>;
      proxyCortiTranscription?: (data: {
        audioBuffer: ArrayBuffer;
        language: string;
        environment: string;
        tenant: string;
      }) => Promise<ProxyTranscriptionResult>;
      getTinfoilKey?: () => Promise<string | null>;
      saveTinfoilKey?: (key: string) => Promise<void>;
      getTinfoilChatModels?: () => Promise<TinfoilCatalogModel[]>;
      proxyTinfoilTranscription?: (data: {
        audioBuffer: ArrayBuffer;
        language?: string;
        prompt?: string;
      }) => Promise<ProxyTranscriptionResult>;
      getDeepgramKey?: () => Promise<string | null>;
      saveDeepgramKey?: (key: string) => Promise<void>;
      getAssemblyAIKey?: () => Promise<string | null>;
      saveAssemblyAIKey?: (key: string) => Promise<void>;

      // Custom endpoint API keys
      getCustomTranscriptionKey?: () => Promise<string | null>;
      saveCustomTranscriptionKey?: (key: string) => Promise<void>;
      getCleanupCustomKey?: () => Promise<string | null>;
      saveCleanupCustomKey?: (key: string) => Promise<void>;
      getNoteFormattingCustomKey?: () => Promise<string | null>;
      saveNoteFormattingCustomKey?: (key: string) => Promise<void>;
      getTranslationCustomKey?: () => Promise<string | null>;
      saveTranslationCustomKey?: (key: string) => Promise<void>;
      getDictationAgentCustomKey?: () => Promise<string | null>;
      saveDictationAgentCustomKey?: (key: string) => Promise<void>;
      getDictationAgentVisionCustomKey?: () => Promise<string | null>;
      saveDictationAgentVisionCustomKey?: (key: string) => Promise<void>;
      getChatAgentCustomKey?: () => Promise<string | null>;
      saveChatAgentCustomKey?: (key: string) => Promise<void>;

      // Enterprise provider key persistence
      getBedrockRegion?: () => Promise<string | null>;
      saveBedrockRegion?: (value: string) => Promise<void>;
      getBedrockProfile?: () => Promise<string | null>;
      saveBedrockProfile?: (value: string) => Promise<void>;
      getBedrockAccessKeyId?: () => Promise<string | null>;
      saveBedrockAccessKeyId?: (key: string) => Promise<void>;
      getBedrockSecretAccessKey?: () => Promise<string | null>;
      saveBedrockSecretAccessKey?: (key: string) => Promise<void>;
      getBedrockSessionToken?: () => Promise<string | null>;
      saveBedrockSessionToken?: (key: string) => Promise<void>;
      getAzureEndpoint?: () => Promise<string | null>;
      saveAzureEndpoint?: (value: string) => Promise<void>;
      getAzureApiKey?: () => Promise<string | null>;
      saveAzureApiKey?: (key: string) => Promise<void>;
      getAzureDeployment?: () => Promise<string | null>;
      saveAzureDeployment?: (value: string) => Promise<void>;
      getAzureApiVersion?: () => Promise<string | null>;
      saveAzureApiVersion?: (value: string) => Promise<void>;
      getVertexProject?: () => Promise<string | null>;
      saveVertexProject?: (value: string) => Promise<void>;
      getVertexLocation?: () => Promise<string | null>;
      saveVertexLocation?: (value: string) => Promise<void>;
      getVertexApiKey?: () => Promise<string | null>;
      saveVertexApiKey?: (key: string) => Promise<void>;
      testEnterpriseConnection?: (
        provider: string,
        config: Record<string, unknown>
      ) => Promise<{
        success: boolean;
        error?: string;
        messageKey?: string;
        messageParams?: Record<string, string | number>;
        action?: string;
        actionKey?: string;
        copyCommand?: string;
        technicalDetails?: {
          status?: number;
          exceptionType?: string;
          requestId?: string;
          underlyingError?: string;
        };
      }>;
      getManagedEnterpriseConfig?: (
        accountId: string,
        workspaceId: string,
        expectedAuthGeneration: number,
        forceRefresh?: boolean
      ) => Promise<{
        success: boolean;
        status?: "network" | "current" | "cached" | "error";
        accountId?: string | null;
        workspaceId?: string | null;
        authGeneration?: number | null;
        config?: ManagedEnterpriseConfig;
        code?: string;
        error?: string;
        enforcementRequired?: boolean;
        enforcedScopes?: string[];
      }>;
      onManagedEnterpriseConfigChanged?: (
        callback: (snapshot: {
          accountId: string;
          workspaceId: string;
          authGeneration: number;
          config: ManagedEnterpriseConfig | null;
          code: string | null;
          enforcementRequired?: boolean;
          enforcedScopes?: string[];
        }) => void
      ) => () => void;
      clearManagedEnterpriseIdentity?: () => Promise<void>;
      managedTranscribe?: (data: {
        audioBuffer: ArrayBuffer;
        fileName: string;
        mimeType: string;
        language?: string;
        prompt?: string;
        managed: { provider: "azure"; context: ManagedEnterpriseRequestContext };
      }) => Promise<{ text?: string; error?: string; code?: string; messageKey?: string }>;

      // Dictation key persistence (file-based for reliable startup)
      getDictationKey?: () => Promise<string | null>;
      getActiveDictationKey?: () => Promise<string>;
      getEffectiveDefaultHotkey?: () => Promise<string>;
      saveDictationKey?: (key: string) => Promise<void>;

      // Activation mode persistence (file-based for reliable startup)
      getActivationMode?: () => Promise<"tap" | "push">;
      saveActivationMode?: (mode: "tap" | "push") => Promise<void>;

      // Debug logging
      getLogLevel?: () => Promise<string>;
      log?: (entry: {
        level: string;
        message: string;
        meta?: any;
        scope?: string;
        source?: string;
      }) => Promise<void>;
      getDebugState: () => Promise<{
        enabled: boolean;
        logPath: string | null;
        logLevel: string;
      }>;
      setDebugLogging: (enabled: boolean) => Promise<{
        success: boolean;
        enabled?: boolean;
        logPath?: string | null;
        error?: string;
      }>;
      openLogsFolder: () => Promise<{ success: boolean; error?: string }>;

      // FFmpeg availability
      checkFFmpegAvailability: () => Promise<FFmpegAvailabilityResult>;
      getAudioDiagnostics: () => Promise<AudioDiagnosticsResult>;

      // System settings helpers
      requestMicrophoneAccess?: () => Promise<{ granted: boolean }>;
      checkMicrophoneAccess?: () => Promise<{ granted: boolean; status: string }>;
      getSystemDefaultMicrophone?: (options?: { refresh?: boolean }) => Promise<{
        name: string;
        nativeId?: string;
        platform: string;
        source: "system" | "unavailable";
      }>;
      checkSystemAudioAccess?: () => Promise<SystemAudioAccessResult>;
      requestSystemAudioAccess?: () => Promise<SystemAudioAccessResult>;
      openMicrophoneSettings?: () => Promise<{ success: boolean; error?: string }>;
      openSoundInputSettings?: () => Promise<{ success: boolean; error?: string }>;
      openAccessibilitySettings?: () => Promise<{ success: boolean; error?: string }>;
      openSystemAudioSettings?: () => Promise<{ success: boolean; error?: string }>;
      openScreenRecordingSettings?: () => Promise<{ success: boolean; error?: string }>;
      openLoginItemsSettings?: () => Promise<{ success: boolean; error?: string }>;
      checkScreenRecordingAccess?: () => Promise<ScreenRecordingAccessResult>;
      requestScreenRecordingAccess?: () => Promise<ScreenRecordingAccessResult>;
      captureScreenContext?: () => Promise<ScreenContextImage | null>;
      setScreenContextEnabled?: (enabled: boolean) => Promise<{ success: boolean }>;
      toggleMediaPlayback?: () => Promise<boolean>;
      pauseMediaPlayback?: () => Promise<boolean>;
      resumeMediaPlayback?: () => Promise<boolean>;
      getModelCacheRoot?: () => Promise<string>;
      openWhisperModelsFolder?: () => Promise<{ success: boolean; error?: string }>;

      // Windows Push-to-Talk notifications
      notifyActivationModeChanged?: (mode: "tap" | "push") => void;
      notifyHotkeyChanged?: (hotkey: string) => void;
      registerMeetingHotkey?: (hotkey: string) => Promise<{ success: boolean; message?: string }>;
      notifyFloatingIconAutoHideChanged?: (enabled: boolean) => void;
      onFloatingIconAutoHideChanged?: (callback: (enabled: boolean) => void) => () => void;
      notifyStartMinimizedChanged?: (enabled: boolean) => void;
      notifyPanelStartPositionChanged?: (position: string) => void;
      getMainWindowHorizontalDirection?: () => Promise<"left" | "right">;
      onMainWindowHorizontalDirectionChanged?: (
        callback: (direction: "left" | "right") => void
      ) => () => void;
      onMainWindowWillResize?: (
        callback: (resize: {
          bounds: Electron.Rectangle;
          anchor: "bottom-left" | "bottom-right" | "center";
        }) => void
      ) => () => void;

      // Auto-start at login. requiresApproval is macOS-only: SMAppService can
      // register the login item and still leave it awaiting approval in System
      // Settings, which otherwise looks like a toggle that will not stick.
      getAutoStartEnabled?: () => Promise<{ enabled: boolean; requiresApproval: boolean }>;
      setAutoStartEnabled?: (enabled: boolean) => Promise<{ success: boolean; error?: string }>;

      // Auth
      authClearSession?: () => Promise<{
        success: boolean;
        tokenState?: AuthTokenState;
        error?: string;
      }>;
      authGetToken?: () => Promise<string | null>;
      authGetTokenState?: () => Promise<AuthTokenState>;
      authSetToken?: (
        token: string,
        expectedGeneration: number
      ) => Promise<AuthTokenMutationResult>;
      onAuthTokenStateChanged?: (
        callback: (state: { generation: number; hasToken: boolean }) => void
      ) => () => void;

      // OpenWhispr Cloud API
      cloudTranscribe?: (
        audioBuffer: ArrayBuffer,
        opts: {
          language?: string;
          prompt?: string;
          useCase?: string;
          diarization?: boolean;
          localDate?: string;
          analyticsOccurredAt?: string;
          // Why a managed-streaming user's dictation went batch (rollout metric).
          streamingFallbackReason?: string;
        } & SttDetectedLanguageFields &
          OrukeetTelemetry
      ) => Promise<
        {
          success: boolean;
          text?: string;
          warning?: string;
          clientTranscriptionId?: string;
          wordsUsed?: number;
          wordsRemaining?: number;
          limitReached?: boolean;
        } & PolicyFailureMetadata
      >;
      cancelCloudTranscription?: () => void;
      cloudReason?: (
        text: string,
        opts: {
          model?: string;
          agentName?: string;
          customDictionary?: string[];
          customPrompt?: string;
          systemPrompt?: string;
          requestPurpose?: "agent";
          promptMode?: "cleanup" | "agent";
          purpose?: CloudReasonPurpose;
          screenContext?: ScreenContextImage;
          tone?: DictationTone;
          appCategory?: ToneAppCategory;
          language?: string;
          locale?: string;
          streamingFallbackReason?: string;
        } & SttDetectedLanguageFields &
          OrukeetTelemetry
      ) => Promise<{
        success: boolean;
        text?: string;
        model?: string;
        provider?: string;
        promptMode?: string;
        matchType?: string;
        screenContextApplied?: boolean;
        error?: string;
        code?: string;
      }>;
      cancelCloudReason?: () => void;
      cloudStreamingUsage?: (
        text: string,
        audioDurationSeconds: number,
        opts?: {
          sendLogs?: boolean;
          sttProvider?: string;
          sttModel?: string;
          sttProcessingMs?: number;
          sttLanguage?: string;
          audioSizeBytes?: number;
          audioFormat?: string;
          clientTotalMs?: number;
          clientTranscriptionId?: string;
          localDate?: string;
          analyticsOccurredAt?: string;
          analyticsWordCount?: number;
          analyticsCounterVersion?: number;
        } & SttDetectedLanguageFields &
          OrukeetTelemetry
      ) => Promise<{
        success: boolean;
        wordsUsed?: number;
        wordsRemaining?: number;
        limitReached?: boolean;
        error?: string;
        code?: string;
      }>;
      cloudHealthCheck?: () => Promise<{
        ok: boolean;
        status?: number;
        code?: string;
        messageKey?: string;
      }>;
      cloudUsage?: () => Promise<
        UsageResponse & {
          success: boolean;
          error?: string;
          code?: string;
        }
      >;
      cloudCheckout?: (opts?: {
        plan?: "monthly" | "annual";
        tier?: "pro" | "business";
      }) => Promise<{
        success: boolean;
        url?: string;
        error?: string;
        code?: string;
      }>;
      cloudBillingPortal?: () => Promise<{
        success: boolean;
        url?: string;
        error?: string;
        code?: string;
      }>;
      cloudSwitchPlan?: (opts: {
        plan: "monthly" | "annual";
        tier: "pro" | "business";
      }) => Promise<{
        success: boolean;
        alreadyOnPlan?: boolean;
        error?: string;
      }>;
      cloudPreviewSwitch?: (opts: {
        plan: "monthly" | "annual";
        tier: "pro" | "business";
      }) => Promise<{
        success: boolean;
        immediateAmount?: number;
        currency?: string;
        currentPriceAmount?: number;
        currentInterval?: string;
        newPriceAmount?: number;
        newInterval?: string;
        nextBillingDate?: string;
        alreadyOnPlan?: boolean;
        error?: string;
      }>;

      // Authenticated cloud API proxy (`public: true` skips the auth requirement)
      cloudApiRequest?: (opts: {
        method?: string;
        path: string;
        body?: unknown;
        public?: boolean;
        expectedAuthGeneration?: number;
      }) => Promise<
        {
          success: boolean;
          data?: unknown;
        } & PolicyFailureMetadata
      >;

      // Cloud audio file transcription
      transcribeAudioFileCloud?: (
        filePath: string,
        options?: { requestId?: string }
      ) => Promise<
        {
          success: boolean;
          text?: string;
          warning?: string;
          failedChunks?: number;
          totalChunks?: number;
        } & PolicyFailureMetadata
      >;

      cancelUploadTranscription?: (requestId: string) => Promise<{ success: boolean }>;

      onUploadTranscriptionProgress?: (
        callback: (data: { stage: string; chunksTotal: number; chunksCompleted: number }) => void
      ) => () => void;

      // BYOK audio file transcription
      transcribeAudioFileByok?: (options: {
        filePath: string;
        apiKey: string;
        baseUrl: string;
        model: string;
        diarize?: boolean;
        timestamps?: boolean;
        provider?: string;
        language?: string;
        environment?: string;
        tenant?: string;
        transcriptionMode?: string;
        remoteTranscriptionUrl?: string;
        remoteTranscriptionModel?: string;
        managed?: {
          kind: "managed";
          provider: "azure";
          deployment: string;
          context: ManagedEnterpriseRequestContext;
        };
      }) => Promise<{
        success: boolean;
        text?: string;
        error?: string;
        diarized?: boolean;
        segments?: Array<{ text: string; start: number; end: number; speaker?: string }>;
      }>;

      // Usage limit events
      notifyLimitReached?: (data: { wordsUsed: number; limit: number }) => void;
      onLimitReached?: (
        callback: (data: { wordsUsed: number; limit: number }) => void
      ) => () => void;

      // Workspace invitation deep link
      onWorkspaceInvitationToken?: (callback: (token: string) => void) => () => void;
      getPendingInvitationToken?: () => Promise<string | null>;

      // AssemblyAI Streaming
      assemblyAiStreamingWarmup?: (options?: { sampleRate?: number; language?: string }) => Promise<
        {
          success: boolean;
          alreadyWarm?: boolean;
        } & PolicyFailureMetadata
      >;
      assemblyAiStreamingStart?: (options?: { sampleRate?: number; language?: string }) => Promise<
        {
          success: boolean;
          usedWarmConnection?: boolean;
        } & PolicyFailureMetadata
      >;
      assemblyAiStreamingSend?: (audioBuffer: ArrayBuffer) => void;
      assemblyAiStreamingForceEndpoint?: () => void;
      assemblyAiStreamingStop?: () => Promise<{
        success: boolean;
        text?: string;
        error?: string;
      }>;
      assemblyAiStreamingStatus?: () => Promise<{
        isConnected: boolean;
        sessionId: string | null;
      }>;
      onAssemblyAiPartialTranscript?: (callback: (text: string) => void) => () => void;
      onAssemblyAiFinalTranscript?: (callback: (text: string) => void) => () => void;
      onAssemblyAiError?: (callback: (error: string) => void) => () => void;
      onAssemblyAiSessionEnd?: (
        callback: (data: { audioDuration?: number; text?: string }) => void
      ) => () => void;

      // Referral stats
      getReferralStats?: () => Promise<{
        referralCode: string;
        referralLink: string;
        totalReferrals: number;
        completedReferrals: number;
        pendingReferrals: number;
        totalMonthsEarned: number;
        referrals: Array<{
          id: string;
          email: string;
          name: string;
          status: "pending" | "completed" | "rewarded";
          created_at: string;
          first_payment_at: string | null;
          words_used: number;
        }>;
      }>;

      sendReferralInvite?: (email: string) => Promise<{
        success: boolean;
        invite: {
          id: string;
          recipientEmail: string;
          status: "sent" | "failed" | "opened" | "converted";
          sentAt: string;
        };
      }>;

      getReferralInvites?: () => Promise<{
        invites: Array<{
          id: string;
          recipientEmail: string;
          status: "sent" | "failed" | "opened" | "converted";
          sentAt: string;
          openedAt?: string;
          convertedAt?: string;
        }>;
      }>;

      // Agent Mode
      updateVoiceAgentHotkey?: (hotkey: string) => Promise<{ success: boolean; message?: string }>;
      getVoiceAgentKey?: () => Promise<string>;
      updateTranslationHotkey?: (hotkey: string) => Promise<{ success: boolean; message?: string }>;
      getTranslationKey?: () => Promise<string>;
      createAgentConversation?: (
        title: string,
        noteId?: number | null,
        spaceId?: number | null,
        folderId?: number | null
      ) => Promise<{
        id: number;
        title: string;
        note_id?: number | null;
        space_id?: number | null;
        folder_id?: number | null;
        created_at: string;
        updated_at: string;
      } | null>;
      getConversationsForNote?: (
        noteId: number,
        limit?: number
      ) => Promise<
        Array<{
          id: number;
          title: string;
          created_at: string;
          updated_at: string;
          message_count: number;
        }>
      >;
      getConversationsForContainer?: (
        spaceId: number,
        folderId?: number | null,
        limit?: number
      ) => Promise<
        Array<{
          id: number;
          title: string;
          created_at: string;
          updated_at: string;
          message_count: number;
        }>
      >;
      getAgentConversations?: (limit?: number) => Promise<
        Array<{
          id: number;
          title: string;
          archived_at?: string;
          cloud_id?: string;
          client_conversation_id?: string;
          created_at: string;
          updated_at: string;
        }>
      >;
      getAgentConversation?: (id: number) => Promise<{
        id: number;
        title: string;
        archived_at?: string;
        cloud_id?: string | null;
        client_conversation_id?: string | null;
        created_at: string;
        updated_at: string;
        messages: Array<{
          id: number;
          conversation_id: number;
          role: "user" | "assistant" | "system";
          content: string;
          metadata?: string;
          created_at: string;
        }>;
      } | null>;
      deleteAgentConversation?: (id: number) => Promise<{ success: boolean }>;
      updateAgentConversationTitle?: (id: number, title: string) => Promise<{ success: boolean }>;
      addAgentMessage?: (
        conversationId: number,
        role: "user" | "assistant" | "system",
        content: string,
        metadata?: Record<string, unknown>
      ) => Promise<{
        id: number;
        conversation_id: number;
        role: string;
        content: string;
        metadata?: string;
        created_at: string;
      } | null>;
      getAgentMessages?: (conversationId: number) => Promise<
        Array<{
          id: number;
          conversation_id: number;
          role: "user" | "assistant" | "system";
          content: string;
          metadata?: string;
          created_at: string;
        }>
      >;
      getAgentConversationsWithPreview?: (
        limit?: number,
        offset?: number,
        includeArchived?: boolean
      ) => Promise<ConversationPreview[]>;
      searchAgentConversations?: (query: string, limit?: number) => Promise<ConversationPreview[]>;
      archiveAgentConversation?: (id: number) => Promise<{ success: boolean }>;
      unarchiveAgentConversation?: (id: number) => Promise<{ success: boolean }>;
      updateAgentConversationCloudId?: (
        id: number,
        cloudId: string
      ) => Promise<{ success: boolean }>;
      semanticSearchConversations?: (
        query: string,
        limit?: number
      ) => Promise<ConversationPreview[]>;

      // Deepgram Streaming
      deepgramStreamingWarmup?: (options?: { sampleRate?: number; language?: string }) => Promise<{
        success: boolean;
        alreadyWarm?: boolean;
        error?: string;
        code?: string;
      }>;
      deepgramStreamingStart?: (options?: {
        sampleRate?: number;
        language?: string;
        forceNew?: boolean;
      }) => Promise<
        {
          success: boolean;
          usedWarmConnection?: boolean;
        } & PolicyFailureMetadata
      >;
      deepgramStreamingSend?: (audioBuffer: ArrayBuffer) => void;
      deepgramStreamingFinalize?: () => void;
      deepgramStreamingStop?: () => Promise<{
        success: boolean;
        text?: string;
        error?: string;
      }>;
      deepgramStreamingStatus?: () => Promise<{
        isConnected: boolean;
        sessionId: string | null;
      }>;
      onDeepgramPartialTranscript?: (callback: (text: string) => void) => () => void;
      onDeepgramFinalTranscript?: (callback: (text: string) => void) => () => void;
      onDeepgramError?: (callback: (error: string) => void) => () => void;
      onDeepgramSessionEnd?: (
        callback: (data: { audioDuration?: number; text?: string }) => void
      ) => () => void;

      // Gemini Live Streaming
      geminiStreamingWarmup?: (
        options?: DictationRealtimeSessionOptions
      ) => Promise<
        { success: boolean; alreadyWarm?: boolean; error?: string } & PolicyFailureMetadata
      >;
      geminiStreamingStart?: (
        options?: DictationRealtimeSessionOptions & { forceNew?: boolean }
      ) => Promise<
        { success: boolean; usedWarmConnection?: boolean; error?: string } & PolicyFailureMetadata
      >;
      geminiStreamingSend?: (audioBuffer: ArrayBuffer) => void;
      geminiStreamingFinalize?: () => void;
      geminiStreamingStop?: () => Promise<{
        success: boolean;
        text?: string;
        model?: string;
        audioBytesSent?: number;
        error?: string;
      }>;
      geminiStreamingStatus?: () => Promise<{ isConnected: boolean; isConnecting: boolean }>;
      onGeminiPartialTranscript?: (callback: (text: string) => void) => () => void;
      onGeminiFinalTranscript?: (callback: (text: string) => void) => () => void;
      onGeminiError?: (callback: (error: string) => void) => () => void;
      onGeminiSessionEnd?: (callback: (data: { text?: string }) => void) => () => void;

      // Corti streaming (BYOK)
      cortiStreamingWarmup?: (options?: {
        environment?: string;
        tenant?: string;
        language?: string;
        keyterms?: string[];
      }) => Promise<{ success: boolean } & PolicyFailureMetadata>;
      cortiStreamingStart?: (options?: {
        environment?: string;
        tenant?: string;
        language?: string;
        keyterms?: string[];
      }) => Promise<{ success: boolean } & PolicyFailureMetadata>;
      cortiStreamingSend?: (audioBuffer: ArrayBuffer) => void;
      cortiStreamingFinalize?: () => void;
      cortiStreamingStop?: () => Promise<{
        success: boolean;
        text?: string;
        model?: string;
        audioBytesSent?: number;
        error?: string;
      }>;
      cortiStreamingStatus?: () => Promise<{ isConnected: boolean; sessionId: string | null }>;
      onCortiPartialTranscript?: (callback: (text: string) => void) => () => void;
      onCortiFinalTranscript?: (callback: (text: string) => void) => () => void;
      onCortiError?: (callback: (error: string) => void) => () => void;
      onCortiSessionEnd?: (callback: (data: { text?: string }) => void) => () => void;

      // Agent cloud streaming (event-based)
      startAgentStream?: (
        requestId: string,
        messages: Array<{ role: string; content: string | Array<unknown> }>,
        opts?: {
          systemPrompt?: string;
          tools?: Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
          screenContext?: { data: string; mediaType: string };
        }
      ) => void;
      cancelAgentStream?: (requestId: string) => void;
      onAgentStreamChunk?: (
        callback: (payload: {
          requestId: string;
          chunk: {
            type: "content" | "tool_call" | "done";
            text?: string;
            id?: string;
            name?: string;
            arguments?: string;
            finishReason?: string;
          };
        }) => void
      ) => () => void;
      onAgentStreamError?: (
        callback: (payload: PolicyFailureMetadata & { requestId: string; error: string }) => void
      ) => () => void;
      onAgentStreamEnd?: (callback: (payload: { requestId: string }) => void) => () => void;

      productHelp: (
        id: string,
        input: { topic: string; page?: string }
      ) => Promise<import("../services/help/productHelp").HelpResult>;
      cancelProductHelp: (id: string) => void;
      productHelpBasics: () => Promise<import("../services/help/productHelp").HelpBasics>;

      // Agent cloud tools
      agentOpenNote?: (noteId: number) => Promise<{ success: boolean; error?: string }>;
      agentWebSearch?: (
        query: string,
        numResults?: number
      ) => Promise<
        {
          success: boolean;
          results?: Array<{
            title: string;
            url: string;
            text: string;
            publishedDate?: string;
          }>;
        } & PolicyFailureMetadata
      >;

      // Google Calendar
      gcalStartOAuth?: () => Promise<{ success: boolean; email?: string; error?: string }>;
      gcalDisconnect?: (email?: string) => Promise<{ success: boolean; error?: string }>;
      gcalGetConnectionStatus?: () => Promise<{
        connected: boolean;
        accounts: Array<{ email: string }>;
        email: string | null;
      }>;
      gcalGetCalendars?: () => Promise<{ success: boolean; calendars: any[] }>;
      gcalSetCalendarSelection?: (
        calendarId: string,
        isSelected: boolean
      ) => Promise<{ success: boolean; error?: string }>;
      gcalSetPrimaryOnly?: (value: boolean) => Promise<{ success: boolean; error?: string }>;
      gcalSyncEvents?: () => Promise<{ success: boolean; error?: string }>;
      gcalGetUpcomingEvents?: (
        windowMinutes?: number
      ) => Promise<{ success: boolean; events: any[] }>;
      connectorStatus?: () => Promise<ConnectorStatus[]>;
      connectorPrepare?: (
        connectorId: string,
        action: string,
        args: Record<string, unknown>
      ) => Promise<ConnectorPrepareResult>;
      /** Reads provider data for the model (an issue search); never writes. */
      connectorQuery?: (
        connectorId: string,
        action: string,
        args: Record<string, unknown>
      ) => Promise<ConnectorQueryResult>;
      connectorCommit?: (actionId: string, edits: ConnectorEdits) => Promise<ConnectorCommitResult>;
      /** Cancels a pending approval, or a direct run (by its runId) still waiting on policy. */
      connectorCancel?: (
        actionId: string,
        reason: ConnectorCancelReason
      ) => Promise<{ cancelled: boolean }>;
      connectorRunDirect?: (
        connectorId: string,
        action: string,
        args: Record<string, unknown>,
        runId?: string
      ) => Promise<ConnectorDirectResult>;
      connectorRecentActions?: (
        connectorId: string,
        limit?: number
      ) => Promise<ConnectorActionRecord[]>;
      connectorFindContacts?: (
        query: string
      ) => Promise<{ contacts: ContactMatch[]; hasMore?: boolean; unavailableReason?: string }>;
      /**
       * A note's participants, plus its calendar event's organizer, minus the
       * user and rooms (main applies find_contact's exclusions).
       */
      connectorNoteAttendees?: (
        request: NoteAttendeesRequest
      ) => Promise<{ attendees: NoteAttendee[]; unavailableReason?: string }>;
      connectorConnect?: (connectorId: string) => Promise<ConnectorConnectResult>;
      /**
       * Stops this connector's connect in progress, whichever account started it
       * (including one still waiting on policy); the connect ends as oauth_cancelled.
       */
      connectorCancelConnect?: (connectorId: string) => Promise<ConnectorCancelConnectResult>;
      connectorDisconnect?: (connectorId: string) => Promise<ConnectorDisconnectResult>;
      onConnectorStatusChanged?: (callback: (statuses: ConnectorStatus[]) => void) => () => void;
      onConnectorConnectProgress?: (
        callback: (progress: ConnectorConnectProgress) => void
      ) => () => void;
      calendarGetAvailability?: (
        request: CalendarAvailabilityRequest
      ) => Promise<
        | { success: true; availability: CalendarAvailabilityResult }
        | { success: false; error: string }
      >;
      gcalGetEvent?: (eventId: string) => Promise<{
        success: boolean;
        event: CalendarEvent | null;
      }>;
      calendarGetLinkableEvents?: () => Promise<{
        success: boolean;
        events: LinkableCalendarEvent[];
      }>;

      // Contacts
      searchContacts: (query: string) => Promise<{
        success: boolean;
        contacts: Array<{ email: string; display_name: string | null }>;
      }>;
      upsertContact: (contact: {
        email: string;
        displayName?: string | null;
      }) => Promise<{ success: boolean }>;
      getMD5Hash: (text: string) => Promise<string>;

      // Meeting transcription (streaming, dual-channel)
      meetingTranscriptionPrepare?: (options: {
        provider?: string;
        model?: string;
        language?: string;
      }) => Promise<{ success: boolean; alreadyPrepared?: boolean } & PolicyFailureMetadata>;
      meetingTranscriptionStart?: (options: {
        provider?: string;
        model?: string;
        language?: string;
        noteId?: number | null;
        sessionId: string;
        autoEndEligible: boolean;
        aecEnabled?: boolean;
        speakerIndexBase?: number;
      }) => Promise<
        {
          success: boolean;
          sessionId?: string;
          error?: string;
          systemAudioMode?: SystemAudioMode;
          systemAudioStrategy?: SystemAudioStrategy;
          oneOnOneAttendee?: { displayName: string; email: string | null } | null;
          speakerIndexBase?: number;
        } & PolicyFailureMetadata
      >;
      meetingTranscriptionSend?: (buffer: ArrayBuffer, source: "mic" | "system") => void;
      meetingTranscriptionSetSystemAudioAvailable?: (
        sessionId: string,
        available: boolean
      ) => Promise<{ success: boolean; reason?: "stale-session" }>;
      meetingTranscriptionStop?: (expectedSessionId?: string) => Promise<{
        success: boolean;
        transcript?: string;
        diarizationSessionId?: string;
        error?: string;
        reason?: "stale-session";
      }>;
      meetingTranscriptionCancel?: () => Promise<{
        success: boolean;
        reason?: "recording-active";
      }>;
      onMeetingTranscriptionSegment?: (
        callback: (data: {
          text: string;
          source: "mic" | "system";
          type: "partial" | "final" | "retract";
          timestamp?: number;
        }) => void
      ) => () => void;
      onMeetingSpeakerIdentified?: (
        callback: (data: {
          speakerId: string;
          displayName?: string | null;
          startTime: number;
          endTime: number;
        }) => void
      ) => () => void;
      onMeetingSpeakersMerged?: (
        callback: (
          merges: Array<{
            keep: string;
            remove: string;
            displayName?: string | null;
            similarity: number;
          }>
        ) => void
      ) => () => void;
      onMeetingSessionSpeakerConfigUpdated?: (
        callback: (config: { enabled: boolean; expectedCount: number }) => void
      ) => () => void;
      onMeetingTranscriptionError?: (callback: (error: string) => void) => () => void;
      onMeetingTranscriptionFatalError?: (callback: (error: string) => void) => () => void;
      onMeetingSystemAudioSilent?: (
        callback: (data: { systemAudioStrategy: SystemAudioStrategy }) => void
      ) => () => void;
      onMeetingSystemAudioDegraded?: (callback: () => void) => () => void;
      onMeetingSystemAudioInterrupted?: (
        callback: (data: MeetingSystemAudioInterruption) => void
      ) => () => void;
      onMeetingSystemAudioResumed?: (callback: () => void) => () => void;

      // Speaker diarization
      downloadDiarizationModels?: () => Promise<{ success: boolean; error?: string }>;
      getDiarizationModelStatus?: () => Promise<{
        available: boolean;
        modelsDownloaded: boolean;
      }>;
      deleteDiarizationModels?: () => Promise<{ success: boolean }>;
      cancelDiarizationDownload?: () => Promise<{
        success: boolean;
        message?: string;
        error?: string;
      }>;
      mergeSpeakerText?: (
        segments: Array<{ start: number; end: number; speaker: string }>,
        text: string,
        duration: number
      ) => Promise<{
        success: boolean;
        text?: string;
        segments?: Array<{ text: string; start: number; end: number; speaker: string }>;
        error?: string;
      }>;
      diarizeAudioFile?: (
        filePath: string,
        options?: { numSpeakers?: number; threshold?: number; requestId?: string }
      ) => Promise<{
        success: boolean;
        segments?: Array<{ start: number; end: number; speaker: string }>;
        durationSeconds?: number;
        error?: string;
        code?: string;
      }>;
      onDiarizationDownloadProgress?: (callback: (data: any) => void) => () => void;
      onMeetingDiarizationComplete?: (
        callback: (data: {
          sessionId?: string;
          noteId?: number | null;
          segments: Array<{
            id: string;
            text: string;
            source: "mic" | "system";
            timestamp?: number;
            speaker?: string;
            speakerName?: string;
            speakerIsPlaceholder?: boolean;
            suggestedName?: string;
            suggestedProfileId?: number;
            speakerStatus?: "provisional" | "confirmed" | "suggested" | "locked";
            speakerLocked?: boolean;
            speakerLockSource?: "user" | "diarization" | "suggestion";
          }>;
          speakerEmbeddings?: Record<string, number[]> | null;
          removedSegments?: RemovedTranscriptSegment[];
        }) => void
      ) => () => void;

      // Speaker name mapping
      getSpeakerMappings?: (noteId: number) => Promise<
        Array<{
          note_id: number;
          speaker_id: string;
          profile_id: number | null;
          display_name: string;
        }>
      >;
      setSpeakerMapping?: (
        noteId: number,
        speakerId: string,
        displayName: string,
        email?: string | null,
        profileId?: number | null
      ) => Promise<{ success: boolean; profileId: number | null }>;
      removeSpeakerMapping?: (noteId: number, speakerId: string) => Promise<{ success: boolean }>;
      getSpeakerProfiles?: () => Promise<
        Array<{
          id: number;
          display_name: string;
          email: string | null;
          sample_count: number;
          created_at: string;
          updated_at: string;
        }>
      >;
      attachSpeakerEmail?: (
        profileId: number,
        email: string | null
      ) => Promise<{
        success: boolean;
        error?: string;
        profile?: {
          id: number;
          display_name: string;
          email: string | null;
          sample_count: number;
        };
      }>;
      saveNoteSpeakerEmbeddings?: (
        noteId: number,
        embeddings: Record<string, number[]>
      ) => Promise<{ success: boolean }>;

      // Dictation realtime streaming
      dictationRealtimeWarmup?: (
        options: DictationRealtimeSessionOptions
      ) => Promise<{ success: boolean } & PolicyFailureMetadata>;
      dictationRealtimeStart?: (
        options: DictationRealtimeSessionOptions
      ) => Promise<{ success: boolean } & PolicyFailureMetadata>;
      dictationRealtimeSend?: (buffer: ArrayBuffer) => void;
      dictationRealtimeFinalize?: () => Promise<
        {
          success: boolean;
          text?: string;
          error?: string;
        } & Partial<DictationLanguageMetadata>
      >;
      dictationRealtimeStop?: () => Promise<{ success: boolean; text: string }>;
      onDictationRealtimePartial?: (callback: (text: string) => void) => () => void;
      onDictationRealtimeFinal?: (callback: (text: string) => void) => () => void;
      onDictationRealtimeLanguage?: (
        callback: (metadata: DictationLanguageMetadata) => void
      ) => () => void;
      onDictationRealtimeError?: (callback: (error: string) => void) => () => void;
      onDictationRealtimeSessionEnd?: (callback: (data: { text: string }) => void) => () => void;

      // Google Calendar event listeners
      onGcalConnectionChanged?: (callback: (data: any) => void) => () => void;
      onGcalEventsSynced?: (callback: (data: any) => void) => () => void;

      // Microsoft Calendar
      mcalStartOAuth?: () => Promise<{
        success: boolean;
        email?: string;
        tenantId?: string | null;
        error?: string;
      }>;
      mcalDisconnect?: (email?: string) => Promise<{ success: boolean; error?: string }>;
      mcalGetConnectionStatus?: () => Promise<{
        connected: boolean;
        accounts: MicrosoftCalendarAccount[];
      }>;
      mcalSetPrimaryOnly?: (value: boolean) => Promise<{ success: boolean; error?: string }>;
      onMcalConnectionChanged?: (callback: (data: any) => void) => () => void;
      onMcalEventsSynced?: (callback: (data: any) => void) => () => void;

      // Apple Calendar (macOS EventKit)
      acalConnect?: () => Promise<{ success: boolean; reason?: string; error?: string }>;
      acalDisconnect?: () => Promise<{ success: boolean; error?: string }>;
      acalGetConnectionStatus?: () => Promise<{ connected: boolean; sourceNames: string[] }>;
      openCalendarPrivacySettings?: () => Promise<{ success: boolean; error?: string }>;
      onAcalConnectionChanged?: (
        callback: (data: { connected: boolean; sourceNames: string[] }) => void
      ) => () => void;
      onAcalEventsSynced?: (callback: (data: any) => void) => () => void;

      syncNotificationPreferences?: (prefs: {
        notificationsEnabled: boolean;
        notifyMeetingDetection: boolean;
        notifyCalendarReminders: boolean;
        meetingProcessDetection: boolean;
      }) => Promise<{ success: boolean }>;
      setSpeakerDiarizationEnabled?: (
        enabled: boolean
      ) => Promise<{ success: boolean; error?: string }>;
      setMeetingSessionSpeakerConfig?: (config: {
        enabled: boolean;
        expectedCount: number;
        countIsExplicit?: boolean;
      }) => Promise<{ success: boolean; error?: string }>;
      getWhisperVadConfig?: () => Promise<{
        success: boolean;
        config?: {
          dictationSileroEnabled: boolean;
          noteRecordingSileroEnabled: boolean;
          meetingSileroEnabled: boolean;
          threshold: number;
          minSpeechDurationMs: number;
          minSilenceDurationMs: number;
          maxSpeechDurationS: number;
          speechPadMs: number;
          samplesOverlap: number;
        };
        error?: string;
      }>;
      setWhisperVadConfig?: (config: {
        dictationSileroEnabled?: boolean;
        noteRecordingSileroEnabled?: boolean;
        meetingSileroEnabled?: boolean;
        threshold?: number;
        minSpeechDurationMs?: number;
        minSilenceDurationMs?: number;
        maxSpeechDurationS?: number;
        speechPadMs?: number;
        samplesOverlap?: number;
      }) => Promise<{ success: boolean; config?: Record<string, unknown>; error?: string }>;
      onMeetingNotificationData?: (callback: (data: MeetingNotificationData) => void) => () => void;
      onMeetingAutoEndRequested?: (
        callback: (request: MeetingAutoEndRequest) => void
      ) => () => void;
      getMeetingNotificationDestination: () => Promise<MeetingResult<MeetingDestinationContext>>;
      selectMeetingNotificationFolder: (
        folder: MeetingFolderRef
      ) => Promise<MeetingResult<MeetingDestinationContext>>;
      createMeetingNotificationFolder: (request: {
        requestId: string;
        name: string;
        spaceId: number;
      }) => Promise<MeetingResult<MeetingDestinationContext & { createdFolder: MeetingFolderRef }>>;
      onMeetingNotificationFolderCreated: (
        callback: (hint: { folderId: number }) => void
      ) => () => void;
      setMeetingNotificationSurface: (
        state: MeetingSurfaceState
      ) => Promise<MeetingResult<{ width: number; height: number; maxHeight: number }>>;
      onMeetingNotificationSurfaceClosed: (
        callback: (data: { revision: number }) => void
      ) => () => void;
      onMeetingNotificationSurfaceResized: (
        callback: (data: { revision: number }) => void
      ) => () => void;
      getMeetingNotificationData?: () => Promise<MeetingNotificationData | null>;
      meetingNotificationReady?: () => Promise<void>;
      meetingNotificationRespond?: (
        detectionId: string,
        action: string,
        options?: {
          existingNote?: Pick<MeetingExistingNote, "noteId" | "spaceId" | "folderId">;
        }
      ) => Promise<MeetingResult<null>>;
      confirmMeetingNoteNavigation: (
        navigationId: string,
        status?: "ready" | "cancel"
      ) => Promise<MeetingResult<NoteItem>>;
      joinCalendarMeeting?: (eventId: string) => Promise<{ success: boolean }>;
      startManualMeeting?: () => Promise<void>;
      getPendingMeetingNoteNavigation?: () => Promise<{
        navigationId?: string;
        spaceId?: number;
        noteId: number;
        folderId: number | null;
        event: any;
        trigger?: "hotkey" | "manual" | "calendar-join";
      } | null>;
      onMeetingNoteNavigationPending?: (callback: () => void) => () => void;
      getPendingNoteNavigation?: () => Promise<{
        noteId: number;
        folderId: number | null;
      } | null>;
      onNoteNavigationPending?: (callback: () => void) => () => void;
      onPreviewText?: (callback: (text: string) => void) => () => void;
      onPreviewAppend?: (callback: (text: string) => void) => () => void;
      onPreviewHold?: (callback: (payload: { showCleanup: boolean }) => void) => () => void;
      onPreviewResult?: (callback: (payload: { text: string }) => void) => () => void;
      onPreviewHide?: (callback: () => void) => () => void;
      startDictationPreview?: (opts: {
        provider: string;
        model: string;
        language?: string;
        display?: boolean;
      }) => Promise<{ success: boolean }>;
      stopDictationPreview?: (opts?: {
        showCleanup?: boolean;
        flushed?: boolean;
      }) => Promise<{ success: boolean; streamed?: boolean; text?: string }>;
      dismissDictationPreview?: () => Promise<{ success: boolean }>;
      updateDictationPreview?: (text: string) => Promise<{ success: boolean }>;
      completeDictationPreview?: (payload: { text?: string }) => Promise<{ success: boolean }>;
      hideDictationPreview?: () => Promise<{ success: boolean }>;
      sendDictationPreviewAudio?: (data: ArrayBuffer) => void;

      // Sync operations
      getPendingNotes?: (spaceKind?: "private" | "team") => Promise<NoteItem[]>;
      getPendingNoteDeletes?: () => Promise<NoteItem[]>;
      getNoteByClientId?: (clientNoteId: string) => Promise<NoteItem | null>;
      upsertNoteFromCloud?: (
        cloudNote: Record<string, unknown>,
        localFolderId: number | null,
        localSpaceId?: number | null
      ) => Promise<NoteItem | null>;
      acknowledgeNoteCreate?: (
        id: number,
        snapshot: NoteCreateSnapshot,
        cloudId: string,
        cloudUpdatedAt?: string | null,
        ownerUserId?: string | null,
        options?: NoteCreateAckWriteOptions
      ) => Promise<NoteCreateAckResult>;
      markNoteSyncedIfUnchanged?: (
        id: number,
        snapshot: NoteUpdateSnapshot,
        expectedCloudId: string,
        cloudUpdatedAt?: string | null,
        ownerUserId?: string | null,
        cloudRevision?: number | null,
        cloudNote?: NoteCloudText | null
      ) => Promise<NoteUpdateAckResult>;
      setNoteCloudBase?: (
        id: number,
        cloudUpdatedAt: string | null,
        cloudRevision?: number | null,
        options?: NoteCloudBaseOptions
      ) => Promise<{ success: boolean; note?: NoteItem }>;
      setNoteOwnerFromCloud?: (id: number, ownerUserId: string) => Promise<void>;
      countTeamNotesMissingOwner?: () => Promise<number>;
      countNotesMissingRevision?: (spaceKind?: "private" | "team") => Promise<number>;
      markNoteSyncError?: (id: number) => Promise<void>;
      restoreNoteAfterDeniedDelete?: (id: number) => Promise<{ success: boolean; id: number }>;
      hardDeleteNote?: (id: number) => Promise<void>;

      getPendingFolders?: (spaceKind?: "private" | "team") => Promise<FolderItem[]>;
      getFolderByClientId?: (clientFolderId: string) => Promise<FolderItem | null>;
      upsertFolderFromCloud?: (
        cloudFolder: Record<string, unknown>,
        localSpaceId?: number | null
      ) => Promise<FolderItem>;
      acknowledgeFolderCreate?: (
        id: number,
        snapshot: FolderPushSnapshot,
        expectedCloudId: string | null,
        responseClientFolderId: string,
        cloudId: string,
        cloudUpdatedAt?: string | null
      ) => Promise<FolderAckResult>;
      markFolderSyncedIfUnchanged?: (
        id: number,
        snapshot: FolderPushSnapshot,
        expectedCloudId: string
      ) => Promise<FolderAckResult>;
      getFolderIdMap?: () => Promise<FolderItem[]>;
      getPendingFolderDeletes?: () => Promise<FolderItem[]>;
      restoreFolderAfterDeniedDelete?: (id: number) => Promise<{
        success: boolean;
        id: number;
        folder?: FolderItem;
        notes?: NoteItem[];
        conversationIds?: number[];
        reason?: "name-taken";
        error?: string;
      }>;
      hardDeleteFolder?: (id: number) => Promise<{ success: boolean; id: number }>;
      relocateRevokedFolder?: (
        id: number,
        privateSpaceId: number,
        preserveFolder?: boolean
      ) => Promise<{
        success: boolean;
        folder?: FolderItem | null;
        folderName?: string;
        relocatedNotes?: NoteItem[];
        deletedNoteIds?: number[];
        error?: string;
      }>;

      getPendingConversations?: () => Promise<ConversationPreview[]>;
      getPendingConversationDeletes?: () => Promise<ConversationPreview[]>;
      getConversationByClientId?: (clientId: string) => Promise<ConversationPreview | null>;
      upsertConversationFromCloud?: (
        cloudConv: Record<string, unknown>,
        messages: Array<Record<string, unknown>>
      ) => Promise<void>;
      acknowledgeConversationCreate?: (
        id: number,
        snapshot: ConversationCreateSnapshot,
        cloudId: string
      ) => Promise<ConversationCreateAckResult | undefined>;
      markConversationSynced?: (
        id: number,
        cloudId: string
      ) => Promise<{ success: boolean } | undefined>;
      hardDeleteConversation?: (id: number) => Promise<void>;

      getPendingTranscriptions?: () => Promise<TranscriptionItem[]>;
      getTranscriptionByClientId?: (clientId: string) => Promise<TranscriptionItem | null>;
      upsertTranscriptionFromCloud?: (
        cloudTranscription: Record<string, unknown>
      ) => Promise<TranscriptionItem>;
      markTranscriptionSynced?: (id: number, cloudId: string) => Promise<void>;
      getPendingTranscriptionDeletes?: () => Promise<TranscriptionItem[]>;
      hardDeleteTranscription?: (id: number) => Promise<{ success: boolean; id: number }>;

      getPendingDictionary?: () => Promise<DictionaryEntryItem[]>;
      getPendingDictionaryDeletes?: () => Promise<DictionaryEntryItem[]>;
      getDictionaryByClientId?: (clientDictId: string) => Promise<DictionaryEntryItem | null>;
      upsertDictionaryFromCloud?: (
        cloudEntry: Record<string, unknown>
      ) => Promise<DictionaryEntryItem | null>;
      markDictionarySynced?: (
        id: number,
        cloudId: string,
        serverUpdatedAt?: string,
        expectedWord?: string,
        expectedSource?: DictionaryEntryItem["source"],
        serverSource?: DictionaryEntryItem["source"]
      ) => Promise<{ success: boolean; changes: number }>;
      hardDeleteDictionary?: (id: number) => Promise<{ success: boolean; id: number }>;
      clearDictionaryCloudId?: (id: number) => Promise<{ success: boolean }>;
      broadcastDictionaryUpdated?: () => Promise<{ success: boolean }>;

      getPendingSnippets?: () => Promise<SnippetEntryItem[]>;
      getPendingSnippetDeletes?: () => Promise<SnippetEntryItem[]>;
      getSnippetForCloudMerge?: (
        cloudEntry: Record<string, unknown>
      ) => Promise<SnippetEntryItem | null>;
      upsertSnippetFromCloud?: (
        cloudEntry: Record<string, unknown>
      ) => Promise<SnippetEntryItem | null>;
      markSnippetSynced?: (
        id: number,
        cloudId: string,
        serverUpdatedAt?: string,
        expectedTrigger?: string,
        expectedReplacement?: string
      ) => Promise<{ success: boolean; changes: number }>;
      hardDeleteSnippet?: (id: number) => Promise<{ success: boolean; id: number }>;
      clearSnippetCloudId?: (id: number) => Promise<{ success: boolean }>;
      broadcastSnippetsUpdated?: () => Promise<{ success: boolean }>;
    };

    api?: {
      sendDebugLog: (message: string) => void;
    };
  }
}