@hearthscale/app 0.2.4 → 0.4.0-rc.1

package/dist/index.d.ts

@@ -1,186 +1,3 @@
-/** Resolved publisher identity, independent of the model architecture.
- *  `GET /v1/publishers/{owner}/picture` answers the picture of the Hub
- *  user or organisation `repository` names first: its bytes as
- *  `image/png`, `image/jpeg`, `image/webp`, `image/gif` or
- *  `image/svg+xml`, with `cache-control: max-age=86400`. A 404
- *  `invalid_request` says no picture is known for the owner, and a 400
- *  `invalid_request` refuses a name that is not one Hub path segment of
- *  ASCII letters, digits, `-`, `_` and `.`. */
-interface ModelIdentity {
-    publisher: string;
-    /** The Hub repository whose publisher supplies the artwork; null for other sources. */
-    repository: string | null;
-}
-/** A job kind a model runs: the JSON Schema (draft-07) of its input, every
- *  object of it closed. A property of `"format": "asset"`, alone or as the
- *  items of an array, names a file by its asset id on the app's side,
- *  `contentMediaType` saying what it takes, and its `description` the
- *  limits the model sets on it; it reaches the Server as a `RenderUpload`
- *  in the same place. A property of `"format": "model"` names another
- *  model of the same Server by its card id; it reaches the Server as that
- *  model's id. A property's `default` is what the model's saved settings
- *  give a job that leaves it out. */
-interface JobSpec {
-    input: Record<string, unknown>;
-}
-/** The plan of a load or a media job against the memory as it stands, in
- *  MiB. A loaded model's process holds the graphics and system memory, and
- *  may fill the growth beside them as it keeps conversations ready; a
- *  job's process holds them at most while it runs. */
-interface MemoryPlan {
-    graphicsMib: number;
-    systemMib: number;
-    growthMib: number;
-    /** The graphics and system memory together, written as the words write
-     *  an amount of memory. */
-    takes: string;
-    /** The context a language model's load takes, shorter than its settings
-     *  ask where the memory free now holds no more; absent for a media job. */
-    contextTokens?: number;
-    /** Whether the broker takes the load or the job now: it starts at once,
-     *  or once the busy models and jobs it waits for finish. It is the check
-     *  a load or a job meets as it starts, on the memory free now, and the
-     *  catalogue says it changed when it does. */
-    ready: boolean;
-    /** The plan in words, or why the load cannot start now: the limit that
-     *  stops it, the system memory free or what Windows can still commit,
-     *  and what the person closes or changes. */
-    words: string;
-}
-interface DownloadProgressBytes {
-    receivedBytes: number;
-    totalBytes: number;
-}
-/** The order of a Discover search; trending first where `sort` names
- *  none. */
-type HubSort = 'trending' | 'downloads' | 'likes' | 'updated';
-/** One Hugging Face repository as Discover lists it: who published it, the
- *  model it quantises, how it is used, and what its header states of its
- *  size, its architecture and its window. */
-interface HubRepository {
-    identity: ModelIdentity;
-    formats: string[];
-    tasks: string[];
-    repo: string;
-    author: string;
-    /** The repository the weights were quantised from, where the card
-     *  names one. */
-    baseModel: string | null;
-    downloads: number;
-    likes: number;
-    /** A gated repository's files are read only with the Hugging Face token
-     *  the Server holds. */
-    gated: boolean;
-    updatedAt: string | null;
-    pipeline: string | null;
-    architecture: string | null;
-    params: number | null;
-    contextLength: number | null;
-    vision: boolean;
-    tools: boolean;
-    reasoning: boolean;
-}
-/** A file that can fill a companion role: where it is, how big it is, and
- *  whether its checksum is published. */
-interface CompanionOption {
-    repo: string;
-    path: string;
-    sizeBytes: number;
-    verifiable: boolean;
-    installed?: {
-        modelId: string;
-        path: string;
-        source: {
-            type: string;
-            repo: string;
-            revision: string;
-        };
-        sha256: string;
-        sizeBytes: number;
-    };
-    containsVision?: boolean;
-}
-/** A companion role of a candidate and the files that fill it. */
-interface CompanionRole {
-    role: string;
-    label: string;
-    options: CompanionOption[];
-    /** A gated base or encoder repository whose files this caller cannot read. */
-    gated?: string;
-}
-/** One file of a repository a pull can name: the whole shard set where it
- *  is a numbered shard, with the weights' projector beside it where the
- *  repository holds one. */
-interface HubCandidate {
-    /** The model id the pull makes, with the projector a lone one picks. */
-    id: string;
-    /** The name the pulled model goes by where no other model of the
-     *  library shares it, as `CatalogModel.label` names it. */
-    name: string;
-    path: string;
-    quantization: string;
-    /** Every byte the pull writes for this file, its set and its projector. */
-    sizeBytes: number;
-    engine: string;
-    /** Whether every byte of it publishes a checksum; a pull refuses the
-     *  rest by name rather than downloading them unverified. */
-    verifiable: boolean;
-    /** The files the repository supplies beside the weights. */
-    components: {
-        role: string;
-        label: string;
-        path: string;
-    }[];
-    /** Companion roles whose files the pull selects from compatible installed
-     *  components, the model's family or the encoder's own releases. */
-    requires: CompanionRole[];
-    /** The companion roles the model loads where a pull names a file for
-     *  them: `llm_vision`, the vision
-     *  part of a language model encoder, for a family that reads reference
-     *  pictures through it. */
-    offers: CompanionRole[];
-    /** Whether the repository holds vision projectors beside the file. */
-    projector: boolean;
-    /** The projectors to choose from where there is more than one, each
-     *  with the model id a pull with it makes. */
-    projectorOptions: {
-        path: string;
-        id: string;
-        sizeBytes: number;
-        verifiable: boolean;
-    }[];
-    /** The task the model serves, as `CatalogRole` names it. */
-    role: string;
-    format: string;
-    /** For an adapter: model ids from a Server, card ids from the platform. */
-    fits?: string[];
-    /** Why the file cannot be pulled, in the Server's words. */
-    reason?: string;
-}
-/** `GET /control/discover?task=&q=&sort=` answers the repositories of one
- *  task that `q` matches, or with no `q` the whole set, at most 30, as
- *  `HubRepository[]`; and `GET /control/discover/{owner}/{repo}` one
- *  repository as `HubListing`: the files a runtime of the Server runs, how
- *  many files it publishes in all, so a repository whose listing yields
- *  no candidate is one no runtime there runs, and every file a pull of
- *  another repository's model can name as a companion. Both read Hugging
- *  Face on a person's act and on nothing else, and with no token, so they
- *  reach the public repositories alone; the Server's own window reads the
- *  same answers from `/local/discover`, with the token the person stored. */
-interface HubListing {
-    repo: string;
-    model: HubRepository;
-    files: number;
-    candidates: HubCandidate[];
-    companions: CompanionOption[];
-    capabilities: {
-        vision: boolean;
-        tools: boolean;
-        reasoning: boolean;
-        tasks: string[];
-    };
-}
-
 /**
  * The platform half of the contract, generated from the Rust types of
  * the `contract` crate by `npm run contract` in `apps/platform/scripts`.
@@ -226,6 +43,12 @@ type Entry = {
     type: 'session.filing';
 } | {
     model?: string | null;
+    reasoning?: Reasoning | null;
+    /**
+     * The id of the index's place the agent's `file_search` reads in; with
+     * none it reads every place the app may read.
+     */
+    place?: string | null;
     type: 'session.settings';
 } | {
     to: string | null;
@@ -253,6 +76,11 @@ type Entry = {
      * block named them.
      */
     shown?: string;
+    /**
+     * The context window, in tokens, the turn planned its first
+     * request with.
+     */
+    window?: number;
     type: 'turn.started';
 } | {
     turn: string;
@@ -272,6 +100,20 @@ type Entry = {
     model: string;
     provider: string;
     error?: string;
+    /**
+     * Milliseconds from the request to the first streamed fragment of
+     * the reply: text, reasoning or a call.
+     */
+    firstTokenMs?: number;
+    /**
+     * The attempts of the round thrown away before this reply, oldest
+     * first.
+     */
+    retries?: Retry[];
+    /**
+     * The streamed calls that named no tool, left out of `toolCalls`.
+     */
+    dropped?: number;
     type: 'agent.message';
 } | {
     callId: string;
@@ -280,9 +122,13 @@ type Entry = {
      * The call this one runs under; absent for a call of the turn.
      */
     under?: string;
+    /**
+     * The name as the model wrote it.
+     */
     name: string;
     /**
-     * JSON-encoded, as the model emitted them.
+     * The arguments as the model wrote them: JSON-encoded, or the
+     * markup of a call written in the words of the reply.
      */
     arguments: string;
     context: CallContext;
@@ -291,6 +137,10 @@ type Entry = {
      * Absent for a core tool, and for a name that named no tool.
      */
     label?: CallLabel;
+    /**
+     * How the call runs, where the model wrote it out of form.
+     */
+    repaired?: Repaired;
     type: 'call.prepared';
 } | {
     callId: string;
@@ -426,6 +276,10 @@ type Entry = {
     watermark: string;
     rounds: number;
     type: 'compaction.cleared';
+} | {
+    callId: string;
+    chars: number;
+    type: 'compaction.clipped';
 } | {
     tailStart: string;
     summary: string;
@@ -488,7 +342,7 @@ type RootKind = 'home' | 'workspace' | 'project' | 'memory' | 'skill' | 'folder'
  */
 type PermissionLevel = 'manual' | 'auto' | 'skip' | 'bypass';
 type ModelLocation = 'local' | 'lan' | 'cloud';
-type StopReason = ('end_turn' | 'length' | 'budget' | 'cancelled' | 'error' | 'refused' | 'app_disabled' | 'app_update' | 'interrupted') | 'no_result';
+type StopReason = ('end_turn' | 'length' | 'budget' | 'cancelled' | 'error' | 'refused' | 'app_disabled' | 'app_update' | 'interrupted') | 'no_result' | 'repeated';
 /**
  * A part of a user message.
  */
@@ -550,6 +404,14 @@ type AgentPart = {
     kind: 'reasoning';
 };
 type AgentStop = 'end_turn' | 'tool_calls' | 'length' | 'cancelled' | 'error' | 'refused' | 'interrupted';
+/**
+ * Why an attempt was sent again: its reply held no words and no call, the
+ * provider failed in a way that passes before any token, the request did
+ * not fit the runtime's window, or, and the attempt sent again carried a
+ * reminder, the reply announced a step and made no call, or it stated
+ * figures that nothing it was given holds and no program ran in the turn.
+ */
+type RetryReason = 'empty' | 'transient' | 'overflow' | 'announced' | 'figures';
 /**
  * A transcript mark an app's manifest names for a tool.
  */
@@ -612,15 +474,20 @@ type EnvironmentKind = 'process' | 'vm';
  * manifest's order, placed in the rail or a tab: a `web` surface's own
  * page, or the web page of a view's tab. `navigate` loads an address in
  * the session's tab, opening it when the session has none, hidden for a
- * view's tab; `evaluate` runs a script and answers its value;
- * `screenshot` answers the page as an asset; `show` puts the tab in front
- * of the person; `close` ends it.
+ * view's tab; `evaluate` runs a script and answers its value; `click`
+ * presses the left button at a point of the page's viewport, in its CSS
+ * pixels; `type` types text into the element with focus; `press` presses
+ * a key or a combination such as `Control+a`, but none that pastes, since
+ * a page may not read the clipboard; `screenshot` answers the page as an
+ * asset; `show` puts the tab in front of the person; `close` ends it. The
+ * page receives `click`, `type` and `press` as the person's own input,
+ * which its scripts cannot tell apart from a person's.
  */
-type SurfaceOp = 'navigate' | 'evaluate' | 'screenshot' | 'show' | 'close';
+type SurfaceOp = 'navigate' | 'evaluate' | 'click' | 'type' | 'press' | 'screenshot' | 'show' | 'close';
 /**
  * One setting's value.
  */
-type SettingValue = string | number | boolean;
+type SettingValue = string | number | boolean | string[];
 /**
  * What a model card answers on, and what a job runs: a role word of
  *         the runtimes, such as chat, embedding, image or transcription.
@@ -683,7 +550,6 @@ type NetworkEntry = string;
  */
 type ListenPort = number;
 type Lifetime = 'service';
-type Reasoning = 'none' | 'auto' | 'high';
 /**
  * A relative path inside the package, forward slashes, never leaving it.
  */
@@ -722,6 +588,7 @@ type TriggerDeclaration = {
     name: string;
     keys?: string;
     hold?: boolean;
+    armed?: boolean;
     kind: 'hotkey';
 } | {
     name: string;
@@ -800,13 +667,12 @@ type SystemEvent = 'idle' | 'active' | 'lock' | 'unlock' | 'sleep' | 'wake' | 'p
  * `events`, `models`, `jobs` and `peers` alike, each only when its app
  * names it here. An agent's core tools need no namespace here.
  */
-type Uses = ('sessions' | 'sessions.create' | 'secrets' | 'notifications' | 'readers' | 'roots' | 'exec' | 'catalogue' | 'surface' | 'store' | 'db' | 'events' | 'models' | 'jobs' | 'terminals' | 'files.open' | 'surfaces.open' | 'peers' | 'index' | 'capture.microphone' | 'capture.system-sound' | 'capture.program-sound' | 'capture.screen' | 'capture.window' | 'capture.camera' | 'desktop.context' | 'desktop.actions') | 'net.ask' | 'desktop.overlay' | 'input.controller' | 'system.state';
+type Uses = ('sessions' | 'sessions.create' | 'secrets' | 'notifications' | 'readers' | 'roots' | 'exec' | 'catalogue' | 'surface' | 'store' | 'db' | 'events' | 'models' | 'jobs' | 'terminals' | 'files.open' | 'surfaces.open' | 'peers' | 'index' | 'capture.microphone' | 'capture.system-sound' | 'capture.program-sound' | 'capture.screen' | 'capture.window' | 'capture.camera' | 'desktop.context' | 'desktop.actions') | 'net.ask' | 'desktop.around' | 'desktop.overlay' | 'input.controller' | 'system.state';
 /**
- * The model an introduction card downloads on this computer's Server: one
- * its catalogue lists, by the id its device row gives it, or a file of a
- * Hugging Face repository.
+ * The model an introduction card downloads on this computer's Server: a
+ * file of a Hugging Face repository, or the best model of a kind.
  */
-type OnboardingDownload = string | HubFile;
+type OnboardingDownload = HubFile | BestModel;
 /**
  * What a surface is: `view`, an MCP Apps document in a sandboxed frame,
  * which may reserve slots for the chat the shell draws for the app's own
@@ -952,6 +818,22 @@ type SettingDeclaration = {
     minLength?: number;
     maxLength?: number;
     pattern?: string;
+    /**
+     * The tool that lists the values to pick from, for a list only the
+     * computer knows, such as its microphones. It is called with `{}` and
+     * answers `{ options: [{ value, label }] }`. The page calls it with no
+     * press, so it is one the app declares, its views may call, and that
+     * neither changes anything nor reaches out.
+     */
+    optionsFrom?: string;
+    /**
+     * The field takes several lines.
+     */
+    multiline?: boolean;
+    /**
+     * What the empty field shows.
+     */
+    placeholder?: string;
     /**
      * The value the platform holds until the person changes it.
      */
@@ -991,19 +873,56 @@ type SettingDeclaration = {
      */
     default: number;
     type: 'integer';
+} | {
+    /**
+     * The setting's label.
+     */
+    title: string;
+    /**
+     * The tooltip of the setting's row.
+     */
+    description?: string;
+    items: ListSettingItems;
+    maxItems?: number;
+    /**
+     * What the empty field shows.
+     */
+    placeholder?: string;
+    /**
+     * The value the platform holds until the person changes it.
+     */
+    default: string[];
+    type: 'array';
 };
 /**
- * One row of a settings group: a setting by its name, or a button that
- * calls one of the app's tools with `{}`. A tool whose result names a view
- * opens that view in a modal over the settings; any other shows its text
- * in a tooltip of the button.
+ * The one type a list setting's entries have.
+ */
+type StringType = 'string';
+/**
+ * One row of a settings group: a setting by its name, with a button at the
+ * end of its row where it names one, or a button alone. A button calls one of
+ * the app's tools with `{}`. A tool whose result names a view opens that view
+ * in a modal over the settings; any other shows its text in a tooltip of the
+ * button.
  */
 type SettingsItem = {
     property: string;
+    /**
+     * The row shows only while another setting holds a value.
+     */
+    when?: SettingsWhen;
+    /**
+     * The buttons beside the setting's control, in their order. A list or a
+     * field of several lines fills its row and takes none.
+     *
+     * @minItems 1
+     */
+    actions?: SettingsAction[];
     kind: 'property';
 } | {
     tool: string;
     title: string;
+    confirm?: SettingsConfirm;
     kind: 'tool';
 };
 /**
@@ -1057,7 +976,7 @@ type CompletionOption = 'logprobs' | 'topLogprobs' | 'topK' | 'minP' | 'grammar'
  * The kinds of model an app's Discover search lists, each a `HubTask` word
  * of the inference contract. Draft weights and upscalers have none.
  */
-type DiscoverTask = 'text' | 'image' | 'transcription' | 'diarization' | 'separation' | 'speech' | 'music' | 'embedding' | 'rerank' | 'adapter' | 'all';
+type DiscoverTask = 'text' | 'image' | 'video' | 'transcription' | 'diarization' | 'separation' | 'speech' | 'music' | 'embedding' | 'rerank' | 'adapter' | 'all';
 /**
  * What an app asks to install on a Hearthscale Server: a card a Server
  * lists and does not hold, by its id, or a file of a Hugging Face
@@ -1164,6 +1083,11 @@ type ResourceWriteResult = {
  * commit with its first parent.
  */
 type VcsScope = 'working' | 'staged' | 'branch' | 'commit';
+/**
+ * The parts of a search: the words of the passages and the names of the
+ * files, the meanings, and the rerank model's order of the best.
+ */
+type IndexLeg = 'words' | 'vectors' | 'rerank';
 /**
  * What a transcription stream tells an app's backend: the open
  * segment's text so far, a segment's final text with its start and end in
@@ -1177,6 +1101,10 @@ type ListenEvent = {
     stream: string;
     index: number;
     text: string;
+    /**
+     * The words after `text` that may still change.
+     */
+    tentative?: string;
     type: 'partial';
 } | {
     stream: string;
@@ -1205,7 +1133,7 @@ type NoticeAction = {
     title: string;
     id: string;
 };
-type HotkeyPhase = 'pressed' | 'released';
+type HotkeyPhase = ('pressed' | 'released') | 'cancelled';
 type DeviceEvent = 'connected' | 'removed';
 type PowerSource = 'ac' | 'battery';
 /**
@@ -1301,7 +1229,8 @@ interface ToolCall {
     id: string;
     name: string;
     /**
-     * JSON-encoded arguments exactly as the model emitted them.
+     * JSON-encoded arguments. A reply the log keeps holds each call as it
+     * runs; its `call.prepared` keeps what the model wrote.
      */
     arguments: string;
 }
@@ -1312,8 +1241,20 @@ interface ToolCall {
 interface Usage {
     input: number;
     output: number;
+    /**
+     * The tokens of `output` the model spent reasoning, where the runtime
+     * states them.
+     */
+    reasoning?: number;
     estimated?: true;
 }
+/**
+ * An attempt of a round that was thrown away and sent again, and when.
+ */
+interface Retry {
+    reason: RetryReason;
+    at: string;
+}
 /**
  * What every tool call, session write and job carries: who acts, where
  * the words came from, and the chain of principals the call crossed,
@@ -1346,6 +1287,20 @@ interface CallSource {
     id: string;
     name: string;
 }
+/**
+ * A call the model wrote out of form, as it runs: the tool's name where
+ * the model wrote it in another case or with `-` for `_`, and the
+ * arguments read as a JSON object of the types the tool's schema names.
+ * `written` marks a call written in the words of the reply.
+ */
+interface Repaired {
+    name: string;
+    /**
+     * JSON-encoded.
+     */
+    arguments: string;
+    written?: true;
+}
 interface Executor {
     principal: PrincipalRef;
     instance: string;
@@ -1441,6 +1396,15 @@ interface AskFacts {
      */
     label?: string;
     arguments?: string;
+    /**
+     * On a card of an app's or a connector's tool: what the call would do,
+     * in one sentence the utility model wrote once the card was open.
+     */
+    plain?: string;
+    /**
+     * The utility model is still writing `plain`.
+     */
+    writing?: true;
     /**
      * The absolute path a file call would touch.
      */
@@ -1493,9 +1457,10 @@ interface AskFacts {
         [k: string]: unknown;
     };
     /**
-     * A connector card: the connector, and the tools waiting on a bulk
-     * card, or the sign-in's issuer, or the device code the person types
-     * at the verification address. An app's sign-in card carries the
+     * A connector card: the connector by its id, with the name the person
+     * knows it or its app by in `sourceName`, and the tools waiting on a
+     * bulk card, or the sign-in's issuer, or the device code the person
+     * types at the verification address. An app's sign-in card carries the
      * issuer, the scopes, and the code or the sign-in a window starts
      * with the authorization endpoint its browser opens.
      */
@@ -1731,7 +1696,13 @@ interface Manifest {
      * Semver, shown and never interpreted.
      */
     version: string;
-    api: 6;
+    api: 7;
+    /**
+     * The lowest Hearthscale version the package runs on. A Hearthscale
+     * of a lower version refuses the package, and the Marketplace offers
+     * it the newest release it meets.
+     */
+    hearthscale?: string;
     description: string;
     icon?: Schemed;
     license?: string;
@@ -1860,6 +1831,11 @@ interface ModelRequirement {
      */
     recommend?: string[];
     sampling?: Sampling;
+    /**
+     * The level the agent's turns think at; a level the person picks for
+     * a conversation goes over it on a model that lists two or more
+     * levels.
+     */
     reasoning?: Reasoning;
 }
 interface Sampling {
@@ -1880,6 +1856,17 @@ interface Budget {
  */
 interface ModelNeed {
     required: boolean;
+    /**
+     * The setting that holds the device this kind of model hears, which its
+     * test on the app's page opens.
+     */
+    input?: string;
+    /**
+     * The tool that says which of a search's models the app recommends: it takes
+     * `{ languages, models }` and answers `{ recommended: [{ repo, word }] }`, the
+     * one it recommends most first. It runs with no press.
+     */
+    recommend?: string;
     /**
      * The Hugging Face tasks the kind's card states, every one of them.
      *
@@ -2070,6 +2057,14 @@ interface InstalledCompanionSource {
     repo: string;
     revision: string;
 }
+/**
+ * The model of a kind that the app's own tool recommends, where its manifest
+ * names one, else the first recommended for the user's device, else
+ * the first of a search, found when the card opens.
+ */
+interface BestModel {
+    best: ModelKind;
+}
 /**
  * A right-click entry of the app's rail button: a call of one of the
  * app's tools with these arguments, `{}` when absent. A result that names
@@ -2102,6 +2097,13 @@ interface SettingsSchema {
         [k: string]: SettingDeclaration;
     };
 }
+/**
+ * The entries of a list setting: strings, each at most `maxLength` long.
+ */
+interface ListSettingItems {
+    type: StringType;
+    maxLength?: number;
+}
 interface SettingsGroup {
     title: string;
     /**
@@ -2109,6 +2111,29 @@ interface SettingsGroup {
      */
     items: SettingsItem[];
 }
+/**
+ * A setting and the value that shows a row.
+ */
+interface SettingsWhen {
+    property: string;
+    is: unknown;
+}
+/**
+ * A button beside a setting's control.
+ */
+interface SettingsAction {
+    tool: string;
+    title: string;
+    confirm?: SettingsConfirm;
+}
+/**
+ * What a button asks before it runs its tool, for a press that cannot be undone.
+ * The answer that goes ahead carries the button's own title.
+ */
+interface SettingsConfirm {
+    title: string;
+    body: string;
+}
 interface Mentions {
     tool: string;
 }
@@ -2216,6 +2241,11 @@ interface ModelCard {
      * states them.
      */
     tasks?: string[];
+    /**
+     * What a transcription model's card and file state about it, where its
+     * provider states it.
+     */
+    speech?: SpeechFacts;
     vision?: boolean;
     tools?: boolean;
     /**
@@ -2223,6 +2253,21 @@ interface ModelCard {
      * states it.
      */
     reasoning?: boolean;
+    /**
+     * The levels the model thinks at, least first, where its provider
+     * states them.
+     *
+     * Items: How much a model thinks before it answers, least first: `none` is Off and
+     * `max` thinks with no limit. A model that lacks a level runs at the
+     * nearest one it has, the higher of two as near. The inference contract's
+     * `Reasoning`: a Server's `reasoning_effort` takes the same words.
+     */
+    reasoningLevels?: Reasoning[];
+    /**
+     * The level the model thinks at when a request names none, where its
+     * provider states it.
+     */
+    reasoningLevel?: Reasoning;
     /**
      * The job kinds the card runs, by kind word, each with the input it
      * takes.
@@ -2256,23 +2301,60 @@ interface ModelCard {
      */
     reason?: string;
     /**
-     * What loading the card's model, or a job of it, takes now, where a
-     * Server plans it.
+     * What loading the card's model, or a job of it, takes now, where a
+     * Server plans it.
+     */
+    memory?: MemoryPlan;
+    /**
+     * How much of a downloading card's model has arrived, where its
+     * Server reports it.
+     */
+    progress?: DownloadProgressBytes;
+    /**
+     * For an adapter whose Server states them, the cards of the models it fits.
+     */
+    fits?: string[];
+    /**
+     * For an adapter whose Server states them, its prompt trigger words.
+     */
+    triggers?: string[];
+    /**
+     * The name of a licence that limits commercial use, where a Server's
+     * recommendation states one.
+     */
+    limitingLicense?: string;
+    /**
+     * How an embedding card's inputs are written, where its Server's
+     * recommendation states it; a card that states none takes its texts
+     * as they are.
+     */
+    embedding?: Embedding;
+}
+/**
+ * How an embedding model's inputs are written. Each template holds
+ * `{text}` where the text goes, and a document's `{title}` where the
+ * document's title goes; a template ends with the model's end token where
+ * its file's tokenizer adds none.
+ */
+interface Embedding {
+    /**
+     * A search's words.
      */
-    memory?: MemoryPlan;
+    query: string;
     /**
-     * How much of a downloading card's model has arrived, where its
-     * Server reports it.
+     * A passage of a document with a title.
      */
-    progress?: DownloadProgressBytes;
+    document: string;
     /**
-     * For an adapter whose Server states them, the cards of the models it fits.
+     * A passage of a document with no title, where it is not `document`
+     * with an empty title.
      */
-    fits?: string[];
+    untitled?: string;
     /**
-     * For an adapter whose Server states them, its prompt trigger words.
+     * The length its vectors are cut to, where it is used shorter than it
+     * embeds.
      */
-    triggers?: string[];
+    dimensions?: number;
 }
 /**
  * A Hearthscale Server this computer names, as `ctx.models.servers` and
@@ -2299,6 +2381,11 @@ interface HubSearch {
      * The order of a Discover search: the inference contract's `HubSort`.
      */
     sort?: HubSort;
+    /**
+     * The short codes of the languages a speech model must hear, with commas
+     * between them.
+     */
+    language?: string;
 }
 /**
  * A file of a Hugging Face repository to install on a Hearthscale Server,
@@ -2402,6 +2489,12 @@ interface CompletionRequest {
      */
     format?: CompletionFormat;
     sampling?: Sampling;
+    /**
+     * How much a model thinks before it answers, least first: `none` is Off and
+     * `max` thinks with no limit. A model that lacks a level runs at the
+     * nearest one it has, the higher of two as near. The inference contract's
+     * `Reasoning`: a Server's `reasoning_effort` takes the same words.
+     */
     reasoning?: Reasoning;
     /**
      * Asks for the same answer to the same request as far as the runtime
@@ -2435,6 +2528,10 @@ interface ChatMessage {
     content: ChatContent;
     toolCalls?: ToolCall[];
     toolCallId?: string;
+    /**
+     * The reasoning of a reply of the turn the request continues.
+     */
+    reasoning?: string;
 }
 /**
  * One tool as a model sees it.
@@ -2667,6 +2764,16 @@ interface Session {
      * The card the next turn uses, when a person chose one.
      */
     model?: string;
+    /**
+     * The level the next turn thinks at, when a person chose one and the
+     * model lists two or more levels.
+     */
+    reasoning?: Reasoning;
+    /**
+     * The id of the index's place the agent's `file_search` reads in, when a
+     * person chose one.
+     */
+    place?: string;
     createdAt: string;
     updatedAt: string;
     status: SessionStatus;
@@ -2893,15 +3000,76 @@ interface IndexPage {
 }
 /**
  * One answer of a search of the shared index: the passage, the document
- * it came from and its page, and how well it answers the query.
+ * it came from and its page, and how well it answers the query. A
+ * passage of a file in a place has the file's absolute path as its
+ * source and the place's id; a file that answers by its name alone has
+ * a line of its name, folder, size and date as its text.
  */
 interface IndexHit {
+    /**
+     * Names the passage while it is in the index.
+     */
+    id: string;
     source: string;
     title?: string;
     page?: number;
+    /**
+     * What a person calls the page, such as `Slide 4` or a sheet's name.
+     */
+    label?: string;
+    /**
+     * The first and the last line of the passage on its page, from 1.
+     */
+    start?: number;
+    end?: number;
+    place?: string;
     text: string;
     score: number;
 }
+/**
+ * The body of `POST /index/search`: a search of every place the caller
+ * may read, the person's reach for a window and the app's for a view.
+ */
+interface IndexSearchRequest {
+    query: string;
+    /**
+     * Ten when none is named.
+     */
+    limit?: number;
+    legs?: IndexLegs;
+    /**
+     * The id of the one place to search in.
+     */
+    place?: string;
+    /**
+     * The query is a phrase a passage holds word for word; only the words
+     * leg runs.
+     */
+    phrase?: boolean;
+}
+/**
+ * The legs a search runs; a search with none named runs each.
+ */
+interface IndexLegs {
+    words: boolean;
+    vectors: boolean;
+    rerank: boolean;
+}
+/**
+ * The answer of a search: its hits, best first, and each leg it could
+ * not run.
+ */
+interface IndexSearch {
+    hits: IndexHit[];
+    unavailable: IndexUnavailable[];
+}
+/**
+ * A leg the search was asked to run and could not, with the reason.
+ */
+interface IndexUnavailable {
+    leg: IndexLeg;
+    reason: string;
+}
 /**
  * One enabled app as `apps.list` lists it.
  */
@@ -2995,9 +3163,10 @@ interface AppSkill {
 interface HotkeyState {
     name: string;
     /**
-     * The keys that fire the hotkey now, the person's or else the
-     * declared ones; none where neither names any, or where another
-     * app's hotkey holds them.
+     * The keys the hotkey names, the person's or else the declared ones;
+     * none where neither names any, or where another app's hotkey holds
+     * them. A hotkey declared with `armed: false` fires them only while
+     * its backend arms it.
      */
     keys?: string;
     /**
@@ -3236,6 +3405,236 @@ interface MediaKeyPress {
     key: MediaKey;
 }
 
+/**
+ * What a Server asks Hearthscale's api about models and what it answers:
+ * the models that suit one computer, best first for each kind, with the
+ * exact files of each. The Server keeps the last answer on disk.
+ */
+
+/** A model's licence: its name, and whether it is open for commercial use. */
+interface OfferedLicense {
+    name: string;
+    commercial: boolean;
+}
+
+/**
+ * Control: the first-party half of the inference contract — everything the
+ * OpenAI shape cannot express. Served by the Server (`hearthd`) beside the
+ * generation routes.
+ */
+
+/** How much a model thinks before it answers, least first, as a chat
+ *  request's `reasoning_effort` names it: `none` is Off and `max` thinks
+ *  with no limit. A model that lacks a level runs at the nearest one it
+ *  has, the higher of two as near. */
+type Reasoning = 'none' | 'low' | 'medium' | 'high' | 'max';
+/** Resolved publisher identity, independent of the model architecture.
+ *  `GET /v1/publishers/{owner}/picture` answers the picture of the Hub
+ *  user or organisation `repository` names first: its bytes as
+ *  `image/png`, `image/jpeg`, `image/webp`, `image/gif` or
+ *  `image/svg+xml`, with `cache-control: max-age=86400`. A 404
+ *  `invalid_request` says no picture is known for the owner, and a 400
+ *  `invalid_request` refuses a name that is not one Hub path segment of
+ *  ASCII letters, digits, `-`, `_` and `.`. */
+interface ModelIdentity {
+    publisher: string;
+    /** The Hub repository whose publisher supplies the artwork; null for other sources. */
+    repository: string | null;
+}
+/** What a transcription model's card and file state about it. A list is empty,
+ *  and a field null, where neither says. */
+interface SpeechFacts {
+    /** The languages it hears, by their short codes. */
+    languages: string[];
+    /** The percent of words, or of characters in a language written without
+     *  spaces, its publisher measured wrong on a public test set, by language. */
+    errors: Record<string, number>;
+    /** How long 30 s of speech took on a graphics device, as its publisher measured
+     *  it on the reference computer most like its Server. */
+    seconds: number | null;
+    /** The same on the processor. */
+    processorSeconds: number | null;
+    /** It writes English from another language. */
+    translates: boolean | null;
+    /** It tells the language by itself. */
+    detects: boolean | null;
+}
+/** A job kind a model runs: the JSON Schema (draft-07) of its input, every
+ *  object of it closed. A property of `"format": "asset"`, alone or as the
+ *  items of an array, names a file by its asset id on the app's side,
+ *  `contentMediaType` saying what it takes, and its `description` the
+ *  limits the model sets on it; it reaches the Server as a `RenderUpload`
+ *  in the same place. A property of `"format": "model"` names another
+ *  model of the same Server by its card id; it reaches the Server as that
+ *  model's id. A property's `default` is what the model's saved settings
+ *  give a job that leaves it out. */
+interface JobSpec {
+    input: Record<string, unknown>;
+}
+/** The plan of a load or a media job against the memory as it stands, in
+ *  MiB. A loaded model's process holds the graphics and system memory, and
+ *  may fill the growth beside them as it keeps conversations ready; a
+ *  job's process holds them at most while it runs. */
+interface MemoryPlan {
+    graphicsMib: number;
+    systemMib: number;
+    growthMib: number;
+    /** The graphics and system memory together, written as the words write
+     *  an amount of memory. */
+    takes: string;
+    /** The context a language model's load takes, shorter than its settings
+     *  ask where the memory free now holds no more; absent for a media job. */
+    contextTokens?: number;
+    /** Whether the broker takes the load or the job now: it starts at once,
+     *  or once the busy models and jobs it waits for finish. It is the check
+     *  a load or a job meets as it starts, on the memory free now, and the
+     *  catalogue says it changed when it does. */
+    ready: boolean;
+    /** The plan in words, or why the load cannot start now: the limit that
+     *  stops it, the system memory free or what Windows can still commit,
+     *  and what the person closes or changes. */
+    words: string;
+}
+interface DownloadProgressBytes {
+    receivedBytes: number;
+    totalBytes: number;
+}
+/** The order of a Discover search; trending first where `sort` names
+ *  none. */
+type HubSort = 'trending' | 'downloads' | 'likes' | 'updated';
+/** One Hugging Face repository as Discover lists it: who published it, the
+ *  model it quantises, how it is used, and what its header states of its
+ *  size, its architecture and its window. */
+interface HubRepository {
+    identity: ModelIdentity;
+    formats: string[];
+    tasks: string[];
+    repo: string;
+    author: string;
+    /** The repository the weights were quantised from, where the card
+     *  names one. */
+    baseModel: string | null;
+    downloads: number;
+    likes: number;
+    /** A gated repository's files are read only with the Hugging Face token
+     *  the Server holds. */
+    gated: boolean;
+    updatedAt: string | null;
+    pipeline: string | null;
+    architecture: string | null;
+    params: number | null;
+    contextLength: number | null;
+    vision: boolean;
+    tools: boolean;
+    reasoning: boolean;
+    /** What a speech model's card states about it. */
+    speech: SpeechFacts | null;
+}
+/** A file that can fill a companion role: where it is, how big it is, and
+ *  whether its checksum is published. */
+interface CompanionOption {
+    repo: string;
+    path: string;
+    sizeBytes: number;
+    verifiable: boolean;
+    installed?: {
+        modelId: string;
+        path: string;
+        source: {
+            type: string;
+            repo: string;
+            revision: string;
+        };
+        sha256: string;
+        sizeBytes: number;
+    };
+    containsVision?: boolean;
+    /** The licence the recommendations state for a usual part of a family. */
+    license?: OfferedLicense;
+}
+/** A companion role of a candidate and the files that fill it. */
+interface CompanionRole {
+    role: string;
+    label: string;
+    options: CompanionOption[];
+    /** A gated base or encoder repository whose files this caller cannot read. */
+    gated?: string;
+}
+/** One file of a repository a pull can name: the whole shard set where it
+ *  is a numbered shard, with the weights' projector beside it where the
+ *  repository holds one. */
+interface HubCandidate {
+    /** The model id the pull makes, with the projector a lone one picks. */
+    id: string;
+    /** The name the pulled model goes by where no other model of the
+     *  library shares it, as `CatalogModel.label` names it. */
+    name: string;
+    path: string;
+    quantization: string;
+    /** Every byte the pull writes for this file, its set and its projector. */
+    sizeBytes: number;
+    engine: string;
+    /** Whether every byte of it publishes a checksum; a pull refuses the
+     *  rest by name rather than downloading them unverified. */
+    verifiable: boolean;
+    /** The files the repository supplies beside the weights. */
+    components: {
+        role: string;
+        label: string;
+        path: string;
+    }[];
+    /** Companion roles whose files the pull selects from compatible installed
+     *  components, the model's family or the encoder's own releases. */
+    requires: CompanionRole[];
+    /** The companion roles the model loads where a pull names a file for
+     *  them: `llm_vision`, the vision
+     *  part of a language model encoder, for a family that reads reference
+     *  pictures through it. */
+    offers: CompanionRole[];
+    /** Whether the repository holds vision projectors beside the file. */
+    projector: boolean;
+    /** The projectors to choose from where there is more than one, each
+     *  with the model id a pull with it makes. */
+    projectorOptions: {
+        path: string;
+        id: string;
+        sizeBytes: number;
+        verifiable: boolean;
+    }[];
+    /** The task the model serves, as `CatalogRole` names it. */
+    role: string;
+    format: string;
+    /** For an adapter: model ids from a Server, card ids from the platform. */
+    fits?: string[];
+    /** Why the file cannot be pulled, in the Server's words. */
+    reason?: string;
+}
+/** `GET /control/discover?task=&q=&sort=` answers the repositories of one
+ *  task that `q` matches, or with no `q` the whole set, at most 30, as
+ *  `HubRepository[]`; and `GET /control/discover/{owner}/{repo}` one
+ *  repository as `HubListing`: the files a runtime of the Server runs, how
+ *  many files it publishes in all, so a repository whose listing yields
+ *  no candidate is one no runtime there runs, and every file a pull of
+ *  another repository's model can name as a companion. Both read Hugging
+ *  Face on a person's act and on nothing else, and with no token, so they
+ *  reach the public repositories alone; the Server's own window reads the
+ *  same answers from `/local/discover`, with the token the person stored. */
+interface HubListing {
+    repo: string;
+    model: HubRepository;
+    files: number;
+    /** The path of the file a press takes, where one can be taken. */
+    fileToTake: string | null;
+    candidates: HubCandidate[];
+    companions: CompanionOption[];
+    capabilities: {
+        vision: boolean;
+        tools: boolean;
+        reasoning: boolean;
+        tasks: string[];
+    };
+}
+
 /**
  * The view bridge: what a view, an app's UI in a sandboxed frame, and its
  * host say to each other beyond the MCP Apps standard the view speaks.
@@ -3470,8 +3869,8 @@ interface HostSlot {
     project?: string;
     /** On a `chat` or `composer` slot: false draws the composer with no
      *  model picker, for an app whose models are chosen only on its page in
-     *  Settings; the rest of the composer's footer keeps its place. Absent,
-     *  the composer shows the picker. */
+     *  Settings; the thinking level and the rest of the composer's footer
+     *  keep their places. Absent, the composer shows the picker. */
     modelPicker?: boolean;
     /** On a `terminal` slot: the folder its shell starts in, inside a folder
      *  the person gave the view's app. The slot's id, letters, digits, `-`
@@ -3514,6 +3913,15 @@ type HostSlotNotification =
         session: string | null;
     };
 }
+/** The person asked to go back or forward in the tab, whose web page has
+ *  loaded none. Every view that fills a tab hears it, with or without a
+ *  slot, and moves through its own places. */
+ | {
+    method: 'hearthscale/ui/history';
+    params: {
+        direction: 'back' | 'forward';
+    };
+}
 /** The tab's web page changed: its address, title, icon, load, history
  *  or zoom. Sent once when the view starts and at each change. */
  | {
@@ -4313,6 +4721,17 @@ interface ViewExtensionMethods {
             servers: ModelServer[];
         };
     };
+    /** The cards Hearthscale recommends of a kind, best first and in every
+     *  state, this computer's own Server first. */
+    'hearthscale/models/recommended': {
+        uses: 'models';
+        params: {
+            kind: ModelKind;
+        };
+        result: {
+            cards: ModelCard[];
+        };
+    };
     /** A search of a Server's Discover: the public Hugging Face
      *  repositories of `task` that `search` matches, as that Server answers
      *  it. Needs a click, as it reads Hugging Face. */
@@ -4500,6 +4919,15 @@ interface ViewExtensionMethods {
         };
         result: Empty;
     };
+    /** A search of the device's file index: the documents the app put and
+     *  the files of every place the app may read now, or of the one place
+     *  `place` names; the hits best first, and each leg that could not run
+     *  with the reason. */
+    'hearthscale/index/search': {
+        uses: 'index';
+        params: IndexSearchRequest;
+        result: IndexSearch;
+    };
 }
 type ViewExtensionMethod = keyof ViewExtensionMethods;
 /** The notifications the host sends a view, each only to a view whose app
@@ -4712,8 +5140,8 @@ type CapturedPart = {
     width: number;
     height: number;
 };
-/** A transcription stream. The Server cuts the sound at pauses, and
- *  each part becomes a segment. */
+/** A transcription stream. The sound is cut at pauses unless `pauses` is
+ *  false, and each part becomes a segment. */
 interface Listening {
     readonly id: string;
     /** 16 kHz mono 16-bit little-endian PCM, at most 10 s at a time, such
@@ -4959,11 +5387,15 @@ interface AppContext {
             root: string;
             path?: string;
         }): Promise<boolean>;
-        /** With a hotkey trigger: the keys that fire each of the app's
-         *  hotkeys now, the person's or else the declared ones, so the app
-         *  can show them; `keys` is absent where none are set or another
-         *  app's hotkey holds them, which `takenBy` names. */
+        /** With a hotkey trigger: the keys of each of the app's hotkeys, the
+         *  person's or else the declared ones, so the app can show them;
+         *  `keys` is absent where none are set or another app's hotkey holds
+         *  them, which `takenBy` names. A hotkey declared with `armed: false`
+         *  fires its keys only while `arm` holds them. */
         hotkeys: {
+            /** Makes a hotkey declared with `armed: false` hold its keys, or lets
+             *  them go: at every other moment they reach the program in front. */
+            arm(name: string, on: boolean): Promise<void>;
             list(): Promise<HotkeyState[]>;
             /** Hears a move of the keys of any of them, with every one as
              *  `list` answers it. */
@@ -4997,7 +5429,9 @@ interface AppContext {
          *  taken in milliseconds since the Unix epoch on the computer that
          *  captures, the clock every capture there shares: a part's moment is
          *  `startedAt + at`. Sound comes as 16 kHz mono 16-bit PCM in parts of
-         *  half a second, one after another, silence included; the screen, a window and the camera as a JPEG
+         *  half a second, or `part` ms from 50 to 500 for the microphone and
+         *  the computer's sound, one after another, silence included; the last
+         *  part may be shorter; the screen, a window and the camera as a JPEG
          *  picture every `interval` ms (1000 unless named, at least 250), the
          *  screen cut to `region` when named. `device` names a device of
          *  `devices`; a window and a program need one. `echo` takes the
@@ -5016,6 +5450,7 @@ interface AppContext {
             };
             echo?: boolean;
             keep?: boolean;
+            part?: number;
         }): Promise<{
             capture: string;
             startedAt: number;
@@ -5034,10 +5469,21 @@ interface AppContext {
         }) => void): () => void;
     };
     /** Other programs on the person's computer: what they show, with
-     *  `desktop.context`, and typing into the one in front, with
-     *  `desktop.actions`. */
+     *  `desktop.context`, the text around the cursor, with `desktop.around`,
+     *  and typing into the one in front, with `desktop.actions`. */
     desktop: {
         context(): Promise<DesktopContext>;
+        /** With `desktop.around`: the text around the cursor of the focused field
+         *  in the program in front, up to 1024 characters each way. A password
+         *  field gives no text and answers `password: true`. Null where the
+         *  program does not tell it, or a Hearthscale window has the focus
+         *  anywhere but in a view of this app. */
+        around(): Promise<{
+            before: string;
+            selected: string;
+            after: string;
+            password?: true;
+        } | null>;
         /** Calls `on('change')` with each change from now on, and keeps the
          *  backend up. */
         watch(): Promise<void>;
@@ -5046,12 +5492,21 @@ interface AppContext {
         on(event: 'ended', fn: (ended: {
             reason: string;
         }) => void): () => void;
+        /** The window in front now, to name to `type` or `paste`, which then
+         *  refuse once another window is in front. Null where the system names no
+         *  window, as Wayland does: the text then goes to whichever window has the
+         *  focus. */
+        front(): Promise<string | null>;
         /** Types the text into the focused field of the program in front. */
-        type(text: string): Promise<void>;
+        type(text: string, options?: {
+            front?: string | null;
+        }): Promise<void>;
         /** Pastes the text there through the clipboard, which it restores. */
-        paste(text: string): Promise<void>;
-        /** Presses each combination in turn, such as `ctrl+a` or `enter`: a
-         *  key with `ctrl`, `shift`, `alt` or `meta` before it. */
+        paste(text: string, options?: {
+            front?: string | null;
+        }): Promise<void>;
+        /** Presses each combination in turn, at most 200, such as `ctrl+a` or
+         *  `enter`: a key with `ctrl`, `shift`, `alt` or `meta` before it. */
         keys(keys: string[]): Promise<void>;
     };
     /** With `input.controller`: the person's game controllers, read also
@@ -5120,8 +5575,8 @@ interface AppContext {
             reason: string;
         }) => void): () => void;
     };
-    /** With `index` in `uses`: the shared index, where the app finds again
-     *  what it put and the text files of the places it watches. */
+    /** With `index` in `uses`: the device's index, where the app finds
+     *  again what it put and the files of every place it may read. */
     index: {
         /** Puts a document in place of what was put under its source;
          *  answers how many passages it holds. */
@@ -5129,14 +5584,15 @@ interface AppContext {
         /** Answers whether there was a document under the source. */
         remove(source: string): Promise<boolean>;
         /** The passages that best answer the query, best first; ten unless
-         *  a limit is named. */
+         *  a limit is named. A passage of a file has the file's absolute path
+         *  as its source. */
         search(query: string, limit?: number): Promise<IndexHit[]>;
-        /** Indexes every text file at or under a path of a mount, under the
-         *  source `file:<mount>/<path>`, and again whenever one changes, also
-         *  after a restart while the app may read the path. */
+        /** Asks for a folder of a mount as a place of the device's index:
+         *  the person sees it among the places, and every app that may read
+         *  it finds its files. The place stays while the app may read it. */
         watch(path: MountPath): Promise<void>;
-        /** Stops a watch and removes what it indexed; answers whether there
-         *  was one. */
+        /** Lets go of a place the app asked for; answers whether it had
+         *  asked. The place goes once nobody holds it. */
         unwatch(path: MountPath): Promise<boolean>;
     };
     /** With `notifications` in `uses`: a system notification. A press
@@ -5225,6 +5681,11 @@ interface AppContext {
             task?: string;
             state?: CardState;
         }): Promise<ModelList>;
+        /** The cards Hearthscale recommends of a kind for each Server's computer,
+         *  best first and in every state, this computer's own Server first. A card
+         *  a Server does not hold yet goes to `install` by its id. Empty where a
+         *  Server has no answer. */
+        recommended(kind: ModelKind): Promise<ModelCard[]>;
         /** The Hearthscale Servers this app may install on: this computer's
          *  first, then each paired one, with whether each serves now. */
         servers(): Promise<ModelServer[]>;
@@ -5269,15 +5730,28 @@ interface AppContext {
          *  the reason none can: this app's, or another app's under the
          *  `sessions.create` grant. */
         effective(kind: ModelKind, app?: string): Promise<EffectiveModel>;
+        /** The languages the person speaks to this app, as short codes, as they
+         *  chose them on its page; empty where they chose none. */
+        languages(): Promise<string[]>;
         /** Opens a stream on the transcription card `model` names, or else on
          *  the app's transcription model, which runs on a Hearthscale Server:
          *  the sound written in goes out as text while it is spoken. Rejects
-         *  when the model is not on a Server. `words` are hint words, such as
-         *  names, for a model whose engine takes them. */
+         *  when the model is not on a Server. `words` are names and terms the
+         *  sound holds, which an engine that takes hints favours and the text of
+         *  any other is corrected to. `aliases` names, for a term, what the model
+         *  may write for it. With `pauses: false`, a pause ends no segment, and
+         *  one segment runs until `end`. `translate` writes English on a model
+         *  that translates, or not, over the setting the person saved on the
+         *  model; any other model writes what it hears. `filterSilence` leaves
+         *  out the sound that holds no voice. */
         listen(options?: {
             language?: string;
             model?: string;
             words?: string[];
+            aliases?: Record<string, string[]>;
+            pauses?: boolean;
+            translate?: boolean;
+            filterSilence?: boolean;
         }): Promise<Listening>;
     };
     /** With `sessions.create`: the projects of an app this one may start