@hearthscale/app 0.3.0 → 0.4.0-rc.1

package/dist/index.d.ts

@@ -1,228 +1,3 @@
-/**
- * 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.
- */
-
-/** 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 platform half of the contract, generated from the Rust types of
  * the `contract` crate by `npm run contract` in `apps/platform/scripts`.
@@ -268,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;
@@ -295,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;
@@ -314,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;
@@ -322,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;
@@ -333,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;
@@ -468,6 +276,10 @@ type Entry = {
     watermark: string;
     rounds: number;
     type: 'compaction.cleared';
+} | {
+    callId: string;
+    chars: number;
+    type: 'compaction.clipped';
 } | {
     tailStart: string;
     summary: string;
@@ -530,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.
  */
@@ -592,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.
  */
@@ -654,11 +474,16 @@ 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.
  */
@@ -725,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.
  */
@@ -1259,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
@@ -1400,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;
 }
@@ -1411,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,
@@ -1445,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;
@@ -1841,6 +1697,12 @@ interface Manifest {
      */
     version: string;
     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;
@@ -1969,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 {
@@ -2386,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.
@@ -2441,6 +2323,38 @@ interface ModelCard {
      * 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.
+     */
+    query: string;
+    /**
+     * A passage of a document with a title.
+     */
+    document: string;
+    /**
+     * A passage of a document with no title, where it is not `document`
+     * with an empty title.
+     */
+    untitled?: string;
+    /**
+     * The length its vectors are cut to, where it is used shorter than it
+     * embeds.
+     */
+    dimensions?: number;
 }
 /**
  * A Hearthscale Server this computer names, as `ctx.models.servers` and
@@ -2575,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
@@ -2608,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.
@@ -2837,9 +2761,19 @@ interface Session {
     title: string;
     preview: string;
     /**
-     * The card the next turn uses, when a person chose one.
+     * 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.
      */
-    model?: string;
+    place?: string;
     createdAt: string;
     updatedAt: string;
     status: SessionStatus;
@@ -3066,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.
  */
@@ -3410,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.
@@ -3644,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, `-`
@@ -4694,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
@@ -5341,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. */
@@ -5350,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hearthscale/app",
-  "version": "0.3.0",
+  "version": "0.4.0-rc.1",
   "description": "The types a Hearthscale app's backend and views import: the backend's exports and context, the view's host methods, extensions and slots; and the typed call of a view's requests.",
   "license": "MIT",
   "type": "module",
@@ -39,7 +39,7 @@
     "rollup": "^4.62.2",
     "rollup-plugin-dts": "^6.5.1",
     "typescript": "^5.6.3",
-    "@hearthscale/contract": "0.3.0"
+    "@hearthscale/contract": "0.4.0-rc.1"
   },
   "scripts": {
     "build": "node scripts/build.mjs",