@athenaintel/react 0.57.1 → 0.59.0

package/dist/agent-runtime/src/dictation-record.d.ts

@@ -0,0 +1,279 @@
+export type DictationSurface = 'desktop' | 'web' | 'mobile';
+export type DictationClientPlatform = 'macos' | 'windows' | 'linux' | 'ios' | 'android' | 'web';
+/** How a dictation ended. Agora takes any lowercase snake_case code; these are the shared ones. */
+export declare const DictationOutcome: {
+    readonly INSERTED: 'inserted';
+    readonly COPIED: 'copied';
+    readonly COMMENT_DRAFTED: 'comment_drafted';
+    readonly INSERT_FAILED: 'insert_failed';
+    readonly NOT_INSERTED: 'not_inserted';
+    readonly CANCELLED: 'cancelled';
+    readonly RESTORED: 'restored';
+    readonly EMPTY: 'empty';
+    readonly FAILED: 'failed';
+};
+export type DictationOutcome = (typeof DictationOutcome)[keyof typeof DictationOutcome];
+export declare const DictationMode: {
+    readonly PUSH_TO_TALK: 'push_to_talk';
+    readonly HANDS_FREE: 'hands_free';
+};
+export type DictationMode = (typeof DictationMode)[keyof typeof DictationMode];
+/** The moments a dictation's latency is measured between. */
+export declare const DictationMark: {
+    readonly MIC_STARTED: 'mic_started';
+    readonly STREAM_OPEN: 'stream_open';
+    readonly FIRST_RESULT: 'first_result';
+    readonly STOPPED: 'stopped';
+    readonly FINALIZED: 'finalized';
+    readonly DELIVERED: 'delivered';
+};
+export type DictationMark = (typeof DictationMark)[keyof typeof DictationMark];
+/** One hour of audio: what one tab holds for one dictation (~115 MB at 16 kHz). */
+export declare const MAX_CAPTURED_AUDIO_SECONDS: number;
+/** Agora's ceiling on `text` and `raw_transcript`. */
+export declare const MAX_DICTATION_TEXT_CHARS = 1000000;
+/** A v4 UUID: agora keys a person's dictation by it, so a retry lands on the same record. */
+export declare function mintDictationId(): string;
+/**
+ * Where the WAV meets the recognizer's clock. From `wav_seconds` on, a result
+ * at stream time `t` sits at `wav_seconds + (t - stream_seconds)` in the WAV.
+ * Each socket the session opens starts its clock at zero, so a reconnect
+ * starts a new segment.
+ */
+export interface DictationStreamSegment {
+    wav_seconds: number;
+    stream_seconds: number;
+}
+/**
+ * Everything one dictation produced while the person spoke. Appends are copies
+ * and counters only, so feeding it from the audio callback and the session's
+ * events costs the dictation nothing; the record is built afterwards.
+ */
+export declare class DictationCapture {
+    readonly clientDictationId: string;
+    /** Epoch ms the dictation began (the person asked to dictate). */
+    readonly startedAt: number;
+    readonly sampleRate: number;
+    private readonly now;
+    private readonly maxAudioBytes;
+    private readonly audio;
+    private audioBytes;
+    private audioBytesDropped;
+    private readonly results;
+    private resultsBytes;
+    private resultsDropped;
+    private readonly marks;
+    private readonly segments;
+    private readonly resultSegments;
+    private resolveSettled;
+    private readonly settledPromise;
+    constructor({ clientDictationId, now, sampleRate, maxAudioSeconds, }?: {
+        clientDictationId?: string;
+        now?: () => number;
+        sampleRate?: number;
+        maxAudioSeconds?: number;
+    });
+    /** One chunk of mono 16-bit little-endian PCM, as handed to the session's `sendAudio`. */
+    addAudio(chunk: ArrayBuffer): void;
+    /** A final `Results` message as Deepgram sent it (the session's `final-result` event). */
+    addResult(message: unknown): void;
+    /** Records when `mark` happened; the first time wins. */
+    mark(mark: DictationMark, at?: number): void;
+    markedAt(mark: DictationMark): number | null;
+    /**
+     * Where the next chunk lands on the recognizer's clock: the session's
+     * `sentAudioSeconds` while its socket is open, `null` while the chunk waits
+     * for one. Call it before `addAudio`. A jump in the clock (a new socket)
+     * starts a new segment.
+     */
+    noteStreamPosition(streamSeconds: number | null): void;
+    get hasAudio(): boolean;
+    get audioSeconds(): number;
+    /** What the recognizer finalized, joined: the transcript before any edit or delivery. */
+    get finalTranscript(): string;
+    get finalResults(): readonly unknown[];
+    get audioChunks(): readonly ArrayBuffer[];
+    /** What the capture had to leave out to stay inside its bounds (empty when nothing). */
+    get truncation(): Record<string, number>;
+    get streamSegments(): readonly DictationStreamSegment[];
+    /** For each kept final result, the index of the stream segment it was heard on. */
+    get resultSegmentIndexes(): readonly number[];
+    /** The recognizer has flushed what it will say about this dictation (or it was superseded). */
+    settle(): void;
+    /** Resolves once settled, or after `timeoutMs` at the latest. */
+    whenSettled({ timeoutMs }: {
+        timeoutMs: number;
+    }): Promise<void>;
+}
+/**
+ * A RIFF/WAVE file of uncompressed 16-bit PCM around `chunks`: what agora
+ * stores for a dictation (lossless, never Opus or MP3).
+ */
+export declare function encodeDictationWav({ chunks, sampleRate, channels, }: {
+    chunks: readonly ArrayBuffer[];
+    sampleRate: number;
+    channels?: number;
+}): Uint8Array<ArrayBuffer>;
+/** Lowercase hex SHA-256, or `null` on a runtime without WebCrypto (Hermes). */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string | null>;
+/** Milliseconds each step took; `null` where the step never happened. */
+export interface DictationLatency {
+    /** Dictation start → the microphone producing audio. */
+    mic_start_ms: number | null;
+    /** Dictation start → the recognizer's stream open (≈0 for a warm one). */
+    stream_open_ms: number | null;
+    /** Dictation start → the first words on screen. */
+    first_result_ms: number | null;
+    /** The person stopping → the recognizer's last result. */
+    stop_to_final_ms: number | null;
+    /** The person stopping → the text delivered. */
+    stop_to_insert_ms: number | null;
+}
+/** The body of `PUT /api/dictations/{client_dictation_id}` (agora's `DictationUpsert`). */
+export interface DictationRecordBody {
+    workspace_id: string;
+    surface: DictationSurface;
+    client_app: string;
+    client_version: string;
+    client_platform: DictationClientPlatform;
+    client_os_version: string | null;
+    device_id: string | null;
+    started_at: string;
+    ended_at: string;
+    duration_ms: number;
+    mode: string;
+    stop_method: string | null;
+    outcome: string;
+    text: string;
+    raw_transcript: string | null;
+    /** `null`: agora counts the words of `text`. */
+    word_count: number | null;
+    language: string | null;
+    model: string | null;
+    stt_params: Record<string, unknown> | null;
+    transcript_results: unknown[] | null;
+    target_app_bundle_id: string | null;
+    target_app_name: string | null;
+    microphone_label: string | null;
+    latency: DictationLatency;
+    metadata: Record<string, unknown>;
+}
+/** A dictation ready to file: its JSON record and, when anything was heard, its WAV. */
+export interface DictationRecord {
+    clientDictationId: string;
+    body: DictationRecordBody;
+    wav: Uint8Array<ArrayBuffer> | null;
+}
+export interface DictationClient {
+    surface: DictationSurface;
+    app: string;
+    version: string;
+    platform: DictationClientPlatform;
+    osVersion?: string | null;
+    deviceId?: string | null;
+}
+/**
+ * The record agora stores for `capture`. `text` is what was delivered (or left
+ * on screen); the recognizer's own words go in `raw_transcript` and its final
+ * messages in `transcript_results`. Language and model come from the session's
+ * listen parameters (`DeepgramDictationSession.listenParams`); `stt_params` is
+ * `sttParams` when given (the session's whole request, its keyterms and
+ * replacements as lists: `DeepgramDictationSession.sttParams`), else them.
+ */
+export declare function buildDictationRecord({ capture, workspaceId, client, mode, stopMethod, outcome, text, listenParams, sttParams, targetAppBundleId, targetAppName, microphoneLabel, metadata, now, }: {
+    capture: DictationCapture;
+    workspaceId: string;
+    client: DictationClient;
+    mode: string;
+    stopMethod?: string | null;
+    outcome: string;
+    text: string;
+    listenParams?: Readonly<Record<string, string>>;
+    sttParams?: Readonly<Record<string, unknown>>;
+    targetAppBundleId?: string | null;
+    targetAppName?: string | null;
+    microphoneLabel?: string | null;
+    metadata?: Record<string, unknown>;
+    now?: () => number;
+}): DictationRecord;
+/**
+ * One request to agora's dictation routes. `path` is relative to the `/api/`
+ * root (`dictations/{id}`), so a host can hand it to a client already rooted there.
+ */
+export type DictationHttpRequest = {
+    kind: 'record';
+    path: string;
+    json: DictationRecordBody;
+} | {
+    kind: 'audio';
+    path: string;
+    wav: Uint8Array<ArrayBuffer>;
+    sha256: string | null;
+};
+/** The answer, whatever its status; a send that never got one throws. */
+export interface DictationHttpResponse {
+    status: number;
+    /** The `Retry-After` header, when the server sent one. */
+    retryAfter: string | null;
+    /** The parsed JSON body, when there was one. */
+    body: unknown;
+}
+export type DictationSend = (request: DictationHttpRequest) => Promise<DictationHttpResponse>;
+export type DictationUploadResult = {
+    status: 'stored';
+    audio: 'stored' | 'none';
+}
+/** Not stored yet and worth sending again later (offline, server busy, signed out). */
+ | {
+    status: 'retry_later';
+    recordStored: boolean;
+    httpStatus: number | null;
+}
+/** Agora refused it for good (a 4xx a retry cannot change). */
+ | {
+    status: 'refused';
+    step: 'record' | 'audio';
+    httpStatus: number;
+    recordStored: boolean;
+};
+export declare const dictationRecordPath: (clientDictationId: string) => string;
+export declare const dictationAudioPath: (clientDictationId: string) => string;
+/**
+ * Files `record`: the JSON record (an idempotent upsert keyed by its id), then
+ * its WAV. Each request is tried at most `maxAttempts` times, waiting the
+ * server's `Retry-After` (capped at 30 s) or a capped backoff between tries.
+ * `recordStored` skips a record an earlier call already stored. The same WAV
+ * sent again answers 200; a 409 (`audio_already_stored`: agora holds a
+ * different recording for this id, which it never replaces) is a refusal.
+ * Never throws.
+ */
+export declare function uploadDictationRecord({ record, send, recordStored, maxAttempts, sleep, backoffMs, }: {
+    record: DictationRecord;
+    send: DictationSend;
+    recordStored?: boolean;
+    maxAttempts?: number;
+    sleep?: (ms: number) => Promise<void>;
+    backoffMs?: (attempt: number) => number;
+}): Promise<DictationUploadResult>;
+interface FetchLikeResponse {
+    status: number;
+    headers: {
+        get: (name: string) => string | null;
+    };
+    text: () => Promise<string>;
+}
+export type DictationFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string | Uint8Array;
+}) => Promise<FetchLikeResponse>;
+/**
+ * A `DictationSend` over `fetch`, for a host without its own API client (the
+ * phone app). `baseUrl` is agora's origin; `headers` supplies auth per request.
+ */
+export declare function createFetchDictationSend({ baseUrl, headers, fetchImpl, }: {
+    baseUrl: string;
+    headers: () => Promise<Record<string, string>> | Record<string, string>;
+    fetchImpl?: DictationFetch;
+}): DictationSend;
+export {};

package/dist/agent-runtime/src/dictation-session.d.ts

@@ -57,6 +57,15 @@ export type DeepgramDictationEvent = {
     type: 'listened';
     until: number;
     audioSecondsSent: number;
+}
+/**
+ * A final `Results` message exactly as Deepgram sent it (this recording's, never a reset
+ * recording's tail), before the transcript event it produces: what a host keeps to file the
+ * dictation (`DictationCapture.addResult`, `./dictation-record`).
+ */
+ | {
+    type: 'final-result';
+    message: unknown;
 };
 type DeepgramDictationListener = (event: DeepgramDictationEvent) => void;
 export type DictationSocketLike = Pick<WebSocket, 'send' | 'close' | 'readyState' | 'binaryType'> & {
@@ -69,21 +78,72 @@ export interface CreateDictationSocketOptions {
     url: string;
     protocols: string[];
 }
-export interface DeepgramDictationSessionOptions {
+/** A find-and-replace Deepgram applies to the transcript; an empty `replace` removes what it finds. */
+export interface DictationStreamReplacement {
+    find: string;
+    replace: string;
+}
+/** What a session's sockets ask Deepgram for, beyond the fixed audio parameters. */
+export interface DictationListenOptions {
+    /** Extra Deepgram listen parameters (e.g. `language`, `utterance_end_ms`), one value each. */
+    listenParams?: Record<string, string>;
+    /** The person's dictionary, one repeated `keyterm` each, in order. */
+    keyterms?: readonly string[];
+    /** The person's replacements, one repeated `replace` each (`find` or `find:replacement`). */
+    replacements?: readonly DictationStreamReplacement[];
+    /**
+     * Voice lock: only the first speaker heard is kept. It reads Deepgram's speaker labels, so it
+     * goes with `diarize: 'true'`; results without labels pass through.
+     */
+    voiceLock?: boolean;
+}
+export interface DeepgramDictationSessionOptions extends DictationListenOptions {
     fetchToken: () => Promise<string>;
     /** Agora origin (http(s)) hosting the dictation relay, e.g. `CONFIG.serverUrl`. */
     serverUrl: string;
-    /** Extra Deepgram listen parameters (e.g. `keyterm`, `utterance_end_ms`), one value each. */
-    listenParams?: Record<string, string>;
     createSocket?: (options: CreateDictationSocketOptions) => DictationSocketLike;
     keepAliveIntervalMs?: number;
     idleCloseMs?: number;
     finalizeTimeoutMs?: number;
 }
-export declare function buildDictationStreamUrl({ serverUrl, listenParams, }: {
+/**
+ * The relay's URL: the fixed parameters and `listenParams`, then each keyterm as a repeated
+ * `keyterm` and each replacement as a repeated `replace`, `find` or `find:replacement` with each
+ * part percent-encoded and the separator a literal colon, the way Deepgram (and agora's relay,
+ * which refuses the whole stream for one value it does not take) reads it, so a colon inside a
+ * part survives.
+ */
+export declare function buildDictationStreamUrl({ serverUrl, listenParams, keyterms, replacements, }: {
     serverUrl: string;
     listenParams?: Record<string, string>;
+    keyterms?: readonly string[];
+    replacements?: readonly DictationStreamReplacement[];
 }): string;
+/** Voice lock locks onto a speaker once a final result gives them this many words. */
+export declare const VOICE_LOCK_MIN_WORDS = 3;
+/** A result's word with the speaker Deepgram labelled it with (`null` without `diarize`). */
+export interface SpeakerWord {
+    text: string;
+    speaker: number | null;
+}
+/**
+ * Voice lock (Hades' `applyVoiceLock`, as the desktop app runs it): the words of the locked
+ * speaker, as text. Until a speaker is locked an interim result shows nothing (the diarizer's
+ * interim labels are not settled), and a final result locks onto the speaker with the most words in
+ * it once they have `VOICE_LOCK_MIN_WORDS`; before that it is dropped, so background speech never
+ * leaks in ahead of the lock. Results without speaker labels pass through.
+ */
+export declare function voiceLocked({ result, lockedSpeaker, }: {
+    result: {
+        isFinal: boolean;
+        transcript: string;
+        words: readonly SpeakerWord[];
+    };
+    lockedSpeaker: number | null;
+}): {
+    text: string;
+    lockedSpeaker: number | null;
+};
 /**
  * Owns one browser -> Deepgram streaming socket for dictation.
  *
@@ -93,7 +153,22 @@ export declare function buildDictationStreamUrl({ serverUrl, listenParams, }: {
  */
 export declare class DeepgramDictationSession {
     private readonly fetchToken;
-    private readonly streamUrl;
+    private readonly serverUrl;
+    /** What the next socket opens with (`setListenOptions`). */
+    private streamUrl;
+    private configuredListenParams;
+    private keyterms;
+    private replacements;
+    private voiceLock;
+    /** The URL the socket now open (or opening) was opened with. */
+    private socketStreamUrl;
+    /**
+     * Whether the recording now running filters its results by voice lock: taken from the settings
+     * at each new recording and each new socket, so a change applies to the next dictation without
+     * a socket of its own (voice lock reads labels the stream already carries, or passes through).
+     */
+    private activeVoiceLock;
+    private lockedSpeaker;
     private readonly createSocket;
     private readonly keepAliveIntervalMs;
     private readonly idleCloseMs;
@@ -117,16 +192,40 @@ export declare class DeepgramDictationSession {
     private interimSegment;
     private listeners;
     status: DeepgramSocketStatus;
-    constructor({ fetchToken, serverUrl, listenParams, createSocket, keepAliveIntervalMs, idleCloseMs, finalizeTimeoutMs, }: DeepgramDictationSessionOptions);
+    constructor({ fetchToken, serverUrl, listenParams, keyterms, replacements, voiceLock, createSocket, keepAliveIntervalMs, idleCloseMs, finalizeTimeoutMs, }: DeepgramDictationSessionOptions);
+    /** The Deepgram listen parameters the session's sockets open with (one value each). */
+    get listenParams(): Readonly<Record<string, string>>;
+    /**
+     * What a dictation's record keeps of the request: every listen parameter, the keyterms as
+     * `keyterm` and the replacements as `replace` (lists), or `replace_count` when listing them would
+     * outgrow agora's bound on the record.
+     */
+    get sttParams(): Readonly<Record<string, unknown>>;
+    /**
+     * What the session's sockets ask for from now on (the person changed their settings). Never
+     * waits and never cuts a socket short: the socket open now keeps its parameters until the next
+     * `connect` replaces it (one still finishing a dictation's last words is kept until it is done),
+     * so a change applies to the next dictation.
+     */
+    setListenOptions({ listenParams, keyterms, replacements, voiceLock }: DictationListenOptions): void;
     get transcript(): string;
     /** Finalized results only, excluding the in-flight interim segment. */
     get finalizedTranscript(): string;
+    /**
+     * Seconds of audio the open socket has carried: where the next chunk sent on it starts on
+     * Deepgram's result clock. 0 while no socket is open (a socket's clock starts when it opens).
+     */
+    get sentAudioSeconds(): number;
     subscribe(listener: DeepgramDictationListener): () => void;
     /** Marks active demand: cancels the idle close and keeps the socket warm. */
     retain(): void;
     /** Ends active demand: flushes pending results and schedules the idle close. */
     release(): void;
-    /** Resolves once a socket is open. Reuses an open or opening socket. */
+    /**
+     * Resolves once a socket is open. Reuses an open or opening socket, unless the open one asks for
+     * what the person's settings no longer do: that one is replaced, once it has nothing left to
+     * finalize.
+     */
     connect(): Promise<void>;
     sendAudio(chunk: ArrayBuffer): void;
     /**

package/dist/agent-runtime/src/dictation-snippets.d.ts

@@ -0,0 +1,9 @@
+import { type DictationSnippet } from './dictation-preferences';
+/**
+ * `text` with every trigger said in it replaced by its snippet's text (above). The same `text`
+ * when there are no snippets or none was said.
+ */
+export declare function expandSnippets({ text, snippets, }: {
+    text: string;
+    snippets: readonly DictationSnippet[];
+}): string;

package/dist/agent-runtime/src/dictation-transfer.d.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { type DictationReplacement, type DictationSnippet } from './dictation-preferences';
+/**
+ * A person's dictionary, replacements and snippets in and out of Athena as a file, the same in
+ * every app that dictates (Settings ▸ Dictation ▸ Snippets on the web and on the desktop).
+ *
+ * Export is one JSON file of Athena's own (`DICTATION_EXPORT_FORMAT`). Import reads that file back,
+ * a plain list with one dictionary word per line, or a two-column CSV whose first row names its
+ * columns: `find,replace` for replacements, `trigger,text` for snippets. Nothing else is read as
+ * another app's export. An import only adds: what the lists already hold stays as it is (an entry
+ * already there, in any case for a replacement's find or a snippet's trigger, is not added again),
+ * nothing is removed, and the person is told what was added and what did not fit.
+ */
+export declare const DICTATION_EXPORT_FORMAT = "athena-dictation";
+export declare const DICTATION_EXPORT_VERSION = 1;
+/** The most a file to import may weigh (an export of every snippet at its longest fits). */
+export declare const DICTATION_IMPORT_MAX_BYTES: number;
+/** The most entries of each list a file is read for: past them, entries are counted, not read. */
+export declare const DICTATION_IMPORT_MAX_ENTRIES = 2000;
+/** The most entries a summary names, of each kind; the rest it counts. */
+export declare const DICTATION_IMPORT_MAX_NAMED = 20;
+/** The file kinds an import reads, by extension (each app's file picker offers them). */
+export declare const DICTATION_IMPORT_EXTENSIONS: readonly ['json', 'csv', 'txt'];
+/** The lists a file carries. */
+export interface DictationLists {
+    dictionary: readonly string[];
+    replacements: readonly DictationReplacement[];
+    snippets: readonly DictationSnippet[];
+}
+export declare const DictationList: {
+    readonly Dictionary: 'dictionary';
+    readonly Replacements: 'replacements';
+    readonly Snippets: 'snippets';
+};
+export type DictationList = (typeof DictationList)[keyof typeof DictationList];
+/** Athena's export: what a person keeps in each list, as JSON. */
+export declare function dictationExportOf({ lists, now }: {
+    lists: DictationLists;
+    now: Date;
+}): string;
+/** The export's file name: the day it was made, in the person's own time zone. */
+export declare function dictationExportFileName({ now }: {
+    now: Date;
+}): string;
+declare const EntryCountsSchema: z.ZodObject<{
+    dictionary: z.ZodNumber;
+    replacements: z.ZodNumber;
+    snippets: z.ZodNumber;
+}, z.core.$strip>;
+export type DictationEntryCounts = z.infer<typeof EntryCountsSchema>;
+/**
+ * A file read for import: the entries it offers each list (each once, as the lists keep them), the
+ * ones it holds that no list can keep as they are (empty, too long, or with a character agora
+ * refuses), named by a short label, and how many entries of each list it held past what is read.
+ */
+export declare const DictationImportSchema: z.ZodObject<{
+    dictionary: z.ZodArray<z.ZodString>;
+    replacements: z.ZodArray<z.ZodObject<{
+        find: z.ZodString;
+        replace: z.ZodString;
+    }, z.core.$strip>>;
+    snippets: z.ZodArray<z.ZodObject<{
+        trigger: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>>;
+    unusable: z.ZodArray<z.ZodString>;
+    unusableCount: z.ZodNumber;
+    extra: z.ZodObject<{
+        dictionary: z.ZodNumber;
+        replacements: z.ZodNumber;
+        snippets: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DictationImport = z.infer<typeof DictationImportSchema>;
+/** Why a file could not be read for import. */
+export declare const DictationImportRefusal: {
+    /** Not a file this reads: not Athena's export, a list or a CSV it can name the columns of. */
+    readonly NotReadable: 'not-readable';
+    /** A two-column CSV whose first row does not name its columns. */
+    readonly CsvColumns: 'csv-columns';
+    /** Nothing in it to import. */
+    readonly Empty: 'empty';
+    /** Heavier than `DICTATION_IMPORT_MAX_BYTES`. */
+    readonly TooLarge: 'too-large';
+};
+export type DictationImportRefusal = (typeof DictationImportRefusal)[keyof typeof DictationImportRefusal];
+/** What each app says when a file could not be read. */
+export declare const DICTATION_IMPORT_REFUSAL_WORDS: Readonly<Record<DictationImportRefusal, string>>;
+export type DictationImportReading = {
+    ok: true;
+    imported: DictationImport;
+} | {
+    ok: false;
+    refusal: DictationImportRefusal;
+};
+/**
+ * The file a person chose to import, read: by its extension (`.json` Athena's export, `.csv` a
+ * CSV, `.txt` a list), or by what it holds when the name says nothing (an object is the export, a
+ * first row naming `find,replace` or `trigger,text` a CSV, anything else a list).
+ */
+export declare function readDictationImport({ name, text, }: {
+    name: string;
+    text: string;
+}): DictationImportReading;
+/** What an import came to. */
+export interface DictationImportSummary {
+    added: DictationEntryCounts;
+    /** Entries a list already held (a replacement's find or a snippet's trigger in any case). */
+    alreadyThere: number;
+    /** Entries left out because their list is full: the first few named, all counted. */
+    full: Record<DictationList, {
+        named: string[];
+        count: number;
+    }>;
+    /** Entries no list can keep as they are: the first few named, all counted. */
+    unusable: {
+        named: string[];
+        count: number;
+    };
+}
+/** The lists as an app keeps them, which an import adds to. */
+export interface EditableDictationLists {
+    dictionary: string[];
+    replacements: DictationReplacement[];
+    snippets: DictationSnippet[];
+}
+/**
+ * `preferences` with what `imported` offers added at the end of each list, within each list's
+ * limit, and what that came to. Nothing already there is changed or removed.
+ */
+export declare function withImported<T extends EditableDictationLists>({ preferences, imported, }: {
+    preferences: T;
+    imported: DictationImport;
+}): {
+    preferences: T;
+    summary: DictationImportSummary;
+};
+/** What each app tells the person an import came to, a sentence a line. */
+export declare function dictationImportSummaryLines({ summary, }: {
+    summary: DictationImportSummary;
+}): string[];
+export {};